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