3 <html lang=
"en" class=
"no-js">
7 <meta name=
"viewport" content=
"width=device-width,initial-scale=1">
12 <link rel=
"shortcut icon" href=
"../../../../assets/default.favicon.ico">
13 <meta name=
"generator" content=
"mkdocs-1.1.2, mkdocs-material-7.0.5">
17 <title>Structure - WoltLab Suite Documentation
</title>
21 <link rel=
"stylesheet" href=
"../../../../assets/stylesheets/main.77f3fd56.min.css">
24 <link rel=
"stylesheet" href=
"../../../../assets/stylesheets/palette.7fa14f5b.min.css">
28 <meta name=
"theme-color" content=
"#009485">
38 <link rel=
"stylesheet" href=
"../../../../stylesheets/extra.css">
52 <body dir=
"ltr" data-md-color-scheme=
"" data-md-color-primary=
"teal" data-md-color-accent=
"">
56 <input class=
"md-toggle" data-md-toggle=
"drawer" type=
"checkbox" id=
"__drawer" autocomplete=
"off">
57 <input class=
"md-toggle" data-md-toggle=
"search" type=
"checkbox" id=
"__search" autocomplete=
"off">
58 <label class=
"md-overlay" for=
"__drawer"></label>
59 <div data-md-component=
"skip">
62 <a href=
"#structure-of-form-builder" class=
"md-skip">
67 <div data-md-component=
"announce">
69 <aside class=
"md-announce">
70 <div class=
"md-announce__inner md-grid md-typeset">
72 <a href=
"https://www.woltlab.com">Back to
<strong>woltlab.com
</strong></a>
81 <header class=
"md-header" data-md-component=
"header">
82 <nav class=
"md-header__inner md-grid" aria-label=
"Header">
83 <a href=
"../../../.." title=
"WoltLab Suite Documentation" class=
"md-header__button md-logo" aria-label=
"WoltLab Suite Documentation">
85 <img src=
"../../../../assets/logo.png" alt=
"logo">
88 <label class=
"md-header__button md-icon" for=
"__drawer">
89 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 24 24"><path d=
"M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
91 <div class=
"md-header__title" data-md-component=
"header-title">
92 <div class=
"md-header__ellipsis">
93 <div class=
"md-header__topic">
94 <span class=
"md-ellipsis">
95 WoltLab Suite Documentation
98 <div class=
"md-header__topic" data-md-component=
"header-topic">
99 <span class=
"md-ellipsis">
107 <div class=
"md-header__options">
112 <div class=
"md-header__source">
114 <a href=
"https://github.com/WoltLab/docs.woltlab.com/" title=
"Go to repository" class=
"md-source" data-md-component=
"source">
115 <div class=
"md-source__icon md-icon">
117 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 448 512"><path d=
"M439.55 236.05L244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
119 <div class=
"md-source__repository">
128 <div class=
"md-container" data-md-component=
"container">
133 <main class=
"md-main" data-md-component=
"main">
134 <div class=
"md-main__inner md-grid">
138 <div class=
"md-sidebar md-sidebar--primary" data-md-component=
"sidebar" data-md-type=
"navigation" >
139 <div class=
"md-sidebar__scrollwrap">
140 <div class=
"md-sidebar__inner">
146 <nav class=
"md-nav md-nav--primary" aria-label=
"Navigation" data-md-level=
"0">
147 <label class=
"md-nav__title" for=
"__drawer">
148 <a href=
"../../../.." title=
"WoltLab Suite Documentation" class=
"md-nav__button md-logo" aria-label=
"WoltLab Suite Documentation">
150 <img src=
"../../../../assets/logo.png" alt=
"logo">
153 WoltLab Suite Documentation
156 <div class=
"md-nav__source">
158 <a href=
"https://github.com/WoltLab/docs.woltlab.com/" title=
"Go to repository" class=
"md-source" data-md-component=
"source">
159 <div class=
"md-source__icon md-icon">
161 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 448 512"><path d=
"M439.55 236.05L244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
163 <div class=
"md-source__repository">
169 <ul class=
"md-nav__list" data-md-scrollfix
>
178 <li class=
"md-nav__item">
179 <a href=
"../../../../getting-started/" class=
"md-nav__link">
196 <li class=
"md-nav__item md-nav__item--active md-nav__item--nested">
199 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_2" type=
"checkbox" id=
"__nav_2" checked
>
201 <label class=
"md-nav__link" for=
"__nav_2">
203 <span class=
"md-nav__icon md-icon"></span>
205 <nav class=
"md-nav" aria-label=
"PHP API" data-md-level=
"1">
206 <label class=
"md-nav__title" for=
"__nav_2">
207 <span class=
"md-nav__icon md-icon"></span>
210 <ul class=
"md-nav__list" data-md-scrollfix
>
216 <li class=
"md-nav__item">
217 <a href=
"../../../pages/" class=
"md-nav__link">
228 <li class=
"md-nav__item">
229 <a href=
"../../../database-objects/" class=
"md-nav__link">
240 <li class=
"md-nav__item">
241 <a href=
"../../../database-access/" class=
"md-nav__link">
252 <li class=
"md-nav__item">
253 <a href=
"../../../exceptions/" class=
"md-nav__link">
267 <li class=
"md-nav__item md-nav__item--active md-nav__item--nested">
270 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_2_5" type=
"checkbox" id=
"__nav_2_5" checked
>
272 <label class=
"md-nav__link" for=
"__nav_2_5">
274 <span class=
"md-nav__icon md-icon"></span>
276 <nav class=
"md-nav" aria-label=
"API" data-md-level=
"2">
277 <label class=
"md-nav__title" for=
"__nav_2_5">
278 <span class=
"md-nav__icon md-icon"></span>
281 <ul class=
"md-nav__list" data-md-scrollfix
>
287 <li class=
"md-nav__item">
288 <a href=
"../../caches/" class=
"md-nav__link">
299 <li class=
"md-nav__item">
300 <a href=
"../../comments/" class=
"md-nav__link">
311 <li class=
"md-nav__item">
312 <a href=
"../../cronjobs/" class=
"md-nav__link">
323 <li class=
"md-nav__item">
324 <a href=
"../../events/" class=
"md-nav__link">
338 <li class=
"md-nav__item md-nav__item--active md-nav__item--nested">
341 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_2_5_5" type=
"checkbox" id=
"__nav_2_5_5" checked
>
343 <label class=
"md-nav__link" for=
"__nav_2_5_5">
345 <span class=
"md-nav__icon md-icon"></span>
347 <nav class=
"md-nav" aria-label=
"Form Builder" data-md-level=
"3">
348 <label class=
"md-nav__title" for=
"__nav_2_5_5">
349 <span class=
"md-nav__icon md-icon"></span>
352 <ul class=
"md-nav__list" data-md-scrollfix
>
358 <li class=
"md-nav__item">
359 <a href=
"../overview/" class=
"md-nav__link">
372 <li class=
"md-nav__item md-nav__item--active">
374 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"toc" type=
"checkbox" id=
"__toc">
379 <label class=
"md-nav__link md-nav__link--active" for=
"__toc">
381 <span class=
"md-nav__icon md-icon"></span>
384 <a href=
"./" class=
"md-nav__link md-nav__link--active">
389 <nav class=
"md-nav md-nav--secondary" aria-label=
"Table of contents">
395 <label class=
"md-nav__title" for=
"__toc">
396 <span class=
"md-nav__icon md-icon"></span>
399 <ul class=
"md-nav__list" data-md-component=
"toc" data-md-scrollfix
>
401 <li class=
"md-nav__item">
402 <a href=
"#form-nodes" class=
"md-nav__link">
406 <nav class=
"md-nav" aria-label=
"Form Nodes">
407 <ul class=
"md-nav__list">
409 <li class=
"md-nav__item">
410 <a href=
"#iformnode" class=
"md-nav__link">
416 <li class=
"md-nav__item">
417 <a href=
"#iformchildnode" class=
"md-nav__link">
423 <li class=
"md-nav__item">
424 <a href=
"#iformparentnode" class=
"md-nav__link">
430 <li class=
"md-nav__item">
431 <a href=
"#iformelement" class=
"md-nav__link">
437 <li class=
"md-nav__item">
438 <a href=
"#iobjecttypeformnode" class=
"md-nav__link">
444 <li class=
"md-nav__item">
445 <a href=
"#customformnode" class=
"md-nav__link">
451 <li class=
"md-nav__item">
452 <a href=
"#templateformnode" class=
"md-nav__link">
463 <li class=
"md-nav__item">
464 <a href=
"#form-document" class=
"md-nav__link">
470 <li class=
"md-nav__item">
471 <a href=
"#form-button" class=
"md-nav__link">
477 <li class=
"md-nav__item">
478 <a href=
"#form-container" class=
"md-nav__link">
484 <li class=
"md-nav__item">
485 <a href=
"#form-field" class=
"md-nav__link">
489 <nav class=
"md-nav" aria-label=
"Form Field">
490 <ul class=
"md-nav__list">
492 <li class=
"md-nav__item">
493 <a href=
"#form-field-interfaces-and-traits" class=
"md-nav__link">
494 Form Field Interfaces and Traits
497 <nav class=
"md-nav" aria-label=
"Form Field Interfaces and Traits">
498 <ul class=
"md-nav__list">
500 <li class=
"md-nav__item">
501 <a href=
"#iattributeformfield" class=
"md-nav__link">
507 <li class=
"md-nav__item">
508 <a href=
"#iautocompleteformfield" class=
"md-nav__link">
509 IAutoCompleteFormField
514 <li class=
"md-nav__item">
515 <a href=
"#iautofocusformfield" class=
"md-nav__link">
521 <li class=
"md-nav__item">
522 <a href=
"#icssclassformfield" class=
"md-nav__link">
528 <li class=
"md-nav__item">
529 <a href=
"#ifileformfield" class=
"md-nav__link">
535 <li class=
"md-nav__item">
536 <a href=
"#ifilterableselectionformfield" class=
"md-nav__link">
537 IFilterableSelectionFormField
542 <li class=
"md-nav__item">
543 <a href=
"#ii18nformfield" class=
"md-nav__link">
549 <li class=
"md-nav__item">
550 <a href=
"#iimmutableformfield" class=
"md-nav__link">
556 <li class=
"md-nav__item">
557 <a href=
"#iinputmodeformfield" class=
"md-nav__link">
563 <li class=
"md-nav__item">
564 <a href=
"#imaximumformfield" class=
"md-nav__link">
570 <li class=
"md-nav__item">
571 <a href=
"#imaximumlengthformfield" class=
"md-nav__link">
572 IMaximumLengthFormField
577 <li class=
"md-nav__item">
578 <a href=
"#iminimumformfield" class=
"md-nav__link">
584 <li class=
"md-nav__item">
585 <a href=
"#iminimumlengthformfield" class=
"md-nav__link">
586 IMinimumLengthFormField
591 <li class=
"md-nav__item">
592 <a href=
"#imultipleformfield" class=
"md-nav__link">
598 <li class=
"md-nav__item">
599 <a href=
"#inullableformfield" class=
"md-nav__link">
605 <li class=
"md-nav__item">
606 <a href=
"#ipackagesformfield" class=
"md-nav__link">
612 <li class=
"md-nav__item">
613 <a href=
"#ipatternformfield" class=
"md-nav__link">
619 <li class=
"md-nav__item">
620 <a href=
"#iplaceholderformfield" class=
"md-nav__link">
621 IPlaceholderFormField
626 <li class=
"md-nav__item">
627 <a href=
"#iselectionformfield" class=
"md-nav__link">
633 <li class=
"md-nav__item">
634 <a href=
"#isuffixedformfield" class=
"md-nav__link">
640 <li class=
"md-nav__item">
641 <a href=
"#tdefaultidformfield" class=
"md-nav__link">
657 <li class=
"md-nav__item">
658 <a href=
"#displaying-forms" class=
"md-nav__link">
676 <li class=
"md-nav__item">
677 <a href=
"../form_fields/" class=
"md-nav__link">
688 <li class=
"md-nav__item">
689 <a href=
"../validation_data/" class=
"md-nav__link">
700 <li class=
"md-nav__item">
701 <a href=
"../dependencies/" class=
"md-nav__link">
718 <li class=
"md-nav__item">
719 <a href=
"../../package_installation_plugins/" class=
"md-nav__link">
720 Package Installation Plugins
730 <li class=
"md-nav__item">
731 <a href=
"../../user_activity_points/" class=
"md-nav__link">
742 <li class=
"md-nav__item">
743 <a href=
"../../user_notifications/" class=
"md-nav__link">
754 <li class=
"md-nav__item">
755 <a href=
"../../sitemaps/" class=
"md-nav__link">
772 <li class=
"md-nav__item">
773 <a href=
"../../../code-style/" class=
"md-nav__link">
784 <li class=
"md-nav__item">
785 <a href=
"../../../apps/" class=
"md-nav__link">
796 <li class=
"md-nav__item">
797 <a href=
"../../../gdpr/" class=
"md-nav__link">
818 <li class=
"md-nav__item md-nav__item--nested">
821 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_3" type=
"checkbox" id=
"__nav_3" >
823 <label class=
"md-nav__link" for=
"__nav_3">
824 Languages, Templates & CSS
825 <span class=
"md-nav__icon md-icon"></span>
827 <nav class=
"md-nav" aria-label=
"Languages, Templates & CSS" data-md-level=
"1">
828 <label class=
"md-nav__title" for=
"__nav_3">
829 <span class=
"md-nav__icon md-icon"></span>
830 Languages, Templates & CSS
832 <ul class=
"md-nav__list" data-md-scrollfix
>
838 <li class=
"md-nav__item">
839 <a href=
"../../../../view/languages/" class=
"md-nav__link">
850 <li class=
"md-nav__item">
851 <a href=
"../../../../view/templates/" class=
"md-nav__link">
862 <li class=
"md-nav__item">
863 <a href=
"../../../../view/css/" class=
"md-nav__link">
884 <li class=
"md-nav__item md-nav__item--nested">
887 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_4" type=
"checkbox" id=
"__nav_4" >
889 <label class=
"md-nav__link" for=
"__nav_4">
891 <span class=
"md-nav__icon md-icon"></span>
893 <nav class=
"md-nav" aria-label=
"JavaScript API" data-md-level=
"1">
894 <label class=
"md-nav__title" for=
"__nav_4">
895 <span class=
"md-nav__icon md-icon"></span>
898 <ul class=
"md-nav__list" data-md-scrollfix
>
904 <li class=
"md-nav__item">
905 <a href=
"../../../../javascript/general-usage/" class=
"md-nav__link">
917 <li class=
"md-nav__item md-nav__item--nested">
920 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_4_2" type=
"checkbox" id=
"__nav_4_2" >
922 <label class=
"md-nav__link" for=
"__nav_4_2">
924 <span class=
"md-nav__icon md-icon"></span>
926 <nav class=
"md-nav" aria-label=
"New API" data-md-level=
"2">
927 <label class=
"md-nav__title" for=
"__nav_4_2">
928 <span class=
"md-nav__icon md-icon"></span>
931 <ul class=
"md-nav__list" data-md-scrollfix
>
937 <li class=
"md-nav__item">
938 <a href=
"../../../../javascript/new-api_writing-a-module/" class=
"md-nav__link">
949 <li class=
"md-nav__item">
950 <a href=
"../../../../javascript/new-api_data-structures/" class=
"md-nav__link">
961 <li class=
"md-nav__item">
962 <a href=
"../../../../javascript/new-api_core/" class=
"md-nav__link">
973 <li class=
"md-nav__item">
974 <a href=
"../../../../javascript/new-api_dom/" class=
"md-nav__link">
985 <li class=
"md-nav__item">
986 <a href=
"../../../../javascript/new-api_events/" class=
"md-nav__link">
997 <li class=
"md-nav__item">
998 <a href=
"../../../../javascript/new-api_ajax/" class=
"md-nav__link">
1009 <li class=
"md-nav__item">
1010 <a href=
"../../../../javascript/new-api_dialogs/" class=
"md-nav__link">
1021 <li class=
"md-nav__item">
1022 <a href=
"../../../../javascript/new-api_browser/" class=
"md-nav__link">
1023 Browser and Screen Sizes
1033 <li class=
"md-nav__item">
1034 <a href=
"../../../../javascript/new-api_ui/" class=
"md-nav__link">
1051 <li class=
"md-nav__item">
1052 <a href=
"../../../../javascript/legacy-api/" class=
"md-nav__link">
1063 <li class=
"md-nav__item">
1064 <a href=
"../../../../javascript/helper-functions/" class=
"md-nav__link">
1075 <li class=
"md-nav__item">
1076 <a href=
"../../../../javascript/code-snippets/" class=
"md-nav__link">
1097 <li class=
"md-nav__item md-nav__item--nested">
1100 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_5" type=
"checkbox" id=
"__nav_5" >
1102 <label class=
"md-nav__link" for=
"__nav_5">
1104 <span class=
"md-nav__icon md-icon"></span>
1106 <nav class=
"md-nav" aria-label=
"Package Components" data-md-level=
"1">
1107 <label class=
"md-nav__title" for=
"__nav_5">
1108 <span class=
"md-nav__icon md-icon"></span>
1111 <ul class=
"md-nav__list" data-md-scrollfix
>
1117 <li class=
"md-nav__item">
1118 <a href=
"../../../../package/package-xml/" class=
"md-nav__link">
1130 <li class=
"md-nav__item md-nav__item--nested">
1133 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_5_2" type=
"checkbox" id=
"__nav_5_2" >
1135 <label class=
"md-nav__link" for=
"__nav_5_2">
1137 <span class=
"md-nav__icon md-icon"></span>
1139 <nav class=
"md-nav" aria-label=
"PIPs" data-md-level=
"2">
1140 <label class=
"md-nav__title" for=
"__nav_5_2">
1141 <span class=
"md-nav__icon md-icon"></span>
1144 <ul class=
"md-nav__list" data-md-scrollfix
>
1150 <li class=
"md-nav__item">
1151 <a href=
"../../../../package/pip/" class=
"md-nav__link">
1162 <li class=
"md-nav__item">
1163 <a href=
"../../../../package/pip/acl-option/" class=
"md-nav__link">
1174 <li class=
"md-nav__item">
1175 <a href=
"../../../../package/pip/acp-menu/" class=
"md-nav__link">
1186 <li class=
"md-nav__item">
1187 <a href=
"../../../../package/pip/acp-search-provider/" class=
"md-nav__link">
1198 <li class=
"md-nav__item">
1199 <a href=
"../../../../package/pip/acp-template/" class=
"md-nav__link">
1210 <li class=
"md-nav__item">
1211 <a href=
"../../../../package/pip/bbcode/" class=
"md-nav__link">
1222 <li class=
"md-nav__item">
1223 <a href=
"../../../../package/pip/box/" class=
"md-nav__link">
1234 <li class=
"md-nav__item">
1235 <a href=
"../../../../package/pip/clipboard-action/" class=
"md-nav__link">
1246 <li class=
"md-nav__item">
1247 <a href=
"../../../../package/pip/core-object/" class=
"md-nav__link">
1258 <li class=
"md-nav__item">
1259 <a href=
"../../../../package/pip/cronjob/" class=
"md-nav__link">
1270 <li class=
"md-nav__item">
1271 <a href=
"../../../../package/pip/event-listener/" class=
"md-nav__link">
1282 <li class=
"md-nav__item">
1283 <a href=
"../../../../package/pip/file/" class=
"md-nav__link">
1294 <li class=
"md-nav__item">
1295 <a href=
"../../../../package/pip/language/" class=
"md-nav__link">
1306 <li class=
"md-nav__item">
1307 <a href=
"../../../../package/pip/media-provider/" class=
"md-nav__link">
1318 <li class=
"md-nav__item">
1319 <a href=
"../../../../package/pip/menu/" class=
"md-nav__link">
1330 <li class=
"md-nav__item">
1331 <a href=
"../../../../package/pip/menu-item/" class=
"md-nav__link">
1342 <li class=
"md-nav__item">
1343 <a href=
"../../../../package/pip/object-type/" class=
"md-nav__link">
1354 <li class=
"md-nav__item">
1355 <a href=
"../../../../package/pip/object-type-definition/" class=
"md-nav__link">
1356 objectTypeDefinition
1366 <li class=
"md-nav__item">
1367 <a href=
"../../../../package/pip/option/" class=
"md-nav__link">
1378 <li class=
"md-nav__item">
1379 <a href=
"../../../../package/pip/page/" class=
"md-nav__link">
1390 <li class=
"md-nav__item">
1391 <a href=
"../../../../package/pip/pip/" class=
"md-nav__link">
1402 <li class=
"md-nav__item">
1403 <a href=
"../../../../package/pip/script/" class=
"md-nav__link">
1414 <li class=
"md-nav__item">
1415 <a href=
"../../../../package/pip/smiley/" class=
"md-nav__link">
1426 <li class=
"md-nav__item">
1427 <a href=
"../../../../package/pip/sql/" class=
"md-nav__link">
1438 <li class=
"md-nav__item">
1439 <a href=
"../../../../package/pip/style/" class=
"md-nav__link">
1450 <li class=
"md-nav__item">
1451 <a href=
"../../../../package/pip/template/" class=
"md-nav__link">
1462 <li class=
"md-nav__item">
1463 <a href=
"../../../../package/pip/template-listener/" class=
"md-nav__link">
1474 <li class=
"md-nav__item">
1475 <a href=
"../../../../package/pip/user-group-option/" class=
"md-nav__link">
1486 <li class=
"md-nav__item">
1487 <a href=
"../../../../package/pip/user-menu/" class=
"md-nav__link">
1498 <li class=
"md-nav__item">
1499 <a href=
"../../../../package/pip/user-notification-event/" class=
"md-nav__link">
1500 userNotificationEvent
1510 <li class=
"md-nav__item">
1511 <a href=
"../../../../package/pip/user-option/" class=
"md-nav__link">
1522 <li class=
"md-nav__item">
1523 <a href=
"../../../../package/pip/user-profile-menu/" class=
"md-nav__link">
1540 <li class=
"md-nav__item">
1541 <a href=
"../../../../package/database-php-api/" class=
"md-nav__link">
1562 <li class=
"md-nav__item md-nav__item--nested">
1565 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6" type=
"checkbox" id=
"__nav_6" >
1567 <label class=
"md-nav__link" for=
"__nav_6">
1569 <span class=
"md-nav__icon md-icon"></span>
1571 <nav class=
"md-nav" aria-label=
"Migration" data-md-level=
"1">
1572 <label class=
"md-nav__title" for=
"__nav_6">
1573 <span class=
"md-nav__icon md-icon"></span>
1576 <ul class=
"md-nav__list" data-md-scrollfix
>
1583 <li class=
"md-nav__item md-nav__item--nested">
1586 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_1" type=
"checkbox" id=
"__nav_6_1" >
1588 <label class=
"md-nav__link" for=
"__nav_6_1">
1589 Migrating from WSC
5.3
1590 <span class=
"md-nav__icon md-icon"></span>
1592 <nav class=
"md-nav" aria-label=
"Migrating from WSC 5.3" data-md-level=
"2">
1593 <label class=
"md-nav__title" for=
"__nav_6_1">
1594 <span class=
"md-nav__icon md-icon"></span>
1595 Migrating from WSC
5.3
1597 <ul class=
"md-nav__list" data-md-scrollfix
>
1603 <li class=
"md-nav__item">
1604 <a href=
"../../../../migration/wsc53/php/" class=
"md-nav__link">
1615 <li class=
"md-nav__item">
1616 <a href=
"../../../../migration/wsc53/session/" class=
"md-nav__link">
1617 Session Handling and Authentication
1627 <li class=
"md-nav__item">
1628 <a href=
"../../../../migration/wsc53/javascript/" class=
"md-nav__link">
1639 <li class=
"md-nav__item">
1640 <a href=
"../../../../migration/wsc53/templates/" class=
"md-nav__link">
1651 <li class=
"md-nav__item">
1652 <a href=
"../../../../migration/wsc53/libraries/" class=
"md-nav__link">
1653 Third Party Libraries
1670 <li class=
"md-nav__item md-nav__item--nested">
1673 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_2" type=
"checkbox" id=
"__nav_6_2" >
1675 <label class=
"md-nav__link" for=
"__nav_6_2">
1676 Migrating from WSC
5.2
1677 <span class=
"md-nav__icon md-icon"></span>
1679 <nav class=
"md-nav" aria-label=
"Migrating from WSC 5.2" data-md-level=
"2">
1680 <label class=
"md-nav__title" for=
"__nav_6_2">
1681 <span class=
"md-nav__icon md-icon"></span>
1682 Migrating from WSC
5.2
1684 <ul class=
"md-nav__list" data-md-scrollfix
>
1690 <li class=
"md-nav__item">
1691 <a href=
"../../../../migration/wsc52/php/" class=
"md-nav__link">
1702 <li class=
"md-nav__item">
1703 <a href=
"../../../../migration/wsc52/templates/" class=
"md-nav__link">
1704 Templates and Languages
1714 <li class=
"md-nav__item">
1715 <a href=
"../../../../migration/wsc52/libraries/" class=
"md-nav__link">
1716 Third Party Libraries
1733 <li class=
"md-nav__item md-nav__item--nested">
1736 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_3" type=
"checkbox" id=
"__nav_6_3" >
1738 <label class=
"md-nav__link" for=
"__nav_6_3">
1739 Migrating from WSC
3.1
1740 <span class=
"md-nav__icon md-icon"></span>
1742 <nav class=
"md-nav" aria-label=
"Migrating from WSC 3.1" data-md-level=
"2">
1743 <label class=
"md-nav__title" for=
"__nav_6_3">
1744 <span class=
"md-nav__icon md-icon"></span>
1745 Migrating from WSC
3.1
1747 <ul class=
"md-nav__list" data-md-scrollfix
>
1753 <li class=
"md-nav__item">
1754 <a href=
"../../../../migration/wsc31/php/" class=
"md-nav__link">
1772 <li class=
"md-nav__item md-nav__item--nested">
1775 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_4" type=
"checkbox" id=
"__nav_6_4" >
1777 <label class=
"md-nav__link" for=
"__nav_6_4">
1778 Migrating from WSC
3.0
1779 <span class=
"md-nav__icon md-icon"></span>
1781 <nav class=
"md-nav" aria-label=
"Migrating from WSC 3.0" data-md-level=
"2">
1782 <label class=
"md-nav__title" for=
"__nav_6_4">
1783 <span class=
"md-nav__icon md-icon"></span>
1784 Migrating from WSC
3.0
1786 <ul class=
"md-nav__list" data-md-scrollfix
>
1792 <li class=
"md-nav__item">
1793 <a href=
"../../../../migration/wsc30/php/" class=
"md-nav__link">
1804 <li class=
"md-nav__item">
1805 <a href=
"../../../../migration/wsc30/javascript/" class=
"md-nav__link">
1816 <li class=
"md-nav__item">
1817 <a href=
"../../../../migration/wsc30/templates/" class=
"md-nav__link">
1828 <li class=
"md-nav__item">
1829 <a href=
"../../../../migration/wsc30/css/" class=
"md-nav__link">
1840 <li class=
"md-nav__item">
1841 <a href=
"../../../../migration/wsc30/package/" class=
"md-nav__link">
1859 <li class=
"md-nav__item md-nav__item--nested">
1862 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_5" type=
"checkbox" id=
"__nav_6_5" >
1864 <label class=
"md-nav__link" for=
"__nav_6_5">
1865 Migrating from WCF
2.1
1866 <span class=
"md-nav__icon md-icon"></span>
1868 <nav class=
"md-nav" aria-label=
"Migrating from WCF 2.1" data-md-level=
"2">
1869 <label class=
"md-nav__title" for=
"__nav_6_5">
1870 <span class=
"md-nav__icon md-icon"></span>
1871 Migrating from WCF
2.1
1873 <ul class=
"md-nav__list" data-md-scrollfix
>
1879 <li class=
"md-nav__item">
1880 <a href=
"../../../../migration/wcf21/php/" class=
"md-nav__link">
1891 <li class=
"md-nav__item">
1892 <a href=
"../../../../migration/wcf21/templates/" class=
"md-nav__link">
1903 <li class=
"md-nav__item">
1904 <a href=
"../../../../migration/wcf21/css/" class=
"md-nav__link">
1915 <li class=
"md-nav__item">
1916 <a href=
"../../../../migration/wcf21/package/" class=
"md-nav__link">
1943 <li class=
"md-nav__item md-nav__item--nested">
1946 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_7" type=
"checkbox" id=
"__nav_7" >
1948 <label class=
"md-nav__link" for=
"__nav_7">
1950 <span class=
"md-nav__icon md-icon"></span>
1952 <nav class=
"md-nav" aria-label=
"Tutorials" data-md-level=
"1">
1953 <label class=
"md-nav__title" for=
"__nav_7">
1954 <span class=
"md-nav__icon md-icon"></span>
1957 <ul class=
"md-nav__list" data-md-scrollfix
>
1964 <li class=
"md-nav__item md-nav__item--nested">
1967 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_7_1" type=
"checkbox" id=
"__nav_7_1" >
1969 <label class=
"md-nav__link" for=
"__nav_7_1">
1971 <span class=
"md-nav__icon md-icon"></span>
1973 <nav class=
"md-nav" aria-label=
"Tutorial Series" data-md-level=
"2">
1974 <label class=
"md-nav__title" for=
"__nav_7_1">
1975 <span class=
"md-nav__icon md-icon"></span>
1978 <ul class=
"md-nav__list" data-md-scrollfix
>
1984 <li class=
"md-nav__item">
1985 <a href=
"../../../../tutorial/series/overview/" class=
"md-nav__link">
1996 <li class=
"md-nav__item">
1997 <a href=
"../../../../tutorial/series/part_1/" class=
"md-nav__link">
2008 <li class=
"md-nav__item">
2009 <a href=
"../../../../tutorial/series/part_2/" class=
"md-nav__link">
2020 <li class=
"md-nav__item">
2021 <a href=
"../../../../tutorial/series/part_3/" class=
"md-nav__link">
2048 <div class=
"md-sidebar md-sidebar--secondary" data-md-component=
"sidebar" data-md-type=
"toc" >
2049 <div class=
"md-sidebar__scrollwrap">
2050 <div class=
"md-sidebar__inner">
2052 <nav class=
"md-nav md-nav--secondary" aria-label=
"Table of contents">
2058 <label class=
"md-nav__title" for=
"__toc">
2059 <span class=
"md-nav__icon md-icon"></span>
2062 <ul class=
"md-nav__list" data-md-component=
"toc" data-md-scrollfix
>
2064 <li class=
"md-nav__item">
2065 <a href=
"#form-nodes" class=
"md-nav__link">
2069 <nav class=
"md-nav" aria-label=
"Form Nodes">
2070 <ul class=
"md-nav__list">
2072 <li class=
"md-nav__item">
2073 <a href=
"#iformnode" class=
"md-nav__link">
2079 <li class=
"md-nav__item">
2080 <a href=
"#iformchildnode" class=
"md-nav__link">
2086 <li class=
"md-nav__item">
2087 <a href=
"#iformparentnode" class=
"md-nav__link">
2093 <li class=
"md-nav__item">
2094 <a href=
"#iformelement" class=
"md-nav__link">
2100 <li class=
"md-nav__item">
2101 <a href=
"#iobjecttypeformnode" class=
"md-nav__link">
2107 <li class=
"md-nav__item">
2108 <a href=
"#customformnode" class=
"md-nav__link">
2114 <li class=
"md-nav__item">
2115 <a href=
"#templateformnode" class=
"md-nav__link">
2126 <li class=
"md-nav__item">
2127 <a href=
"#form-document" class=
"md-nav__link">
2133 <li class=
"md-nav__item">
2134 <a href=
"#form-button" class=
"md-nav__link">
2140 <li class=
"md-nav__item">
2141 <a href=
"#form-container" class=
"md-nav__link">
2147 <li class=
"md-nav__item">
2148 <a href=
"#form-field" class=
"md-nav__link">
2152 <nav class=
"md-nav" aria-label=
"Form Field">
2153 <ul class=
"md-nav__list">
2155 <li class=
"md-nav__item">
2156 <a href=
"#form-field-interfaces-and-traits" class=
"md-nav__link">
2157 Form Field Interfaces and Traits
2160 <nav class=
"md-nav" aria-label=
"Form Field Interfaces and Traits">
2161 <ul class=
"md-nav__list">
2163 <li class=
"md-nav__item">
2164 <a href=
"#iattributeformfield" class=
"md-nav__link">
2170 <li class=
"md-nav__item">
2171 <a href=
"#iautocompleteformfield" class=
"md-nav__link">
2172 IAutoCompleteFormField
2177 <li class=
"md-nav__item">
2178 <a href=
"#iautofocusformfield" class=
"md-nav__link">
2184 <li class=
"md-nav__item">
2185 <a href=
"#icssclassformfield" class=
"md-nav__link">
2191 <li class=
"md-nav__item">
2192 <a href=
"#ifileformfield" class=
"md-nav__link">
2198 <li class=
"md-nav__item">
2199 <a href=
"#ifilterableselectionformfield" class=
"md-nav__link">
2200 IFilterableSelectionFormField
2205 <li class=
"md-nav__item">
2206 <a href=
"#ii18nformfield" class=
"md-nav__link">
2212 <li class=
"md-nav__item">
2213 <a href=
"#iimmutableformfield" class=
"md-nav__link">
2219 <li class=
"md-nav__item">
2220 <a href=
"#iinputmodeformfield" class=
"md-nav__link">
2226 <li class=
"md-nav__item">
2227 <a href=
"#imaximumformfield" class=
"md-nav__link">
2233 <li class=
"md-nav__item">
2234 <a href=
"#imaximumlengthformfield" class=
"md-nav__link">
2235 IMaximumLengthFormField
2240 <li class=
"md-nav__item">
2241 <a href=
"#iminimumformfield" class=
"md-nav__link">
2247 <li class=
"md-nav__item">
2248 <a href=
"#iminimumlengthformfield" class=
"md-nav__link">
2249 IMinimumLengthFormField
2254 <li class=
"md-nav__item">
2255 <a href=
"#imultipleformfield" class=
"md-nav__link">
2261 <li class=
"md-nav__item">
2262 <a href=
"#inullableformfield" class=
"md-nav__link">
2268 <li class=
"md-nav__item">
2269 <a href=
"#ipackagesformfield" class=
"md-nav__link">
2275 <li class=
"md-nav__item">
2276 <a href=
"#ipatternformfield" class=
"md-nav__link">
2282 <li class=
"md-nav__item">
2283 <a href=
"#iplaceholderformfield" class=
"md-nav__link">
2284 IPlaceholderFormField
2289 <li class=
"md-nav__item">
2290 <a href=
"#iselectionformfield" class=
"md-nav__link">
2296 <li class=
"md-nav__item">
2297 <a href=
"#isuffixedformfield" class=
"md-nav__link">
2303 <li class=
"md-nav__item">
2304 <a href=
"#tdefaultidformfield" class=
"md-nav__link">
2320 <li class=
"md-nav__item">
2321 <a href=
"#displaying-forms" class=
"md-nav__link">
2335 <div class=
"md-content" data-md-component=
"content">
2336 <article class=
"md-content__inner md-typeset">
2339 <a href=
"https://github.com/WoltLab/docs.woltlab.com/edit/5.4/docs/php/api/form_builder/structure.md" title=
"Edit this page" class=
"md-content__button md-icon">
2340 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 24 24"><path d=
"M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z"/></svg>
2344 <h1 id=
"structure-of-form-builder">Structure of Form Builder
<a class=
"headerlink" href=
"#structure-of-form-builder" title=
"Permanent link">#
</a></h1>
2345 <p>Forms built with form builder consist of three major structural elements listed from top to bottom:
</p>
2347 <li>form document,
</li>
2348 <li>form container,
</li>
2349 <li>form field.
</li>
2351 <p>The basis for all three elements are form nodes.
</p>
2352 <div class=
"admonition info">
2353 <p class=
"admonition-title">The form builder API uses fluent interfaces heavily, meaning that unless a method is a getter, it generally returns the objects itself to support method chaining.
</p>
2355 <h2 id=
"form-nodes">Form Nodes
<a class=
"headerlink" href=
"#form-nodes" title=
"Permanent link">#
</a></h2>
2357 <li><code>IFormNode
</code> is the base interface that any node of a form has to implement.
</li>
2358 <li><code>IFormChildNode
</code> extends
<code>IFormNode
</code> for such elements of a form that can be a child node to a parent node.
</li>
2359 <li><code>IFormParentNode
</code> extends
<code>IFormNode
</code> for such elements of a form that can be a parent to child nodes.
</li>
2360 <li><code>IFormElement
</code> extends
<code>IFormNode
</code> for such elements of a form that can have a description and a label.
</li>
2362 <h3 id=
"iformnode"><code>IFormNode
</code><a class=
"headerlink" href=
"#iformnode" title=
"Permanent link">#
</a></h3>
2363 <p><code>IFormNode
</code> is the base interface that any node of a form has to implement and it requires the following methods:
</p>
2365 <li><code>addClass($class)
</code>,
<code>addClasses(array $classes)
</code>,
<code>removeClass($class)
</code>,
<code>getClasses()
</code>, and
<code>hasClass($class)
</code> add, remove, get, and check for CSS classes of the HTML element representing the form node.
2366 If the form node consists of multiple (nested) HTML elements, the classes are generally added to the top element.
2367 <code>static validateClass($class)
</code> is used to check if a given CSS class is valid.
2368 By default, a form node has no CSS classes.
</li>
2369 <li><code>addDependency(IFormFieldDependency $dependency)
</code>,
<code>removeDependency($dependencyId)
</code>,
<code>getDependencies()
</code>, and
<code>hasDependency($dependencyId)
</code> add, remove, get, and check for dependencies of this form node on other form fields.
2370 <code>checkDependencies()
</code> checks if
<strong>all
</strong> of the node’s dependencies are met and returns a boolean value reflecting the check’s result.
2371 The
<a href=
"../dependencies/">form builder dependency documentation
</a> provides more detailed information about dependencies and how they work.
2372 By default, a form node has no dependencies.
</li>
2373 <li><code>attribute($name, $value = null)
</code>,
<code>removeAttribute($name)
</code>,
<code>getAttribute($name)
</code>,
<code>getAttributes()
</code>,
<code>hasAttribute($name)
</code> add, remove, get, and check for attributes of the HTML element represting the form node.
2374 The attributes are added to the same element that the CSS classes are added to.
2375 <code>static validateAttribute($name)
</code> is used to check if a given attribute is valid.
2376 By default, a form node has no attributes.
</li>
2377 <li><code>available($available = true)
</code> and
<code>isAvailable()
</code> can be used to set and check if the node is available.
2378 The availability functionality can be used to easily toggle form nodes based, for example, on options without having to create a condition to append the relevant.
2379 This way of checking availability makes it easier to set up forms.
2380 By default, every form node is available.
</li>
2382 <p>The following aspects are important when working with availability:
</p>
2384 <li>Unavailable fields produce no output, their value is not read, they are not validated and they are not checked for save values.
</li>
2385 <li>Form fields are also able to mark themselves as unavailable, for example, a selection field without any options.
</li>
2386 <li>Form containers are automatically unavailable if they contain no available children.
</li>
2388 <p>Availability sets the static availability for form nodes that does not change during the lifetime of a form.
2389 In contrast, dependencies represent a dynamic availability for form nodes that depends on the current value of certain form fields.
2390 -
<code>cleanup()
</code> is called after the whole form is not used anymore to reset other APIs if the form fields depends on them and they expect such a reset.
2391 This method is not intended to clean up the form field’s value as a new form document object is created to show a clean form.
2392 -
<code>getDocument()
</code> returns the
<code>IFormDocument
</code> object the node belongs to.
2393 (As
<code>IFormDocument
</code> extends
<code>IFormNode
</code>, form document objects simply return themselves.)
2394 -
<code>getHtml()
</code> returns the HTML representation of the node.
2395 <code>getHtmlVariables()
</code> return template variables (in addition to the form node itself) to render the node’s HTML representation.
2396 -
<code>id($id)
</code> and
<code>getId()
</code> set and get the id of the form node.
2397 Every id has to be unique within a form.
2398 <code>getPrefixedId()
</code> returns the prefixed version of the node’s id (see
<code>IFormDocument::getPrefix()
</code> and
<code>IFormDocument::prefix()
</code>).
2399 <code>static validateId($id)
</code> is used to check if a given id is valid.
2400 -
<code>populate()
</code> is called by
<code>IFormDocument::build()
</code> after all form nodes have been added.
2401 This method should finilize the initialization of the form node after all parent-child relations of the form document have been established.
2402 This method is needed because during the construction of a form node, it neither knows the form document it will belong to nor does it know its parent.
2403 -
<code>validate()
</code> checks, after the form is submitted, if the form node is valid.
2404 A form node with children is valid if all of its child nodes are valid.
2405 A form field is valid if its value is valid.
2406 -
<code>static create($id)
</code> is the factory method that has to be used to create new form nodes with the given id.
</p>
2407 <p><code>TFormNode
</code> provides a default implementation of most of these methods.
</p>
2408 <h3 id=
"iformchildnode"><code>IFormChildNode
</code><a class=
"headerlink" href=
"#iformchildnode" title=
"Permanent link">#
</a></h3>
2409 <p><code>IFormChildNode
</code> extends
<code>IFormNode
</code> for such elements of a form that can be a child node to a parent node and it requires the
<code>parent(IFormParentNode $parentNode)
</code> and
<code>getParent()
</code> methods used to set and get the node’s parent node.
2410 <code>TFormChildNode
</code> provides a default implementation of these two methods and also of
<code>IFormNode::getDocument()
</code>.
</p>
2411 <h3 id=
"iformparentnode"><code>IFormParentNode
</code><a class=
"headerlink" href=
"#iformparentnode" title=
"Permanent link">#
</a></h3>
2412 <p><code>IFormParentNode
</code> extends
<code>IFormNode
</code> for such elements of a form that can be a parent to child nodes.
2413 Additionally, the interface also extends
<code>\Countable
</code> and
<code>\RecursiveIterator
</code>.
2414 The interface requires the following methods:
</p>
2416 <li><code>appendChild(IFormChildNode $child)
</code>,
<code>appendChildren(array $children)
</code>,
<code>insertAfter(IFormChildNode $child, $referenceNodeId)
</code>, and
<code>insertBefore(IFormChildNode $child, $referenceNodeId)
</code> are used to insert new children either at the end or at specific positions.
2417 <code>validateChild(IFormChildNode $child)
</code> is used to check if a given child node can be added.
2418 A child node cannot be added if it would cause an id to be used twice.
</li>
2419 <li><code>children()
</code> returns the direct children of a form node.
</li>
2420 <li><code>getIterator()
</code> return a recursive iterator for a form node.
</li>
2421 <li><code>getNodeById($nodeId)
</code> returns the node with the given id by searching for it in the node’s children and recursively in all of their children.
2422 <code>contains($nodeId)
</code> can be used to simply check if a node with the given id exists.
</li>
2423 <li><code>hasValidationErrors()
</code> checks if a form node or any of its children has a validation error (see
<code>IFormField::getValidationErrors()
</code>).
</li>
2424 <li><code>readValues()
</code> recursively calls
<code>IFormParentNode::readValues()
</code> and
<code>IFormField::readValue()
</code> on its children.
</li>
2426 <h3 id=
"iformelement"><code>IFormElement
</code><a class=
"headerlink" href=
"#iformelement" title=
"Permanent link">#
</a></h3>
2427 <p><code>IFormElement
</code> extends
<code>IFormNode
</code> for such elements of a form that can have a description and a label and it requires the following methods:
</p>
2429 <li><code>label($languageItem = null, array $variables = [])
</code> and
<code>getLabel()
</code> can be used to set and get the label of the form element.
2430 <code>requiresLabel()
</code> can be checked if the form element requires a label.
2431 A label-less form element that requires a label will prevent the form from being rendered by throwing an exception.
</li>
2432 <li><code>description($languageItem = null, array $variables = [])
</code> and
<code>getDescription()
</code> can be used to set and get the description of the form element.
</li>
2434 <h3 id=
"iobjecttypeformnode"><code>IObjectTypeFormNode
</code><a class=
"headerlink" href=
"#iobjecttypeformnode" title=
"Permanent link">#
</a></h3>
2435 <p><code>IObjectTypeFormField
</code> has to be implemented by form nodes that rely on a object type of a specific object type definition in order to function.
2436 The implementing class has to implement the methods
<code>objectType($objectType)
</code>,
<code>getObjectType()
</code>, and
<code>getObjectTypeDefinition()
</code>.
2437 <code>TObjectTypeFormNode
</code> provides a default implementation of these three methods.
</p>
2438 <h3 id=
"customformnode"><code>CustomFormNode
</code><a class=
"headerlink" href=
"#customformnode" title=
"Permanent link">#
</a></h3>
2439 <p><code>CustomFormNode
</code> is a form node whose contents can be set directly via
<code>content($content)
</code>.
</p>
2440 <div class=
"admonition warning">
2441 <p class=
"admonition-title">This class should generally not be relied on. Instead,
<code>TemplateFormNode
</code> should be used.
</p>
2443 <h3 id=
"templateformnode"><code>TemplateFormNode
</code><a class=
"headerlink" href=
"#templateformnode" title=
"Permanent link">#
</a></h3>
2444 <p><code>TemplateFormNode
</code> is a form node whose contents are read from a template.
2445 <code>TemplateFormNode
</code> has the following additional methods:
</p>
2447 <li><code>application($application)
</code> and
<code>getApplicaton()
</code> can be used to set and get the abbreviation of the application the shown template belongs to.
2448 If no template has been set explicitly,
<code>getApplicaton()
</code> returns
<code>wcf
</code>.
</li>
2449 <li><code>templateName($templateName)
</code> and
<code>getTemplateName()
</code> can be used to set and get the name of the template containing the node contents.
2450 If no template has been set and the node is rendered, an exception will be thrown.
</li>
2451 <li><code>variables(array $variables)
</code> and
<code>getVariables()
</code> can be used to set and get additional variables passed to the template.
</li>
2453 <h2 id=
"form-document">Form Document
<a class=
"headerlink" href=
"#form-document" title=
"Permanent link">#
</a></h2>
2454 <p>A form document object represents the form as a whole and has to implement the
<code>IFormDocument
</code> interface.
2455 WoltLab Suite provides a default implementation with the
<code>FormDocument
</code> class.
2456 <code>IFormDocument
</code> should not be implemented directly but instead
<code>FormDocument
</code> should be extended to avoid issues if the
<code>IFormDocument
</code> interface changes in the future.
</p>
2457 <p><code>IFormDocument
</code> extends
<code>IFormParentNode
</code> and requires the following additional methods:
</p>
2459 <li><code>action($action)
</code> and
<code>getAction()
</code> can be used set and get the
<code>action
</code> attribute of the
<code><form
></code> HTML element.
</li>
2460 <li><code>addButton(IFormButton $button)
</code> and
<code>getButtons()
</code> can be used add and get form buttons that are shown at the bottom of the form.
2461 <code>addDefaultButton($addDefaultButton)
</code> and
<code>hasDefaultButton()
</code> can be used to set and check if the form has the default button which is added by default unless specified otherwise.
2462 Each implementing class may define its own default button.
2463 <code>FormDocument
</code> has a button with id
<code>submitButton
</code>, label
<code>wcf.global.button.submit
</code>, access key
<code>s
</code>, and CSS class
<code>buttonPrimary
</code> as its default button.
</li>
2464 <li><code>ajax($ajax)
</code> and
<code>isAjax()
</code> can be used to set and check if the form document is requested via an AJAX request or processes data via an AJAX request.
2465 These methods are helpful for form fields that behave differently when providing data via AJAX.
</li>
2466 <li><code>build()
</code> has to be called once after all nodes have been added to this document to trigger
<code>IFormNode::populate()
</code>.
</li>
2468 <p><code>formMode($formMode)
</code> and
<code>getFormMode()
</code> sets the form mode.
2469 Possible form modes are:
</p>
2472 <p><code>IFormDocument::FORM_MODE_CREATE
</code> has to be used when the form is used to create a new object.
</p>
2474 <li><code>IFormDocument::FORM_MODE_UPDATE
</code> has to be used when the form is used to edit an existing object.
</li>
2475 <li><code>getData()
</code> returns the array containing the form data and which is passed as the
<code>$parameters
</code> argument of the constructor of a database object action object.
</li>
2476 <li><code>getDataHandler()
</code> returns the data handler for this document that is used to process the field data into a parameters array for the constructor of a database object action object.
</li>
2477 <li><code>getEnctype()
</code> returns the encoding type of the form.
2478 If the form contains a
<code>IFileFormField
</code>,
<code>multipart/form-data
</code> is returned, otherwise
<code>null
</code> is returned.
</li>
2479 <li><code>loadValues(array $data, IStorableObject $object)
</code> is used when editing an existing object to set the form field values by calling
<code>IFormField::loadValue()
</code> for all form fields.
2480 Additionally, the form mode is set to
<code>IFormDocument::FORM_MODE_UPDATE
</code>.
</li>
2481 <li><span class=
"label label-info">5.4+
</span> <code>markRequiredFields(bool $markRequiredFields = true): self
</code> and
<code>marksRequiredFields(): bool
</code> can be used to set and check whether fields that are required are marked (with an asterisk in the label) in the output.
</li>
2482 <li><code>method($method)
</code> and
<code>getMethod()
</code> can be used to set and get the
<code>method
</code> attribute of the
<code><form
></code> HTML element.
2483 By default, the method is
<code>post
</code>.
</li>
2484 <li><code>prefix($prefix)
</code> and
<code>getPrefix()
</code> can be used to set and get a global form prefix that is prepended to form elements’ names and ids to avoid conflicts with other forms.
2485 By default, the prefix is an empty string.
2486 If a prefix of
<code>foo
</code> is set,
<code>getPrefix()
</code> returns
<code>foo_
</code> (additional trailing underscore).
</li>
2487 <li><code>requestData(array $requestData)
</code>,
<code>getRequestData($index = null)
</code>, and
<code>hasRequestData($index = null)
</code> can be used to set, get and check for specific request data.
2488 In most cases, the relevant request data is the
<code>$_POST
</code> array.
2489 In default AJAX requests handled by database object actions, however, the request data generally is in
<code>AbstractDatabaseObjectAction::$parameters
</code>.
2490 By default,
<code>$_POST
</code> is the request data.
</li>
2492 <p>The last aspect is relevant for
<code>DialogFormDocument
</code> objects.
2493 <code>DialogFormDocument
</code> is a specialized class for forms in dialogs that, in contrast to
<code>FormDocument
</code> do not require an
<code>action
</code> to be set.
2494 Additionally,
<code>DialogFormDocument
</code> provides the
<code>cancelable($cancelable = true)
</code> and
<code>isCancelable()
</code> methods used to determine if the dialog from can be canceled.
2495 By default, dialog forms are cancelable.
</p>
2496 <h2 id=
"form-button">Form Button
<a class=
"headerlink" href=
"#form-button" title=
"Permanent link">#
</a></h2>
2497 <p>A form button object represents a button shown at the end of the form that, for example, submits the form.
2498 Every form button has to implement the
<code>IFormButton
</code> interface that extends
<code>IFormChildNode
</code> and
<code>IFormElement
</code>.
2499 <code>IFormButton
</code> requires four methods to be implemented:
</p>
2501 <li><code>accessKey($accessKey)
</code> and
<code>getAccessKey()
</code> can be used to set and get the access key with which the form button can be activated.
2502 By default, form buttons have no access key set.
</li>
2503 <li><code>submit($submitButton)
</code> and
<code>isSubmit()
</code> can be used to set and check if the form button is a submit button.
2504 A submit button is an
<code>input[type=submit]
</code> element.
2505 Otherwise, the button is a
<code>button
</code> element.
</li>
2507 <h2 id=
"form-container">Form Container
<a class=
"headerlink" href=
"#form-container" title=
"Permanent link">#
</a></h2>
2508 <p>A form container object represents a container for other form containers or form field directly.
2509 Every form container has to implement the
<code>IFormContainer
</code> interface which requires the following method:
</p>
2511 <li><code>loadValues(array $data, IStorableObject $object)
</code> is called by
<code>IFormDocument::loadValuesFromObject()
</code> to inform the container that object data is loaded.
2512 This method is
<em>not
</em> intended to generally call
<code>IFormField::loadValues()
</code> on its form field children as these methods are already called by
<code>IFormDocument::loadValuesFromObject()
</code>.
2513 This method is intended for specialized form containers with more complex logic.
</li>
2515 <p>There are multiple default container implementations:
</p>
2517 <li><code>FormContainer
</code> is the default implementation of
<code>IFormContainer
</code>.
</li>
2518 <li><code>TabMenuFormContainer
</code> represents the container of tab menu, while
</li>
2519 <li><code>TabFormContainer
</code> represents a tab of a tab menu and
</li>
2520 <li><code>TabTabMenuFormContainer
</code> represents a tab of a tab menu that itself contains a tab menu.
</li>
2521 <li>The children of
<code>RowFormContainer
</code> are shown in a row and should use
<code>col-*
</code> classes.
</li>
2522 <li>The children of
<code>RowFormFieldContainer
</code> are also shown in a row but does not show the labels and descriptions of the individual form fields.
2523 Instead of the individual labels and descriptions, the container's label and description is shown and both span all of fields.
</li>
2524 <li><code>SuffixFormFieldContainer
</code> can be used for one form field with a second selection form field used as a suffix.
</li>
2526 <p>The methods of the interfaces that
<code>FormContainer
</code> is implementing are well documented, but here is a short overview of the most important methods when setting up a form or extending a form with an event listener:
</p>
2528 <li><code>appendChild(IFormChildNode $child)
</code>,
<code>appendChildren(array $children)
</code>, and
<code>insertBefore(IFormChildNode $child, $referenceNodeId)
</code> are used to insert new children into the form container.
</li>
2529 <li><code>description($languageItem = null, array $variables = [])
</code> and
<code>label($languageItem = null, array $variables = [])
</code> are used to set the description and the label or title of the form container.
</li>
2531 <h2 id=
"form-field">Form Field
<a class=
"headerlink" href=
"#form-field" title=
"Permanent link">#
</a></h2>
2532 <p>A form field object represents a concrete form field that allows entering data.
2533 Every form field has to implement the
<code>IFormField
</code> interface which extends
<code>IFormChildNode
</code> and
<code>IFormElement
</code>.
</p>
2534 <p><code>IFormField
</code> requires the following additional methods:
</p>
2536 <li><code>addValidationError(IFormFieldValidationError $error)
</code> and
<code>getValidationErrors()
</code> can be used to get and set validation errors of the form field (see
<a href=
"../validation_data/#form-validation">form validation
</a>).
</li>
2537 <li><code>addValidator(IFormFieldValidator $validator)
</code>,
<code>getValidators()
</code>,
<code>removeValidator($validatorId)
</code>, and
<code>hasValidator($validatorId)
</code> can be used to get, set, remove, and check for validators for the form field (see
<a href=
"../validation_data/#form-validation">form validation
</a>).
</li>
2538 <li><code>getFieldHtml()
</code> returns the field's HTML output without the surrounding
<code>dl
</code> structure.
</li>
2539 <li><code>objectProperty($objectProperty)
</code> and
<code>getObjectProperty()
</code> can be used to get and set the object property that the field represents.
2540 When setting the object property is set to an empty string, the previously set object property is unset.
2541 If no object property has been set, the field’s (non-prefixed) id is returned.
</li>
2543 <p>The object property allows having different fields (requiring different ids) that represent the same object property which is handy when available options of the field’s value depend on another field.
2544 Having object property allows to define different fields for each value of the other field and to use form field dependencies to only show the appropriate field.
2545 -
<code>readValue()
</code> reads the form field value from the request data after the form is submitted.
2546 -
<code>required($required = true)
</code> and
<code>isRequired()
</code> can be used to determine if the form field has to be filled out.
2547 By default, form fields do not have to be filled out.
2548 -
<code>value($value)
</code> and
<code>getSaveValue()
</code> can be used to get and set the value of the form field to be used outside of the context of forms.
2549 <code>getValue()
</code>, in contrast, returns the internal representation of the form field’s value.
2550 In general, the internal representation is only relevant when validating the value in additional validators.
2551 <code>loadValue(array $data, IStorableObject $object)
</code> extracts the form field value from the given data array (and additional, non-editable data from the object if the field needs them).
</p>
2552 <p><code>AbstractFormField
</code> provides default implementations of many of the listed methods above and should be extended instead of implementing
<code>IFormField
</code> directly.
</p>
2553 <p>An overview of the form fields provided by default can be found
<a href=
"../form_fields/">here
</a>.
</p>
2554 <h3 id=
"form-field-interfaces-and-traits">Form Field Interfaces and Traits
<a class=
"headerlink" href=
"#form-field-interfaces-and-traits" title=
"Permanent link">#
</a></h3>
2555 <p>WoltLab Suite Core provides a variety of interfaces and matching traits with default implementations for several common features of form fields:
</p>
2556 <h4 id=
"iattributeformfield"><code>IAttributeFormField
</code><a class=
"headerlink" href=
"#iattributeformfield" title=
"Permanent link">#
</a></h4>
2557 <div class=
"admonition info">
2558 <p class=
"admonition-title">Only available since version
5.4.
</p>
2560 <p><code>IAttributeFormField
</code> has to be implemented by form fields for which attributes can be added to the actual form element (in addition to adding attributes to the surrounding element via the attribute-related methods of
<code>IFormNode
</code>).
2561 The implementing class has to implement the methods
<code>fieldAttribute(string $name, string $value = null): self
</code> and
<code>getFieldAttribute(string $name): self
</code>/
<code>getFieldAttributes(): array
</code>, which are used to add and get the attributes, respectively.
2562 Additionally,
<code>hasFieldAttribute(string $name): bool
</code> has to implemented to check if a certain attribute is present,
<code>removeFieldAttribute(string $name): self
</code> to remove an attribute, and
<code>static validateFieldAttribute(string $name)
</code> to check if the attribute is valid for this specific class.
2563 <code>TAttributeFormField
</code> provides a default implementation of these methods and
<code>TInputAttributeFormField
</code> specializes the trait for
<code>input
</code>-based form fields.
2564 These two traits also ensure that if a specific interface that handles a specific attribute is implemented, like
<code>IAutoCompleteFormField
</code> handling
<code>autocomplete
</code>, this attribute cannot be set with this API.
2565 Instead, the dedicated API provided by the relevant interface has to be used.
</p>
2566 <h4 id=
"iautocompleteformfield"><code>IAutoCompleteFormField
</code><a class=
"headerlink" href=
"#iautocompleteformfield" title=
"Permanent link">#
</a></h4>
2567 <div class=
"admonition info">
2568 <p class=
"admonition-title">Only available since version
5.4.
</p>
2570 <p><code>IAutoCompleteFormField
</code> has to be implemented by form fields that support the
<a href=
"https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofilling-form-controls:-the-autocomplete-attribute"><code>autocomplete
</code> attribute
</a>.
2571 The implementing class has to implement the methods
<code>autoComplete(?string $autoComplete): self
</code> and
<code>getAutoComplete(): ?string
</code>, which are used to set and get the autocomplete value, respectively.
2572 <code>TAutoCompleteFormField
</code> provides a default implementation of these two methods and
<code>TTextAutoCompleteFormField
</code> specializes the trait for text form fields.
2573 When using
<code>TAutoCompleteFormField
</code>, you have to implement the
<code>getValidAutoCompleteTokens(): array
</code> method which returns all valid
<code>autocomplete
</code> tokens.
</p>
2574 <h4 id=
"iautofocusformfield"><code>IAutoFocusFormField
</code><a class=
"headerlink" href=
"#iautofocusformfield" title=
"Permanent link">#
</a></h4>
2575 <p><code>IAutoFocusFormField
</code> has to be implemented by form fields that can be auto-focused.
2576 The implementing class has to implement the methods
<code>autoFocus($autoFocus = true)
</code> and
<code>isAutoFocused()
</code>.
2577 By default, form fields are not auto-focused.
2578 <code>TAutoFocusFormField
</code> provides a default implementation of these two methods.
</p>
2579 <h4 id=
"icssclassformfield"><code>ICssClassFormField
</code><a class=
"headerlink" href=
"#icssclassformfield" title=
"Permanent link">#
</a></h4>
2580 <div class=
"admonition info">
2581 <p class=
"admonition-title">Only available since version
5.4.
</p>
2583 <p><code>ICssClassFormField
</code> has to be implemented by form fields for which CSS classes can be added to the actual form element (in addition to adding CSS classes to the surrounding element via the class-related methods of
<code>IFormNode
</code>).
2584 The implementing class has to implement the methods
<code>addFieldClass(string $class): self
</code>/
<code>addFieldClasses(array $classes): self
</code> and
<code>getFieldClasses(): array
</code>, which are used to add and get the CSS classes, respectively.
2585 Additionally,
<code>hasFieldClass(string $class): bool
</code> has to implemented to check if a certain CSS class is present and
<code>removeFieldClass(string $class): self
</code> to remove a CSS class.
2586 <code>TCssClassFormField
</code> provides a default implementation of these methods.
</p>
2587 <h4 id=
"ifileformfield"><code>IFileFormField
</code><a class=
"headerlink" href=
"#ifileformfield" title=
"Permanent link">#
</a></h4>
2588 <p><code>IFileFormField
</code> has to be implemented by every form field that uploads files so that the
<code>enctype
</code> attribute of the form document is
<code>multipart/form-data
</code> (see
<code>IFormDocument::getEnctype()
</code>).
</p>
2589 <h4 id=
"ifilterableselectionformfield"><code>IFilterableSelectionFormField
</code><a class=
"headerlink" href=
"#ifilterableselectionformfield" title=
"Permanent link">#
</a></h4>
2590 <p><code>IFilterableSelectionFormField
</code> extends
<code>ISelectionFormField
</code> by the possibilty for users when selecting the value(s) to filter the list of available options.
2591 The implementing class has to implement the methods
<code>filterable($filterable = true)
</code> and
<code>isFilterable()
</code>.
2592 <code>TFilterableSelectionFormField
</code> provides a default implementation of these two methods.
</p>
2593 <h4 id=
"ii18nformfield"><code>II18nFormField
</code><a class=
"headerlink" href=
"#ii18nformfield" title=
"Permanent link">#
</a></h4>
2594 <p><code>II18nFormField
</code> has to be implemented by form fields if the form field value can be entered separately for all available languages.
2595 The implementing class has to implement the following methods:
</p>
2597 <li><code>i18n($i18n = true)
</code> and
<code>isI18n()
</code> can be used to set whether a specific instance of the class actually supports multilingual input.
</li>
2598 <li><code>i18nRequired($i18nRequired = true)
</code> and
<code>isI18nRequired()
</code> can be used to set whether a specific instance of the class requires separate values for all languages.
</li>
2599 <li><code>languageItemPattern($pattern)
</code> and
<code>getLanguageItemPattern()
</code> can be used to set the pattern/regular expression for the language item used to save the multilingual values.
</li>
2600 <li><code>hasI18nValues()
</code> and
<code>hasPlainValue()
</code> check if the current value is a multilingual or monolingual value.
</li>
2602 <p><code>TI18nFormField
</code> provides a default implementation of these eight methods and additional default implementations of some of the
<code>IFormField
</code> methods.
2603 If multilingual input is enabled for a specific form field, classes using
<code>TI18nFormField
</code> register a
<a href=
"../validation_data/#customformfielddataprocessor">custom form field data processor
</a> to add the array with multilingual input into the
<code>$parameters
</code> array directly using
<code>{$objectProperty}_i18n
</code> as the array key.
2604 If multilingual input is enabled but only a monolingual value is entered, the custom form field data processor does nothing and the form field’s value is added by the
<code>DefaultFormDataProcessor
</code> into the
<code>data
</code> sub-array of the
<code>$parameters
</code> array.
</p>
2605 <div class=
"admonition info">
2606 <p class=
"admonition-title"><code>TI18nFormField
</code> already provides a default implementation of
<code>IFormField::validate()
</code>.
</p>
2608 <h4 id=
"iimmutableformfield"><code>IImmutableFormField
</code><a class=
"headerlink" href=
"#iimmutableformfield" title=
"Permanent link">#
</a></h4>
2609 <p><code>IImmutableFormField
</code> has to be implemented by form fields that support being displayed but whose value cannot be changed.
2610 The implementing class has to implement the methods
<code>immutable($immutable = true)
</code> and
<code>isImmutable()
</code> that can be used to determine if the value of the form field is mutable or immutable.
2611 By default, form field are mutable.
</p>
2612 <h4 id=
"iinputmodeformfield"><code>IInputModeFormField
</code><a class=
"headerlink" href=
"#iinputmodeformfield" title=
"Permanent link">#
</a></h4>
2613 <div class=
"admonition info">
2614 <p class=
"admonition-title">Only available since version
5.4.
</p>
2616 <p><code>IInputModeFormField
</code> has to be implemented by form fields that support the
<a href=
"https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute"><code>inputmode
</code> attribute
</a>.
2617 The implementing class has to implement the methods
<code>inputMode(?string $inputMode): self
</code> and
<code>getInputMode(): ?string
</code>, which are used to set and get the input mode, respectively.
2618 <code>TInputModeFormField
</code> provides a default implementation of these two methods.
</p>
2619 <h4 id=
"imaximumformfield"><code>IMaximumFormField
</code><a class=
"headerlink" href=
"#imaximumformfield" title=
"Permanent link">#
</a></h4>
2620 <p><code>IMaximumFormField
</code> has to be implemented by form fields if the entered value must have a maximum value.
2621 The implementing class has to implement the methods
<code>maximum($maximum = null)
</code> and
<code>getMaximum()
</code>.
2622 A maximum of
<code>null
</code> signals that no maximum value has been set.
2623 <code>TMaximumFormField
</code> provides a default implementation of these two methods.
</p>
2624 <div class=
"admonition warning">
2625 <p class=
"admonition-title">The implementing class has to validate the entered value against the maximum value manually.
</p>
2627 <h4 id=
"imaximumlengthformfield"><code>IMaximumLengthFormField
</code><a class=
"headerlink" href=
"#imaximumlengthformfield" title=
"Permanent link">#
</a></h4>
2628 <p><code>IMaximumLengthFormField
</code> has to be implemented by form fields if the entered value must have a maximum length.
2629 The implementing class has to implement the methods
<code>maximumLength($maximumLength = null)
</code>,
<code>getMaximumLength()
</code>, and
<code>validateMaximumLength($text, Language $language = null)
</code>.
2630 A maximum length of
<code>null
</code> signals that no maximum length has been set.
2631 <code>TMaximumLengthFormField
</code> provides a default implementation of these two methods.
</p>
2632 <div class=
"admonition warning">
2633 <p class=
"admonition-title">The implementing class has to validate the entered value against the maximum value manually by calling
<code>validateMaximumLength()
</code>.
</p>
2635 <h4 id=
"iminimumformfield"><code>IMinimumFormField
</code><a class=
"headerlink" href=
"#iminimumformfield" title=
"Permanent link">#
</a></h4>
2636 <p><code>IMinimumFormField
</code> has to be implemented by form fields if the entered value must have a minimum value.
2637 The implementing class has to implement the methods
<code>minimum($minimum = null)
</code> and
<code>getMinimum()
</code>.
2638 A minimum of
<code>null
</code> signals that no minimum value has been set.
2639 <code>TMinimumFormField
</code> provides a default implementation of these three methods.
</p>
2640 <div class=
"admonition warning">
2641 <p class=
"admonition-title">The implementing class has to validate the entered value against the minimum value manually.
</p>
2643 <h4 id=
"iminimumlengthformfield"><code>IMinimumLengthFormField
</code><a class=
"headerlink" href=
"#iminimumlengthformfield" title=
"Permanent link">#
</a></h4>
2644 <p><code>IMinimumLengthFormField
</code> has to be implemented by form fields if the entered value must have a minimum length.
2645 The implementing class has to implement the methods
<code>minimumLength($minimumLength = null)
</code>,
<code>getMinimumLength()
</code>, and
<code>validateMinimumLength($text, Language $language = null)
</code>.
2646 A minimum length of
<code>null
</code> signals that no minimum length has been set.
2647 <code>TMinimumLengthFormField
</code> provides a default implementation of these three methods.
</p>
2648 <div class=
"admonition warning">
2649 <p class=
"admonition-title">The implementing class has to validate the entered value against the minimum value manually by calling
<code>validateMinimumLength()
</code>.
</p>
2651 <h4 id=
"imultipleformfield"><code>IMultipleFormField
</code><a class=
"headerlink" href=
"#imultipleformfield" title=
"Permanent link">#
</a></h4>
2652 <p><code>IMinimumLengthFormField
</code> has to be implemented by form fields that support selecting or setting multiple values.
2653 The implementing class has to implement the following methods:
</p>
2655 <li><code>multiple($multiple = true)
</code> and
<code>allowsMultiple()
</code> can be used to set whether a specific instance of the class actually should support multiple values.
2656 By default, multiple values are not supported.
</li>
2657 <li><code>minimumMultiples($minimum)
</code> and
<code>getMinimumMultiples()
</code> can be used to set the minimum number of values that have to be selected/entered.
2658 By default, there is no required minimum number of values.
</li>
2659 <li><code>maximumMultiples($minimum)
</code> and
<code>getMaximumMultiples()
</code> can be used to set the maximum number of values that have to be selected/entered.
2660 By default, there is no maximum number of values.
2661 <code>IMultipleFormField::NO_MAXIMUM_MULTIPLES
</code> is returned if no maximum number of values has been set and it can also be used to unset a previously set maximum number of values.
</li>
2663 <p><code>TMultipleFormField
</code> provides a default implementation of these six methods and classes using
<code>TMultipleFormField
</code> register a
<a href=
"../validation_data/#customformfielddataprocessor">custom form field data processor
</a> to add the
<code>HtmlInputProcessor
</code> object with the text into the
<code>$parameters
</code> array directly using
<code>{$objectProperty}_htmlInputProcessor
</code> as the array key.
</p>
2664 <div class=
"admonition warning">
2665 <p class=
"admonition-title">The implementing class has to validate the values against the minimum and maximum number of values manually.
</p>
2667 <h4 id=
"inullableformfield"><code>INullableFormField
</code><a class=
"headerlink" href=
"#inullableformfield" title=
"Permanent link">#
</a></h4>
2668 <p><code>INullableFormField
</code> has to be implemented by form fields that support
<code>null
</code> as their (empty) value.
2669 The implementing class has to implement the methods
<code>nullable($nullable = true)
</code> and
<code>isNullable()
</code>.
2670 <code>TNullableFormField
</code> provides a default implementation of these two methods.
</p>
2671 <p><code>null
</code> should be returned by
<code>IFormField::getSaveValue()
</code> is the field is considered empty and the form field has been set as nullable.
</p>
2672 <h4 id=
"ipackagesformfield"><code>IPackagesFormField
</code><a class=
"headerlink" href=
"#ipackagesformfield" title=
"Permanent link">#
</a></h4>
2673 <p><code>IPackagesFormField
</code> has to be implemented by form fields that, in some way, considers packages whose ids may be passed to the field object.
2674 The implementing class has to implement the methods
<code>packageIDs(array $packageIDs)
</code> and
<code>getPackageIDs()
</code>.
2675 <code>TPackagesFormField
</code> provides a default implementation of these two methods.
</p>
2676 <h4 id=
"ipatternformfield"><code>IPatternFormField
</code><a class=
"headerlink" href=
"#ipatternformfield" title=
"Permanent link">#
</a></h4>
2677 <div class=
"admonition info">
2678 <p class=
"admonition-title">Only available since version
5.4.
</p>
2680 <p><code>IPatternFormField
</code> has to be implemented by form fields that support the
<a href=
"https://html.spec.whatwg.org/multipage/input.html#the-pattern-attribute"><code>pattern
</code> attribute
</a>.
2681 The implementing class has to implement the methods
<code>pattern(?string $pattern): self
</code> and
<code>getPattern(): ?string
</code>, which are used to set and get the pattern, respectively.
2682 <code>TPatternFormField
</code> provides a default implementation of these two methods.
</p>
2683 <h4 id=
"iplaceholderformfield"><code>IPlaceholderFormField
</code><a class=
"headerlink" href=
"#iplaceholderformfield" title=
"Permanent link">#
</a></h4>
2684 <p><code>IPlaceholderFormField
</code> has to be implemented by form fields that support a placeholder value for empty fields.
2685 The implementing class has to implement the methods
<code>placeholder($languageItem = null, array $variables = [])
</code> and
<code>getPlaceholder()
</code>.
2686 <code>TPlaceholderFormField
</code> provides a default implementation of these two methods.
</p>
2687 <h4 id=
"iselectionformfield"><code>ISelectionFormField
</code><a class=
"headerlink" href=
"#iselectionformfield" title=
"Permanent link">#
</a></h4>
2688 <p><code>ISelectionFormField
</code> has to be implemented by form fields with a predefined set of possible values.
2689 The implementing class has to implement the getter and setter methods
<code>options($options, $nestedOptions = false, $labelLanguageItems = true)
</code> and
<code>getOptions()
</code> and additionally two methods related to nesting, i.e. whether the selectable options have a hierarchy:
2690 <code>supportsNestedOptions()
</code> and
<code>getNestedOptions()
</code>.
2691 <code>TSelectionFormField
</code> provides a default implementation of these four methods.
</p>
2692 <h4 id=
"isuffixedformfield"><code>ISuffixedFormField
</code><a class=
"headerlink" href=
"#isuffixedformfield" title=
"Permanent link">#
</a></h4>
2693 <p><code>ISuffixedFormField
</code> has to be implemented by form fields that support supports displaying a suffix behind the actual input field.
2694 The implementing class has to implement the methods
<code>suffix($languageItem = null, array $variables = [])
</code> and
<code>getSuffix()
</code>.
2695 <code>TSuffixedFormField
</code> provides a default implementation of these two methods.
</p>
2696 <h4 id=
"tdefaultidformfield"><code>TDefaultIdFormField
</code><a class=
"headerlink" href=
"#tdefaultidformfield" title=
"Permanent link">#
</a></h4>
2697 <p>Form fields that have a default id have to use
<code>TDefaultIdFormField
</code> and have to implement the method
<code>getDefaultId()
</code>.
</p>
2698 <h2 id=
"displaying-forms">Displaying Forms
<a class=
"headerlink" href=
"#displaying-forms" title=
"Permanent link">#
</a></h2>
2699 <p>The only thing to do in a template to display the
<strong>whole
</strong> form including all of the necessary JavaScript is to put
</p>
2700 <div class=
"highlight"><pre><span></span><code><span class=
"cp">{
</span><span class=
"o">@
</span><span class=
"nv">$form
</span><span class=
"o">-
></span><span class=
"na">getHtml
</span><span class=
"o">()
</span><span class=
"cp">}
</span><span class=
"x"></span>
2702 <p>into the template file at the relevant position.
</p>
2708 <div class=
"md-source-date">
2711 Last update:
2021-
01-
16
2729 <footer class=
"md-footer">
2731 <nav class=
"md-footer__inner md-grid" aria-label=
"Footer">
2733 <a href=
"../overview/" class=
"md-footer__link md-footer__link--prev" rel=
"prev">
2734 <div class=
"md-footer__button md-icon">
2735 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 24 24"><path d=
"M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
2737 <div class=
"md-footer__title">
2738 <div class=
"md-ellipsis">
2739 <span class=
"md-footer__direction">
2748 <a href=
"../form_fields/" class=
"md-footer__link md-footer__link--next" rel=
"next">
2749 <div class=
"md-footer__title">
2750 <div class=
"md-ellipsis">
2751 <span class=
"md-footer__direction">
2757 <div class=
"md-footer__button md-icon">
2758 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 24 24"><path d=
"M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg>
2764 <div class=
"md-footer-meta md-typeset">
2765 <div class=
"md-footer-meta__inner md-grid">
2766 <div class=
"md-footer-copyright">
2768 <div class=
"md-footer-copyright__highlight">
2769 Copyright ©
2020 WoltLab GmbH
2773 <a href=
"https://squidfunk.github.io/mkdocs-material/" target=
"_blank" rel=
"noopener">
2778 <div class=
"md-footer-copyright">
2779 <a href=
"https://www.woltlab.com/legal-notice/">Legal Notice
</a>
2780 <a href=
"https://www.woltlab.com/privacy-policy/">Privacy Policy
</a>
2787 <div class=
"md-dialog" data-md-component=
"dialog">
2788 <div class=
"md-dialog__inner md-typeset"></div>
2790 <script id=
"__config" type=
"application/json">{
"base":
"../../../..",
"features": [],
"translations": {
"clipboard.copy":
"Copy to clipboard",
"clipboard.copied":
"Copied to clipboard",
"search.config.lang":
"en",
"search.config.pipeline":
"trimmer, stopWordFilter",
"search.config.separator":
"[\\s\\-]+",
"search.placeholder":
"Search",
"search.result.placeholder":
"Type to start searching",
"search.result.none":
"No matching documents",
"search.result.one":
"1 matching document",
"search.result.other":
"# matching documents",
"search.result.more.one":
"1 more on this page",
"search.result.more.other":
"# more on this page",
"search.result.term.missing":
"Missing"},
"search":
"../../../../assets/javascripts/workers/search.fb4a9340.min.js",
"version": {
"provider":
"mike"}}
</script>
2793 <script src=
"../../../../assets/javascripts/bundle.5cf3e710.min.js"></script>