]>
Commit | Line | Data |
---|---|---|
4f5b44bd NL |
1 | <?php |
2 | ||
3 | /* | |
4 | * This file is part of the Symfony package. | |
5 | * | |
6 | * (c) Fabien Potencier <fabien@symfony.com> | |
7 | * | |
8 | * For the full copyright and license information, please view the LICENSE | |
9 | * file that was distributed with this source code. | |
10 | */ | |
11 | ||
12 | namespace Symfony\Component\Form\Extension\Core\ChoiceList; | |
13 | ||
14 | /** | |
15 | * Contains choices that can be selected in a form field. | |
16 | * | |
17 | * Each choice has three different properties: | |
18 | * | |
19 | * - Choice: The choice that should be returned to the application by the | |
20 | * choice field. Can be any scalar value or an object, but no | |
21 | * array. | |
22 | * - Label: A text representing the choice that is displayed to the user. | |
23 | * - Value: A uniquely identifying value that can contain arbitrary | |
24 | * characters, but no arrays or objects. This value is displayed | |
25 | * in the HTML "value" attribute. | |
26 | * | |
27 | * @author Bernhard Schussek <bschussek@gmail.com> | |
28 | */ | |
29 | interface ChoiceListInterface | |
30 | { | |
31 | /** | |
32 | * Returns the list of choices | |
33 | * | |
34 | * @return array The choices with their indices as keys | |
35 | */ | |
36 | public function getChoices(); | |
37 | ||
38 | /** | |
39 | * Returns the values for the choices | |
40 | * | |
41 | * @return array The values with the corresponding choice indices as keys | |
42 | */ | |
43 | public function getValues(); | |
44 | ||
45 | /** | |
46 | * Returns the choice views of the preferred choices as nested array with | |
47 | * the choice groups as top-level keys. | |
48 | * | |
49 | * Example: | |
50 | * | |
51 | * <source> | |
52 | * array( | |
53 | * 'Group 1' => array( | |
54 | * 10 => ChoiceView object, | |
55 | * 20 => ChoiceView object, | |
56 | * ), | |
57 | * 'Group 2' => array( | |
58 | * 30 => ChoiceView object, | |
59 | * ), | |
60 | * ) | |
61 | * </source> | |
62 | * | |
63 | * @return array A nested array containing the views with the corresponding | |
64 | * choice indices as keys on the lowest levels and the choice | |
65 | * group names in the keys of the higher levels | |
66 | */ | |
67 | public function getPreferredViews(); | |
68 | ||
69 | /** | |
70 | * Returns the choice views of the choices that are not preferred as nested | |
71 | * array with the choice groups as top-level keys. | |
72 | * | |
73 | * Example: | |
74 | * | |
75 | * <source> | |
76 | * array( | |
77 | * 'Group 1' => array( | |
78 | * 10 => ChoiceView object, | |
79 | * 20 => ChoiceView object, | |
80 | * ), | |
81 | * 'Group 2' => array( | |
82 | * 30 => ChoiceView object, | |
83 | * ), | |
84 | * ) | |
85 | * </source> | |
86 | * | |
87 | * @return array A nested array containing the views with the corresponding | |
88 | * choice indices as keys on the lowest levels and the choice | |
89 | * group names in the keys of the higher levels | |
90 | * | |
91 | * @see getPreferredValues | |
92 | */ | |
93 | public function getRemainingViews(); | |
94 | ||
95 | /** | |
96 | * Returns the choices corresponding to the given values. | |
97 | * | |
98 | * The choices can have any data type. | |
99 | * | |
100 | * @param array $values An array of choice values. Not existing values in | |
101 | * this array are ignored | |
102 | * | |
103 | * @return array An array of choices with ascending, 0-based numeric keys | |
104 | */ | |
105 | public function getChoicesForValues(array $values); | |
106 | ||
107 | /** | |
108 | * Returns the values corresponding to the given choices. | |
109 | * | |
110 | * The values must be strings. | |
111 | * | |
112 | * @param array $choices An array of choices. Not existing choices in this | |
113 | * array are ignored | |
114 | * | |
115 | * @return array An array of choice values with ascending, 0-based numeric | |
116 | * keys | |
117 | */ | |
118 | public function getValuesForChoices(array $choices); | |
119 | ||
120 | /** | |
121 | * Returns the indices corresponding to the given choices. | |
122 | * | |
123 | * The indices must be positive integers or strings accepted by | |
124 | * {@link FormConfigBuilder::validateName()}. | |
125 | * | |
126 | * The index "placeholder" is internally reserved. | |
127 | * | |
128 | * @param array $choices An array of choices. Not existing choices in this | |
129 | * array are ignored | |
130 | * | |
131 | * @return array An array of indices with ascending, 0-based numeric keys | |
132 | */ | |
133 | public function getIndicesForChoices(array $choices); | |
134 | ||
135 | /** | |
136 | * Returns the indices corresponding to the given values. | |
137 | * | |
138 | * The indices must be positive integers or strings accepted by | |
139 | * {@link FormConfigBuilder::validateName()}. | |
140 | * | |
141 | * The index "placeholder" is internally reserved. | |
142 | * | |
143 | * @param array $values An array of choice values. Not existing values in | |
144 | * this array are ignored | |
145 | * | |
146 | * @return array An array of indices with ascending, 0-based numeric keys | |
147 | */ | |
148 | public function getIndicesForValues(array $values); | |
149 | } |