1<?php 2 3/* Copyright (c) 2016 Richard Klees <richard.klees@concepts-and-training.de> Extended GPL, see docs/LICENSE */ 4 5namespace ILIAS\UI\Component\Button; 6 7use ILIAS\UI\Component\Signal; 8 9/** 10 * This is how a factory for buttons looks like. 11 */ 12interface Factory 13{ 14 /** 15 * --- 16 * description: 17 * purpose: > 18 * The standard button is the default button to be used in ILIAS. If 19 * there is no good reason using another button instance in ILIAS, this 20 * is the one that should be used. 21 * composition: > 22 * The standard button uses the primary color as background. 23 * effect: > 24 * If the loading animation is activated, the button shows a spinner wheel 25 * on-click and automatically switches to a deactivated state. 26 * 27 * rules: 28 * usage: 29 * 1: > 30 * Standard buttons MUST be used if there is no good reason using 31 * another instance. 32 * 2: > 33 * The loading animation SHOULD be activated if the Buttons starts 34 * any background process (e.g. ajax calls) without any other immediate 35 * feedback for the user. After the process finished, the button MUST be 36 * removed from/replaced in the DOM. 37 * ordering: 38 * 1: > 39 * The most important standard button SHOULD be first in reading 40 * direction if there are several buttons. 41 * 2: > 42 * In the toolbar and in forms special regulations for the ordering 43 * of the buttons MAY apply. 44 * responsiveness: 45 * 1: > 46 * The most important standard button in multi-action bars MUST be 47 * sticky (stay visible on small screens). 48 * accessibility: 49 * 1: > 50 * Standard buttons MAY define aria-label attribute. Use it in cases 51 * where a text label is not visible on the screen or when the label 52 * does not provide enough information about the action. 53 * 2: > 54 * Some Buttons can be stateful; when engaged, the state MUST be 55 * reflected in the "aria-pressed"-, respectively the "aria-checked"-attribute. 56 * If the Button is not stateful (which is the default), the 57 * aria-attribute SHOULD be omitted. 58 * --- 59 * @param string $label 60 * @param string|Signal $action will be triggered on click 61 * @return \ILIAS\UI\Component\Button\Standard 62 */ 63 public function standard($label, $action); 64 65 /** 66 * --- 67 * description: 68 * purpose: > 69 * The primary button indicates the most important action on a screen. 70 * By definition there can only be one single “most important” action 71 * on any given screen and thus only one single primary button per screen. 72 * composition: > 73 * The background color is the btn-primary-color. This screen-unique 74 * button-color ensures that it stands out and attracts the user’s 75 * attention while there are several buttons competing for attention. 76 * effect: > 77 * In toolbars the primary button are required to be sticky, meaning 78 * they stay in view in the responsive view. If the loading animation 79 * is activated, the button shows a spinner wheel on-click and automatically 80 * switches to a deactivated state. 81 * 82 * background: > 83 * Tiddwell refers to the primary button as “prominent done button” and 84 * describes that “the button that finishes a transaction should be 85 * placed at the end of the visual flow; and is to be made big and well 86 * labeled.” She explains that “A well-understood, obvious last step 87 * gives your users a sense of closure. There’s no doubt that the 88 * transaction will be done when that button is clicked; don’t leave 89 * them hanging, wondering whether their work took effect”. 90 * 91 * The GNOME Human Interface Guidelines -> Buttons also describes a 92 * button indicated as most important for dialogs. 93 * 94 * context: 95 * - “Start test” in Module “Test” 96 * - “Hand In” in exercise 97 * 98 * rules: 99 * usage: 100 * 1: > 101 * Most pages SHOULD NOT have any Primary Button at all. 102 * 2: > 103 * There MUST be no more than one Primary Button per page in ILIAS. 104 * 3: > 105 * The decision to make a Button a Primary Button MUST be confirmed 106 * by the JF. 107 * 4: > 108 * The loading animation rules of the Standard Button MUST be respected. 109 * accessibility: 110 * 1: > 111 * Some Buttons can be stateful; when engaged, the state MUST be 112 * reflected in the "aria-pressed"-, respectively the "aria-checked"-attribute. 113 * If the Button is not stateful (which is the default), the 114 * aria-attribute SHOULD be omitted. 115 * 116 * --- 117 * @param string $label 118 * @param string|Signal $action will be triggered on click 119 * @return \ILIAS\UI\Component\Button\Primary 120 */ 121 public function primary($label, $action); 122 123 /** 124 * --- 125 * description: 126 * purpose: > 127 * The close button triggers the closing of some collection displayed 128 * temporarily such as an overlay. 129 * composition: > 130 * The close button is displayed without border. 131 * effect: > 132 * Clicking the close button closes the enclosing collection. 133 * 134 * rules: 135 * ordering: 136 * 1: > 137 * The Close Button MUST always be positioned in the top right of a 138 * collection. 139 * accessibility: 140 * 1: > 141 * The functionality of the close button MUST be indicated for screen 142 * readers by an aria-label. 143 * --- 144 * @return \ILIAS\UI\Component\Button\Close 145 */ 146 public function close(); 147 148 /** 149 * --- 150 * description: 151 * purpose: > 152 * Shy buttons are used in contexts that need a less obtrusive presentation 153 * than usual buttons have, e.g. in UI collections like Dropdowns. 154 * composition: > 155 * Shy buttons do not come with a separte background color. 156 * 157 * rules: 158 * usage: 159 * 1: > 160 * Shy buttons MUST only be used, if a standard button presentation 161 * is not appropriate. E.g. if usual buttons destroy the presentation 162 * of an outer UI component or if there is not enough space for a 163 * standard button presentation. 164 * --- 165 * @param string $label 166 * @param string|Signal $action will be triggered on click 167 * @return \ILIAS\UI\Component\Button\Shy 168 */ 169 public function shy($label, $action); 170 171 /** 172 * --- 173 * description: 174 * purpose: > 175 * The Month Button enables to select a specific month to fire some action (probably a change of view). 176 * composition: > 177 * The Month Button is composed of a Button showing the default month directly (probably the 178 * month currently rendered by some view). A dropdown contains an interface enabling the selection of a month from 179 * the future or the past. 180 * effect: > 181 * Selecting a month from the dropdown directly fires the according action (e.g. switching the view to the 182 * selected month). Technically this is currently a Javascript event being fired. 183 * 184 * context: 185 * - Marginal Grid Calendar 186 * 187 * rules: 188 * interaction: 189 * 1: > 190 * Selecting a month from the dropdown MUST directly fire the according action. 191 * 192 * --- 193 * @param string $default Initial value, use format "mm-yyyy". 194 * @return \ILIAS\UI\Component\Button\Month 195 */ 196 public function month($default); 197 198 /** 199 * --- 200 * description: 201 * purpose: > 202 * Tags classify entities. Thus, their primary purpose is the visualization 203 * of those classifications for one entity. However, tags are usually 204 * clickable - either to edit associations or list related entities, 205 * i.e. objects with the same tag. 206 * composition: > 207 * Tags are a colored area with text on it. 208 * When used in a tag-cloud (a list of tags), tags can be visually "weighted" 209 * according to the number of their occurences, be it with different 210 * (font-)sizes, different colors or all of them. 211 * effect: > 212 * Tags may trigger an action or change the view when clicked. 213 * There is no visual difference (besides the cursor) between 214 * clickable tags and tags with unavailable action. 215 * 216 * 217 * rules: 218 * style: 219 * 1: Tags SHOULD be used with an additonal class to adjust colors. 220 * 2: > 221 * The font-color SHOULD be set with high contrast to the chosen 222 * background color. 223 * accessibility: 224 * 1: > 225 * The functionality of the tag button MUST be indicated for screen 226 * readers by an aria-label. 227 * --- 228 * @param string $label 229 * @param string|Signal $action will be triggered on click 230 * @return \ILIAS\UI\Component\Button\Tag 231 */ 232 public function tag($label, $action); 233 234 /** 235 * --- 236 * description: 237 * purpose: > 238 * The bulky button is highly obtrusive. It combines the recognisability 239 * of a graphical element with an explicit textual label on an unusually 240 * sized button. It is hard to overlook and indicates an important action 241 * on the screen. 242 * 243 * composition: > 244 * The Bulky Button consists of an icon or glyph and a (very short) text. 245 * 246 * effect: > 247 * The button has an "engaged"-state: When the button is used to toggle the 248 * visibility of a component, it stays engaged until the component is hidden again. 249 * 250 * rivals: 251 * Primary Button: > 252 * Primary Buttons indicate the most important action among a collection 253 * of actions, e.g. in a tool bar, controls of a form or in a modal. Bulky 254 * Buttons make it hard to miss the indicated action by occupying space. 255 * 256 * rules: 257 * usage: 258 * 1: > 259 * Since Bulky Buttons are so obtrusive they MUST only be used 260 * to indicate important actions on the screen. 261 * wording: 262 * 1: The icon/glyph and the text on the Bulky Button MUST be corresponding. 263 * style: 264 * 1: > 265 * Bulky Buttons MUST occupy as much space as their container 266 * leaves them. 267 * 2: > 268 * When used to toggle the visibility of another component, the button 269 * MUST reflect the componentes state of visibility. 270 * responsiveness: 271 * 1: > 272 * On screens larger than small size, Bulky Buttons MUST contain an icon or glyph plus text. 273 * 2: > 274 * On small-sized screens, Bulky Buttons SHOULD contain only an icon or glyph. 275 * accessibility: 276 * 1: > 277 * The functionality of the Bulky Button MUST be indicated for screen 278 * readers by an aria-label. 279 * 2: > 280 * Some Buttons can be stateful; when engaged, the state MUST be 281 * reflected in the "aria-pressed"-, respectively the "aria-checked"-attribute. 282 * If the Button is not stateful (which is the default), the 283 * aria-attribute SHOULD be omitted. 284 * 285 * --- 286 * @param \ILIAS\UI\Component\Symbol\Icon\Icon | \ILIAS\UI\Component\Symbol\Glyph\Glyph $icon_or_glyph 287 * @param string $label 288 * @param string $action 289 * @return \ILIAS\UI\Component\Button\Bulky 290 */ 291 public function bulky($icon_or_glyph, $label, $action); 292 293 /** 294 * --- 295 * description: 296 * purpose: > 297 * The Toggle Button triggers the activation/deactivation of some control already shown on the screen, i.e. 298 * a filter. The deactivation of a control means, that it is still shown and the user can still interact 299 * with it, but it has no effect on the system. 300 * composition: > 301 * The Toggle Button uses different background colors for the on and off state. 302 * The toggle of the Toggle Button is placed on the left side when it is off, and on the right side 303 * when it is on. 304 * effect: > 305 * Clicking the Toggle Button activates/deactivates the related control. The on/off state of the control 306 * is visually noticeable for the user, i.e. by greying out the control in the off state. 307 * rivals: 308 * Checkbox: > 309 * Checkboxes are established as controls for choosing a value for submission and are therefore handled as Inputs. 310 * Toggle Buttons are used for switching the activation of some control and are therefore handled as Buttons. 311 * Collapse/Expand Glyph: > 312 * Collapse and Expand Glyphs hide or trigger the display of some content. Toggle Buttons leave a control 313 * visible to the user, but activate or deactivate it. 314 * Mode View Control: > 315 * Mode View Controls enable the switching between different aspects of some data. Toggle Buttons 316 * activate/deactivate some control, but do not change or switch the control which the user see currently. 317 * 318 * rules: 319 * usage: 320 * 1: > 321 * The Toggle Button MUST be placed next to the control it activates/deactivates. 322 * ordering: 323 * 1: > 324 * The Toggle Button SHOULD be placed above the control it activates/deactivates. 325 * accessibility: 326 * 1: > 327 * The functionality of the Toggle Button MUST be indicated for screen 328 * readers by an aria-label. 329 * 2: > 330 * The state of the Toggle Button MUST be indicated for screen readers 331 * by using the aria-pressed attribute. 332 * --- 333 * @param string $label 334 * @param string|Signal $toggle_on_action action performed when button changes from off to on 335 * @param string|Signal $toggle_off_action action performed when button changes from on to off 336 * @param bool $is_on 337 * @param Signal|null $click_signal action performed when button is clicked 338 * @return \ILIAS\UI\Component\Button\Toggle 339 */ 340 public function toggle(string $label, $on_action, $off_action, bool $is_on = false, Signal $click_signal = null) : \ILIAS\UI\Component\Button\Toggle; 341} 342