1<?php
2
3/* Copyright (c) 2017 Richard Klees <richard.klees@concepts-and-training.de> Extended GPL, see docs/LICENSE */
4
5namespace ILIAS\UI\Component\Input\Field;
6
7use ILIAS\UI\Component\Component;
8use ILIAS\Transformation\Transformation;
9use ILIAS\Validation\Constraint;
10
11/**
12 * This describes commonalities between all inputs.
13 *
14 * Inputs are different from other UI components. They bundle two things:
15 * the displaying of the component (as the other components do as well)
16 * and the processing of data as it is received from the client.
17 *
18 * There are two types of input fields, individual and groups. They share
19 * this same basic input interface.
20 *
21 * When the the term "value" is used, it references the content of the input
22 * as it is shown to the client. The term "content" on the other hand means
23 * the value that is contained in the input after the client sends it to the
24 * server.
25 *
26 * The latter, i.e. the content, can be validated via constraints and transformed
27 * into other types of data. This means, that e.g. the value of an input could
28 * be some id, while the content could be some object referenced by that id.
29 */
30interface Input extends Component
31{
32
33    /**
34     * Get the label of the input.
35     *
36     * @return    string
37     */
38    public function getLabel();
39
40
41    /**
42     * Get an input like this, but with a replaced label.
43     *
44     * @param    string $label
45     *
46     * @return    Input
47     */
48    public function withLabel($label);
49
50
51    /**
52     * Get the byline of the input.
53     *
54     * @return    string|null
55     */
56    public function getByline();
57
58
59    /**
60     * Get an input like this, but with an additional/replaced label.
61     *
62     * @param    string|null $byline
63     *
64     * @return    Input
65     */
66    public function withByline($byline);
67
68
69    /**
70     * Is this field required?
71     *
72     * @return    bool
73     */
74    public function isRequired();
75
76
77    /**
78     * Get an input like this, but set the field to be required (or not).
79     *
80     * @param    bool $is_required
81     *
82     * @return    Input
83     */
84    public function withRequired($is_required);
85
86
87    /**
88     * Get the value that is displayed in the input client side.
89     *
90     * @return    mixed
91     */
92    public function getValue();
93
94
95    /**
96     * Get an input like this with another value displayed on the
97     * client side.
98     *
99     * @param    mixed
100     *
101     * @throws  \InvalidArgumentException    if value does not fit client side input
102     * @return Input
103     */
104    public function withValue($value);
105
106
107    /**
108     * The error of the input as used in HTML.
109     *
110     * @return string|null
111     */
112    public function getError();
113
114
115    /**
116     * Get an input like this one, with a different error.
117     *
118     * @param    string
119     *
120     * @return    Input
121     */
122    public function withError($error);
123
124
125    /**
126     * Apply a transformation to the content of the input.
127     *
128     * @param    Transformation $trafo
129     *
130     * @return    Input
131     */
132    public function withAdditionalTransformation(Transformation $trafo);
133
134
135    /**
136     * Apply a constraint to the content of the input.
137     *
138     * @param    Constraint $constraint
139     *
140     * @return    Input
141     */
142    public function withAdditionalConstraint(Constraint $constraint);
143}
144