Commit | Line | Data |
---|---|---|
d9cdc0cc TD |
1 | <!DOCTYPE html> |
2 | <head> | |
3 | <meta charset="utf-8"> | |
4 | <meta http-equiv="X-UA-Compatible" content="IE=edge"> | |
5 | <meta name="viewport" content="width=device-width, initial-scale=1"> | |
6 | <meta name="description" content=""> | |
7 | <meta name="keywords" content=" "> | |
8 | <title>Form Builder Fields | WoltLab Suite 5.3 Documentation</title> | |
9 | ||
e2f8eee7 | 10 | <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/syntax.css"> |
d9cdc0cc | 11 | <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,300,600"> |
e2f8eee7 | 12 | <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/font-awesome.min.css"> |
d9cdc0cc | 13 | <!--<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">--> |
e2f8eee7 TD |
14 | <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/modern-business.css"> |
15 | <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/lavish-bootstrap.css"> | |
16 | <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/customstyles.css"> | |
17 | <link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/theme-blue.css?v=3"> | |
d9cdc0cc | 18 | |
e2f8eee7 TD |
19 | <script src="https://docs.woltlab.com/5.3/js/jquery.min.js"></script> |
20 | <script src="https://docs.woltlab.com/5.3/js/jquery.cookie.min.js"></script> | |
21 | <script src="https://docs.woltlab.com/5.3/js/jquery.navgoco.min.js"></script> | |
22 | <script src="https://docs.woltlab.com/5.3/js/bootstrap.min.js"></script> | |
23 | <script src="https://docs.woltlab.com/5.3/js/anchor.min.js"></script> | |
24 | <script src="https://docs.woltlab.com/5.3/js/toc.js"></script> | |
25 | <script src="https://docs.woltlab.com/5.3/js/customscripts.js"></script> | |
d9cdc0cc | 26 | |
e2f8eee7 | 27 | <link rel="shortcut icon" href="https://docs.woltlab.com/5.3/images/favicon.ico"> |
d9cdc0cc | 28 | |
e2f8eee7 | 29 | <link rel="alternate" type="application/rss+xml" title="woltlab.github.io" href="https://docs.woltlab.com/5.3feed.xml"> |
d9cdc0cc TD |
30 | |
31 | <script> | |
32 | $(document).ready(function() { | |
33 | // Initialize navgoco with default options | |
34 | $("#mysidebar").navgoco({ | |
35 | caretHtml: '', | |
36 | accordion: true, | |
37 | openClass: 'active', // open | |
38 | save: false, // leave false or nav highlighting doesn't work right | |
39 | cookie: { | |
40 | name: 'navgoco', | |
41 | expires: false, | |
42 | path: '/' | |
43 | }, | |
44 | slide: { | |
45 | duration: 400, | |
46 | easing: 'swing' | |
47 | } | |
48 | }); | |
49 | ||
50 | $("#collapseAll").click(function(e) { | |
51 | e.preventDefault(); | |
52 | $("#mysidebar").navgoco('toggle', false); | |
53 | }); | |
54 | ||
55 | $("#expandAll").click(function(e) { | |
56 | e.preventDefault(); | |
57 | $("#mysidebar").navgoco('toggle', true); | |
58 | }); | |
59 | ||
60 | }); | |
61 | ||
62 | </script> | |
63 | <script> | |
64 | $(function () { | |
65 | $('[data-toggle="tooltip"]').tooltip() | |
66 | }) | |
67 | </script> | |
68 | ||
69 | ||
70 | </head> | |
71 | <body> | |
72 | <!-- Navigation --> | |
73 | <nav class="navbar navbar-inverse navbar-fixed-top"> | |
74 | <div class="container topnavlinks"> | |
75 | <div class="navbar-header"> | |
76 | <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1"> | |
77 | <span class="sr-only">Toggle navigation</span> | |
78 | <span class="icon-bar"></span> | |
79 | <span class="icon-bar"></span> | |
80 | <span class="icon-bar"></span> | |
81 | </button> | |
82 | <a class="fa fa-home fa-lg navbar-brand" href="index.html"> <span class="projectTitle"> WoltLab Suite 5.3 Documentation</span></a> | |
83 | </div> | |
84 | <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1"> | |
85 | <ul class="nav navbar-nav navbar-right"> | |
86 | <!-- entries without drop-downs appear here --> | |
87 | ||
88 | ||
89 | ||
90 | <li><a href="https://www.woltlab.com" target="_blank">woltlab.com</a></li> | |
91 | ||
92 | ||
93 | ||
94 | ||
95 | ||
96 | <li><a href="https://github.com/WoltLab/WCF/" target="_blank">Code on github.com</a></li> | |
97 | ||
98 | ||
99 | ||
100 | <!-- entries with drop-downs appear here --> | |
101 | <!-- conditional logic to control which topnav appears for the audience defined in the configuration file.--> | |
102 | ||
103 | ||
104 | <!--comment out this block if you want to hide search--> | |
105 | <li> | |
106 | <!--start search--> | |
107 | <div id="search-demo-container"> | |
108 | <input type="text" id="search-input" placeholder="search..."> | |
109 | <ul id="results-container"></ul> | |
110 | </div> | |
e2f8eee7 | 111 | <script src="https://docs.woltlab.com/5.3/js/jekyll-search.js" type="text/javascript"></script> |
d9cdc0cc TD |
112 | <script type="text/javascript"> |
113 | SimpleJekyllSearch.init({ | |
114 | searchInput: document.getElementById('search-input'), | |
115 | resultsContainer: document.getElementById('results-container'), | |
e2f8eee7 | 116 | dataSource: 'https://docs.woltlab.com/5.3/search.json', |
d9cdc0cc TD |
117 | searchResultTemplate: '<li><a href="{url}" title="Form Builder Fields">{title}</a></li>', |
118 | noResultsText: 'No results found.', | |
119 | limit: 10, | |
120 | fuzzy: true, | |
121 | }) | |
122 | </script> | |
123 | <!--end search--> | |
124 | </li> | |
125 | </ul> | |
126 | </div> | |
127 | </div> | |
128 | <!-- /.container --> | |
129 | </nav> | |
130 | ||
131 | ||
132 | <div class="container"> | |
133 | <div class="col-lg-12"> </div> | |
134 | ||
135 | <div class="row"> | |
136 | <div class="col-md-3"> | |
137 | ||
138 | ||
139 | ||
140 | <ul id="mysidebar" class="nav"> | |
141 | <li class="sidebarTitle">WoltLab Suite 5.3</li> | |
142 | ||
143 | ||
144 | ||
145 | <li> | |
146 | <a href="#">Getting Started</a> | |
147 | <ul> | |
148 | ||
149 | ||
150 | ||
151 | ||
152 | <li data-identifier="index"><a href="index.html">Introduction</a></li> | |
153 | ||
154 | ||
155 | ||
156 | ||
157 | ||
158 | ||
159 | ||
160 | ||
161 | <li data-identifier="getting-started_quick-start"><a href="getting-started_quick-start.html">Quick Start</a></li> | |
162 | ||
163 | ||
164 | ||
165 | ||
166 | ||
167 | </ul> | |
168 | </li> | |
169 | ||
170 | <li> | |
171 | <a href="#">PHP API</a> | |
172 | <ul> | |
173 | ||
174 | ||
175 | ||
176 | ||
177 | <li data-identifier="php_pages"><a href="php_pages.html">Pages</a></li> | |
178 | ||
179 | ||
180 | ||
181 | ||
182 | ||
183 | ||
184 | ||
185 | ||
186 | <li data-identifier="php_database-objects"><a href="php_database-objects.html">Database Objects</a></li> | |
187 | ||
188 | ||
189 | ||
190 | ||
191 | ||
192 | ||
193 | ||
194 | ||
195 | <li data-identifier="php_database-access"><a href="php_database-access.html">Database Access</a></li> | |
196 | ||
197 | ||
198 | ||
199 | ||
200 | ||
201 | ||
202 | ||
203 | ||
204 | <li data-identifier="php_exceptions"><a href="php_exceptions.html">Exceptions</a></li> | |
205 | ||
206 | ||
207 | ||
208 | ||
209 | ||
210 | ||
211 | ||
212 | ||
213 | <li class="subfolders"> | |
214 | <a href="#">API</a> | |
215 | <ul> | |
216 | ||
217 | ||
218 | ||
219 | <li data-identifier="php_api_caches"><a href="php_api_caches.html">Caches</a></li> | |
220 | ||
221 | ||
222 | ||
223 | ||
224 | <li data-identifier="php_api_comments"><a href="php_api_comments.html">Comments</a></li> | |
225 | ||
226 | ||
227 | ||
228 | ||
229 | <li data-identifier="php_api_cronjobs"><a href="php_api_cronjobs.html">Cronjobs</a></li> | |
230 | ||
231 | ||
232 | ||
233 | ||
234 | <li data-identifier="php_api_events"><a href="php_api_events.html">Events</a></li> | |
235 | ||
236 | ||
237 | ||
238 | ||
239 | <li data-identifier="php_api_form_builder"><a href="php_api_form_builder.html">Form Builder</a></li> | |
240 | ||
241 | ||
242 | ||
243 | ||
244 | <li data-identifier="php_api_package_installation_plugins"><a href="php_api_package_installation_plugins.html">Package Installation Plugins</a></li> | |
245 | ||
246 | ||
247 | ||
248 | ||
249 | <li data-identifier="php_api_user_activity_points"><a href="php_api_user_activity_points.html">User Activity Points</a></li> | |
250 | ||
251 | ||
252 | ||
253 | ||
254 | <li data-identifier="php_api_user_notifications"><a href="php_api_user_notifications.html">User Notifications</a></li> | |
255 | ||
256 | ||
257 | ||
258 | ||
259 | <li data-identifier="php_api_sitemaps"><a href="php_api_sitemaps.html">Sitemaps</a></li> | |
260 | ||
261 | ||
262 | </ul> | |
263 | </li> | |
264 | ||
265 | ||
266 | ||
267 | ||
268 | ||
269 | <li data-identifier="php_code-style"><a href="php_code-style.html">Code Style</a></li> | |
270 | ||
271 | ||
272 | ||
273 | ||
274 | ||
275 | ||
276 | ||
277 | ||
278 | <li data-identifier="php_apps"><a href="php_apps.html">Apps</a></li> | |
279 | ||
280 | ||
281 | ||
282 | ||
283 | ||
284 | ||
285 | ||
286 | ||
287 | <li data-identifier="php_gdpr"><a href="php_gdpr.html">GDPR</a></li> | |
288 | ||
289 | ||
290 | ||
291 | ||
292 | ||
293 | </ul> | |
294 | </li> | |
295 | ||
296 | <li> | |
297 | <a href="#">Languages, Templates & CSS</a> | |
298 | <ul> | |
299 | ||
300 | ||
301 | ||
302 | ||
303 | <li data-identifier="view_languages"><a href="view_languages.html">Languages</a></li> | |
304 | ||
305 | ||
306 | ||
307 | ||
308 | ||
309 | ||
310 | ||
311 | ||
312 | <li data-identifier="view_templates"><a href="view_templates.html">Templates</a></li> | |
313 | ||
314 | ||
315 | ||
316 | ||
317 | ||
318 | ||
319 | ||
320 | ||
321 | <li data-identifier="view_css"><a href="view_css.html">CSS</a></li> | |
322 | ||
323 | ||
324 | ||
325 | ||
326 | ||
327 | </ul> | |
328 | </li> | |
329 | ||
330 | <li> | |
331 | <a href="#">JavaScript API</a> | |
332 | <ul> | |
333 | ||
334 | ||
335 | ||
336 | ||
337 | <li data-identifier="javascript_general-usage"><a href="javascript_general-usage.html">General Usage</a></li> | |
338 | ||
339 | ||
340 | ||
341 | ||
342 | ||
343 | ||
344 | ||
345 | ||
346 | <li class="subfolders"> | |
347 | <a href="#">New API</a> | |
348 | <ul> | |
349 | ||
350 | ||
351 | ||
352 | <li data-identifier="javascript_new-api_writing-a-module"><a href="javascript_new-api_writing-a-module.html">Writing a module</a></li> | |
353 | ||
354 | ||
355 | ||
356 | ||
357 | <li data-identifier="javascript_new-api_data-structures"><a href="javascript_new-api_data-structures.html">Data Structures</a></li> | |
358 | ||
359 | ||
360 | ||
361 | ||
362 | <li data-identifier="javascript_new-api_core"><a href="javascript_new-api_core.html">Core Functions</a></li> | |
363 | ||
364 | ||
365 | ||
366 | ||
367 | <li data-identifier="javascript_new-api_dom"><a href="javascript_new-api_dom.html">DOM</a></li> | |
368 | ||
369 | ||
370 | ||
371 | ||
372 | <li data-identifier="javascript_new-api_events"><a href="javascript_new-api_events.html">Event Handling</a></li> | |
373 | ||
374 | ||
375 | ||
376 | ||
377 | <li data-identifier="javascript_new-api_ajax"><a href="javascript_new-api_ajax.html">Ajax</a></li> | |
378 | ||
379 | ||
380 | ||
381 | ||
382 | <li data-identifier="javascript_new-api_dialogs"><a href="javascript_new-api_dialogs.html">Dialogs</a></li> | |
383 | ||
384 | ||
385 | ||
386 | ||
387 | <li data-identifier="javascript_new-api_browser"><a href="javascript_new-api_browser.html">Browser and Screen Sizes</a></li> | |
388 | ||
389 | ||
390 | ||
391 | ||
392 | <li data-identifier="javascript_new-api_ui"><a href="javascript_new-api_ui.html">User Interface</a></li> | |
393 | ||
394 | ||
395 | </ul> | |
396 | </li> | |
397 | ||
398 | ||
399 | ||
400 | ||
401 | ||
402 | <li data-identifier="javascript_legacy-api"><a href="javascript_legacy-api.html">Legacy API</a></li> | |
403 | ||
404 | ||
405 | ||
406 | ||
407 | ||
408 | ||
409 | ||
410 | ||
411 | <li data-identifier="javascript_helper-functions"><a href="javascript_helper-functions.html">Helper Functions</a></li> | |
412 | ||
413 | ||
414 | ||
415 | ||
416 | ||
417 | ||
418 | ||
419 | ||
420 | <li data-identifier="javascript_code-snippets"><a href="javascript_code-snippets.html">Code Snippets</a></li> | |
421 | ||
422 | ||
423 | ||
424 | ||
425 | ||
426 | </ul> | |
427 | </li> | |
428 | ||
429 | <li> | |
430 | <a href="#">Package Components</a> | |
431 | <ul> | |
432 | ||
433 | ||
434 | ||
435 | ||
436 | <li data-identifier="package_package-xml"><a href="package_package-xml.html">package.xml</a></li> | |
437 | ||
438 | ||
439 | ||
440 | ||
441 | ||
442 | ||
443 | ||
444 | ||
445 | <li data-identifier="package_pip"><a href="package_pip.html">PIPs</a></li> | |
446 | ||
447 | ||
448 | ||
449 | ||
450 | ||
451 | </ul> | |
452 | </li> | |
453 | ||
454 | <li> | |
455 | <a href="#">Migration</a> | |
456 | <ul> | |
457 | ||
458 | ||
459 | ||
460 | ||
461 | <li class="subfolders"> | |
462 | <a href="#">Migrating from WSC 5.2</a> | |
463 | <ul> | |
464 | ||
465 | ||
466 | ||
467 | <li data-identifier="migration_wsc-52_php"><a href="migration_wsc-52_php.html">PHP API</a></li> | |
468 | ||
469 | ||
470 | ||
471 | ||
472 | <li data-identifier="migration_wsc-52_templates"><a href="migration_wsc-52_templates.html">Templates and Languages</a></li> | |
473 | ||
474 | ||
475 | ||
476 | ||
477 | <li data-identifier="migration_wsc-52_libraries"><a href="migration_wsc-52_libraries.html">Third Party Libraries</a></li> | |
478 | ||
479 | ||
480 | </ul> | |
481 | </li> | |
482 | ||
483 | <li class="subfolders"> | |
484 | <a href="#">Migrating from WSC 3.1</a> | |
485 | <ul> | |
486 | ||
487 | ||
488 | ||
489 | <li data-identifier="migration_wsc-31_php"><a href="migration_wsc-31_php.html">PHP API</a></li> | |
490 | ||
491 | ||
492 | </ul> | |
493 | </li> | |
494 | ||
495 | <li class="subfolders"> | |
496 | <a href="#">Migrating from WSC 3.0</a> | |
497 | <ul> | |
498 | ||
499 | ||
500 | ||
501 | <li data-identifier="migration_wsc-30_php"><a href="migration_wsc-30_php.html">PHP API</a></li> | |
502 | ||
503 | ||
504 | ||
505 | ||
506 | <li data-identifier="migration_wsc-30_javascript"><a href="migration_wsc-30_javascript.html">JavaScript API</a></li> | |
507 | ||
508 | ||
509 | ||
510 | ||
511 | <li data-identifier="migration_wsc-30_templates"><a href="migration_wsc-30_templates.html">Templates</a></li> | |
512 | ||
513 | ||
514 | ||
515 | ||
516 | <li data-identifier="migration_wsc-30_css"><a href="migration_wsc-30_css.html">CSS</a></li> | |
517 | ||
518 | ||
519 | ||
520 | ||
521 | <li data-identifier="migration_wsc-30_package"><a href="migration_wsc-30_package.html">Package Components</a></li> | |
522 | ||
523 | ||
524 | </ul> | |
525 | </li> | |
526 | ||
527 | <li class="subfolders"> | |
528 | <a href="#">Migrating from WCF 2.1</a> | |
529 | <ul> | |
530 | ||
531 | ||
532 | ||
533 | <li data-identifier="migration_wcf-21_php"><a href="migration_wcf-21_php.html">PHP API</a></li> | |
534 | ||
535 | ||
536 | ||
537 | ||
538 | <li data-identifier="migration_wcf-21_templates"><a href="migration_wcf-21_templates.html">Templates</a></li> | |
539 | ||
540 | ||
541 | ||
542 | ||
543 | <li data-identifier="migration_wcf-21_css"><a href="migration_wcf-21_css.html">CSS</a></li> | |
544 | ||
545 | ||
546 | ||
547 | ||
548 | <li data-identifier="migration_wcf-21_package"><a href="migration_wcf-21_package.html">Package Components</a></li> | |
549 | ||
550 | ||
551 | </ul> | |
552 | </li> | |
553 | ||
554 | ||
555 | </ul> | |
556 | </li> | |
557 | ||
558 | <li> | |
559 | <a href="#">Tutorials</a> | |
560 | <ul> | |
561 | ||
562 | ||
563 | ||
564 | ||
565 | <li data-identifier="tutorial_tutorial-series"><a href="tutorial_tutorial-series.html">Tutorial Series</a></li> | |
566 | ||
567 | ||
568 | ||
569 | ||
570 | ||
571 | </ul> | |
572 | </li> | |
573 | ||
574 | ||
575 | </ul> | |
576 | ||
577 | <script> | |
578 | (function() { | |
579 | var sidebar = $('#mysidebar'); | |
580 | var item = sidebar.find('.active'); | |
581 | if (item.length === 0) { | |
582 | var parent = 'php_api_form_builder'; | |
583 | if (parent) { | |
584 | sidebar.find('li[data-identifier="' + parent + '"]').addClass('active'); | |
585 | } | |
586 | } | |
587 | ||
588 | sidebar.find(".active").parents('li').toggleClass("active"); | |
589 | })(); | |
590 | </script> | |
591 | ||
592 | </div> | |
593 | ||
594 | <div class="col-md-9"> | |
595 | <div class="post-header"> | |
596 | <h1 class="post-title-main">Form Builder Fields</h1> | |
597 | </div> | |
598 | ||
599 | ||
600 | ||
601 | <div class="post-content"> | |
602 | ||
603 | ||
604 | ||
605 | ||
606 | ||
607 | <!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. --> | |
608 | <script> | |
609 | $( document ).ready(function() { | |
610 | // Handler for .ready() called. | |
611 | ||
612 | $('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' }); | |
613 | ||
614 | /* this offset helps account for the space taken up by the floating toolbar. */ | |
615 | $('#toc').on('click', 'a', function() { | |
616 | var target = $(this.getAttribute('href')) | |
617 | , scroll_target = target.offset().top | |
618 | ||
619 | $(window).scrollTop(scroll_target - 10); | |
620 | return false | |
621 | }) | |
622 | ||
623 | }); | |
624 | </script> | |
625 | ||
626 | <div id="toc"></div> | |
627 | ||
628 | ||
629 | ||
630 | <h2 id="abstract-form-fields">Abstract Form Fields</h2> | |
631 | ||
632 | <p>The following form field classes cannot be instantiated directly because they are abstract, but they can/must be used when creating own form field classes.</p> | |
633 | ||
634 | <h3 id="abstractformfield"><code class="language-plaintext highlighter-rouge">AbstractFormField</code></h3> | |
635 | ||
636 | <p><code class="language-plaintext highlighter-rouge">AbstractFormField</code> is the abstract default implementation of the <code class="language-plaintext highlighter-rouge">IFormField</code> interface and it is expected that every implementation of <code class="language-plaintext highlighter-rouge">IFormField</code> implements the interface by extending this class.</p> | |
637 | ||
638 | <h3 id="abstractnumericformfield"><code class="language-plaintext highlighter-rouge">AbstractNumericFormField</code></h3> | |
639 | ||
640 | <p><code class="language-plaintext highlighter-rouge">AbstractNumericFormField</code> is the abstract implementation of a form field handling a single numeric value. | |
641 | The class implements <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>, <code class="language-plaintext highlighter-rouge">IMaximumFormField</code>, <code class="language-plaintext highlighter-rouge">IMinimumFormField</code>, <code class="language-plaintext highlighter-rouge">INullableFormField</code>, <code class="language-plaintext highlighter-rouge">IPlaceholderFormField</code> and <code class="language-plaintext highlighter-rouge">ISuffixedFormField</code>. | |
642 | If the property <code class="language-plaintext highlighter-rouge">$integerValues</code> is <code class="language-plaintext highlighter-rouge">true</code>, the form field works with integer values, otherwise it works with floating point numbers. | |
643 | The methods <code class="language-plaintext highlighter-rouge">step($step = null)</code> and <code class="language-plaintext highlighter-rouge">getStep()</code> can be used to set and get the step attribute of the <code class="language-plaintext highlighter-rouge">input</code> element. | |
644 | The default step for form fields with integer values is <code class="language-plaintext highlighter-rouge">1</code>. | |
645 | Otherwise, the default step is <code class="language-plaintext highlighter-rouge">any</code>.</p> | |
646 | ||
647 | <h2 id="general-form-fields">General Form Fields</h2> | |
648 | ||
649 | <p>The following form fields are general reusable fields without any underlying context.</p> | |
650 | ||
651 | <h3 id="booleanformfield"><code class="language-plaintext highlighter-rouge">BooleanFormField</code></h3> | |
652 | ||
653 | <p><code class="language-plaintext highlighter-rouge">BooleanFormField</code> is used for boolean (<code class="language-plaintext highlighter-rouge">0</code> or <code class="language-plaintext highlighter-rouge">1</code>, <code class="language-plaintext highlighter-rouge">yes</code> or <code class="language-plaintext highlighter-rouge">no</code>) values. | |
654 | Objects of this class require a label. | |
655 | The return value of <code class="language-plaintext highlighter-rouge">getSaveValue()</code> is the integer representation of the boolean value, i.e. <code class="language-plaintext highlighter-rouge">0</code> or <code class="language-plaintext highlighter-rouge">1</code>.</p> | |
656 | ||
657 | <h3 id="532-checkboxformfield"><span class="label label-info">5.3.2+</span> <code class="language-plaintext highlighter-rouge">CheckboxFormField</code></h3> | |
658 | ||
659 | <p><code class="language-plaintext highlighter-rouge">CheckboxFormField</code> extends <code class="language-plaintext highlighter-rouge">BooleanFormField</code> and offers a simple HTML checkbox.</p> | |
660 | ||
661 | <h3 id="classnameformfield"><code class="language-plaintext highlighter-rouge">ClassNameFormField</code></h3> | |
662 | ||
663 | <p><code class="language-plaintext highlighter-rouge">ClassNameFormField</code> is a <a href="#textformfield">text form field</a> that supports additional settings, specific to entering a PHP class name:</p> | |
664 | ||
665 | <ul> | |
666 | <li><code class="language-plaintext highlighter-rouge">classExists($classExists = true)</code> and <code class="language-plaintext highlighter-rouge">getClassExists()</code> can be used to ensure that the entered class currently exists in the installation. | |
667 | By default, the existance of the entered class is required.</li> | |
668 | <li><code class="language-plaintext highlighter-rouge">implementedInterface($interface)</code> and <code class="language-plaintext highlighter-rouge">getImplementedInterface()</code> can be used to ensure that the entered class implements the specified interface. | |
669 | By default, no interface is required.</li> | |
670 | <li><code class="language-plaintext highlighter-rouge">parentClass($parentClass)</code> and <code class="language-plaintext highlighter-rouge">getParentClass()</code> can be used to ensure that the entered class extends the specified class. | |
671 | By default, no parent class is required.</li> | |
672 | <li><code class="language-plaintext highlighter-rouge">instantiable($instantiable = true)</code> and <code class="language-plaintext highlighter-rouge">isInstantiable()</code> can be used to ensure that the entered class is instantiable. | |
673 | By default, entered classes have to instantiable.</li> | |
674 | </ul> | |
675 | ||
676 | <p>Additionally, the default id of a <code class="language-plaintext highlighter-rouge">ClassNameFormField</code> object is <code class="language-plaintext highlighter-rouge">className</code>, the default label is <code class="language-plaintext highlighter-rouge">wcf.form.field.className</code>, and if either an interface or a parent class is required, a default description is set if no description has already been set (<code class="language-plaintext highlighter-rouge">wcf.form.field.className.description.interface</code> and <code class="language-plaintext highlighter-rouge">wcf.form.field.className.description.parentClass</code>, respectively).</p> | |
677 | ||
678 | <h3 id="dateformfield"><code class="language-plaintext highlighter-rouge">DateFormField</code></h3> | |
679 | ||
680 | <p><code class="language-plaintext highlighter-rouge">DateFormField</code> is a form field to enter a date (and optionally a time). | |
681 | The following methods are specific to this form field class:</p> | |
682 | ||
683 | <ul> | |
684 | <li><code class="language-plaintext highlighter-rouge">earliestDate($earliestDate)</code> and <code class="language-plaintext highlighter-rouge">getEarliestDate()</code> can be used to get and set the earliest selectable/valid date and <code class="language-plaintext highlighter-rouge">latestDate($latestDate)</code> and <code class="language-plaintext highlighter-rouge">getLatestDate()</code> can be used to get and set the latest selectable/valid date. | |
685 | The date passed to the setters must have the same format as set via <code class="language-plaintext highlighter-rouge">saveValueFormat()</code>. | |
686 | If a custom format is used, that format has to be set via <code class="language-plaintext highlighter-rouge">saveValueFormat()</code> before calling any of the setters.</li> | |
687 | <li><code class="language-plaintext highlighter-rouge">saveValueFormat($saveValueFormat)</code> and <code class="language-plaintext highlighter-rouge">getSaveValueFormat()</code> can be used to specify the date format of the value returned by <code class="language-plaintext highlighter-rouge">getSaveValue()</code>. | |
688 | By default, <code class="language-plaintext highlighter-rouge">U</code> is used as format. | |
689 | The <a href="https://secure.php.net/manual/en/function.date.php">PHP manual</a> provides an overview of supported formats.</li> | |
690 | <li><code class="language-plaintext highlighter-rouge">supportTime($supportsTime = true)</code> and <code class="language-plaintext highlighter-rouge">supportsTime()</code> can be used to toggle whether, in addition to a date, a time can also be specified. | |
691 | By default, specifying a time is disabled.</li> | |
692 | </ul> | |
693 | ||
694 | <h3 id="descriptionformfield"><code class="language-plaintext highlighter-rouge">DescriptionFormField</code></h3> | |
695 | ||
696 | <p><code class="language-plaintext highlighter-rouge">DescriptionFormField</code> is a <a href="#multilinetextformfield">multi-line text form field</a> with <code class="language-plaintext highlighter-rouge">description</code> as the default id and <code class="language-plaintext highlighter-rouge">wcf.global.description</code> as the default label.</p> | |
697 | ||
698 | <h3 id="floatformfield"><code class="language-plaintext highlighter-rouge">FloatFormField</code></h3> | |
699 | ||
700 | <p><code class="language-plaintext highlighter-rouge">FloatFormField</code> is an implementation of <a href="#abstractnumericformfield">AbstractNumericFormField</a> for floating point numbers.</p> | |
701 | ||
702 | <h3 id="iconformfield"><code class="language-plaintext highlighter-rouge">IconFormField</code></h3> | |
703 | ||
704 | <p><code class="language-plaintext highlighter-rouge">IconFormField</code> is a form field to select a FontAwesome icon.</p> | |
705 | ||
706 | <h3 id="integerformfield"><code class="language-plaintext highlighter-rouge">IntegerFormField</code></h3> | |
707 | ||
708 | <p><code class="language-plaintext highlighter-rouge">IntegerFormField</code> is an implementation of <a href="#abstractnumericformfield">AbstractNumericFormField</a> for integers.</p> | |
709 | ||
710 | <h3 id="isdisabledformfield"><code class="language-plaintext highlighter-rouge">IsDisabledFormField</code></h3> | |
711 | ||
712 | <p><code class="language-plaintext highlighter-rouge">IsDisabledFormField</code> is a <a href="#booleanformfield">boolean form field</a> with <code class="language-plaintext highlighter-rouge">isDisabled</code> as the default id.</p> | |
713 | ||
714 | <h3 id="itemlistformfield"><code class="language-plaintext highlighter-rouge">ItemListFormField</code></h3> | |
715 | ||
716 | <p><code class="language-plaintext highlighter-rouge">ItemListFormField</code> is a form field in which multiple values can be entered and returned in different formats as save value. | |
717 | The <code class="language-plaintext highlighter-rouge">saveValueType($saveValueType)</code> and <code class="language-plaintext highlighter-rouge">getSaveValueType()</code> methods are specific to this form field class and determine the format of the save value. | |
718 | The following save value types are supported:</p> | |
719 | ||
720 | <ul> | |
721 | <li><code class="language-plaintext highlighter-rouge">ItemListFormField::SAVE_VALUE_TYPE_ARRAY</code> adds a custom data processor that writes the form field data directly in the parameters array and not in the data sub-array of the parameters array.</li> | |
722 | <li><code class="language-plaintext highlighter-rouge">ItemListFormField::SAVE_VALUE_TYPE_CSV</code> lets the value be returned as a string in which the values are concatenated by commas.</li> | |
723 | <li><code class="language-plaintext highlighter-rouge">ItemListFormField::SAVE_VALUE_TYPE_NSV</code> lets the value be returned as a string in which the values are concatenated by <code class="language-plaintext highlighter-rouge">\n</code>.</li> | |
724 | <li><code class="language-plaintext highlighter-rouge">ItemListFormField::SAVE_VALUE_TYPE_SSV</code> lets the value be returned as a string in which the values are concatenated by spaces.</li> | |
725 | </ul> | |
726 | ||
727 | <p>By default, <code class="language-plaintext highlighter-rouge">ItemListFormField::SAVE_VALUE_TYPE_CSV</code> is used.</p> | |
728 | ||
729 | <p>If <code class="language-plaintext highlighter-rouge">ItemListFormField::SAVE_VALUE_TYPE_ARRAY</code> is used as save value type, <code class="language-plaintext highlighter-rouge">ItemListFormField</code> objects register a <a href="php_api_form_builder-validation_data.html#customformfielddataprocessor">custom form field data processor</a> to add the relevant array into the <code class="language-plaintext highlighter-rouge">$parameters</code> array directly using the object property as the array key.</p> | |
730 | ||
731 | <h3 id="multilinetextformfield"><code class="language-plaintext highlighter-rouge">MultilineTextFormField</code></h3> | |
732 | ||
733 | <p><code class="language-plaintext highlighter-rouge">MultilineTextFormField</code> is a <a href="#textformfield">text form field</a> that supports multiple rows of text. | |
734 | The methods <code class="language-plaintext highlighter-rouge">rows($rows)</code> and <code class="language-plaintext highlighter-rouge">getRows()</code> can be used to set and get the number of rows of the <code class="language-plaintext highlighter-rouge">textarea</code> elements. | |
735 | The default number of rows is <code class="language-plaintext highlighter-rouge">10</code>. | |
736 | These methods do <strong>not</strong>, however, restrict the number of text rows that canbe entered.</p> | |
737 | ||
738 | <h3 id="multipleselectionformfield"><code class="language-plaintext highlighter-rouge">MultipleSelectionFormField</code></h3> | |
739 | ||
740 | <p><code class="language-plaintext highlighter-rouge">MultipleSelectionFormField</code> is a form fields that allows the selection of multiple options out of a predefined list of available options. | |
741 | The class implements <code class="language-plaintext highlighter-rouge">IFilterableSelectionFormField</code>, <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>, and <code class="language-plaintext highlighter-rouge">INullableFormField</code>. | |
742 | If the field is nullable and no option is selected, <code class="language-plaintext highlighter-rouge">null</code> is returned as the save value.</p> | |
743 | ||
744 | <h3 id="radiobuttonformfield"><code class="language-plaintext highlighter-rouge">RadioButtonFormField</code></h3> | |
745 | ||
746 | <p><code class="language-plaintext highlighter-rouge">RadioButtonFormField</code> is a form fields that allows the selection of a single option out of a predefined list of available options using radiobuttons. | |
747 | The class implements <code class="language-plaintext highlighter-rouge">IImmutableFormField</code> and <code class="language-plaintext highlighter-rouge">ISelectionFormField</code>.</p> | |
748 | ||
749 | <h3 id="ratingformfield"><code class="language-plaintext highlighter-rouge">RatingFormField</code></h3> | |
750 | ||
751 | <p><code class="language-plaintext highlighter-rouge">RatingFormField</code> is a form field to set a rating for an object. | |
752 | The class implements <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>, <code class="language-plaintext highlighter-rouge">IMaximumFormField</code>, <code class="language-plaintext highlighter-rouge">IMinimumFormField</code>, and <code class="language-plaintext highlighter-rouge">INullableFormField</code>. | |
753 | Form fields of this class have <code class="language-plaintext highlighter-rouge">rating</code> as their default id, <code class="language-plaintext highlighter-rouge">wcf.form.field.rating</code> as their default label, <code class="language-plaintext highlighter-rouge">1</code> as their default minimum, and <code class="language-plaintext highlighter-rouge">5</code> as their default maximum. | |
754 | For this field, the minimum and maximum refer to the minimum and maximum rating an object can get. | |
755 | When the field is shown, there will be <code class="language-plaintext highlighter-rouge">maximum() - minimum() + 1</code> icons be shown with additional CSS classes that can be set and gotten via <code class="language-plaintext highlighter-rouge">defaultCssClasses(array $cssClasses)</code> and <code class="language-plaintext highlighter-rouge">getDefaultCssClasses()</code>. | |
756 | If a rating values is set, the first <code class="language-plaintext highlighter-rouge">getValue()</code> icons will instead use the classes that can be set and gotten via <code class="language-plaintext highlighter-rouge">activeCssClasses(array $cssClasses)</code> and <code class="language-plaintext highlighter-rouge">getActiveCssClasses()</code>. | |
757 | By default, the only default class is <code class="language-plaintext highlighter-rouge">fa-star-o</code> and the active classes are <code class="language-plaintext highlighter-rouge">fa-star</code> and <code class="language-plaintext highlighter-rouge">orange</code>.</p> | |
758 | ||
759 | <h3 id="showorderformfield"><code class="language-plaintext highlighter-rouge">ShowOrderFormField</code></h3> | |
760 | ||
761 | <p><code class="language-plaintext highlighter-rouge">ShowOrderFormField</code> is a <a href="#singleselectionformfield">single selection form field</a> for which the selected value determines the position at which an object is shown. | |
762 | The show order field provides a list of all siblings and the object will be positioned <strong>after</strong> the selected sibling. | |
763 | To insert objects at the very beginning, the <code class="language-plaintext highlighter-rouge">options()</code> automatically method prepends an additional option for that case so that only the existing siblings need to be passed. | |
764 | The default id of instances of this class is <code class="language-plaintext highlighter-rouge">showOrder</code> and their default label is <code class="language-plaintext highlighter-rouge">wcf.form.field.showOrder</code>.</p> | |
765 | ||
766 | <div class="bs-callout bs-callout-info">It is important that the relevant object property is always kept updated. Whenever a new object is added or an existing object is edited or delete, the values of the other objects have to be adjusted to ensure consecutive numbering.</div> | |
767 | ||
768 | <h3 id="singleselectionformfield"><code class="language-plaintext highlighter-rouge">SingleSelectionFormField</code></h3> | |
769 | ||
770 | <p><code class="language-plaintext highlighter-rouge">SingleSelectionFormField</code> is a form fields that allows the selection of a single option out of a predefined list of available options. | |
771 | The class implements <code class="language-plaintext highlighter-rouge">IFilterableSelectionFormField</code>, <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>, and <code class="language-plaintext highlighter-rouge">INullableFormField</code>. | |
772 | If the field is nullable and the current form field value is considered <code class="language-plaintext highlighter-rouge">empty</code> by PHP, <code class="language-plaintext highlighter-rouge">null</code> is returned as the save value.</p> | |
773 | ||
774 | <h3 id="sortorderformfield"><code class="language-plaintext highlighter-rouge">SortOrderFormField</code></h3> | |
775 | ||
776 | <p><code class="language-plaintext highlighter-rouge">SingleSelectionFormField</code> is a <a href="#singleselectionformfield">single selection form field</a> with default id <code class="language-plaintext highlighter-rouge">sortOrder</code>, default label <code class="language-plaintext highlighter-rouge">wcf.global.showOrder</code> and default options <code class="language-plaintext highlighter-rouge">ASC: wcf.global.sortOrder.ascending</code> and <code class="language-plaintext highlighter-rouge">DESC: wcf.global.sortOrder.descending</code>.</p> | |
777 | ||
778 | <h3 id="textformfield"><code class="language-plaintext highlighter-rouge">TextFormField</code></h3> | |
779 | ||
780 | <p><code class="language-plaintext highlighter-rouge">TextFormField</code> is a form field that allows entering a single line of text. | |
781 | The class implements <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>, <code class="language-plaintext highlighter-rouge">II18nFormField</code>, <code class="language-plaintext highlighter-rouge">IMaximumLengthFormField</code>, <code class="language-plaintext highlighter-rouge">IMinimumLengthFormField</code>, and <code class="language-plaintext highlighter-rouge">IPlaceholderFormField</code>.</p> | |
782 | ||
783 | <h3 id="titleformfield"><code class="language-plaintext highlighter-rouge">TitleFormField</code></h3> | |
784 | ||
785 | <p><code class="language-plaintext highlighter-rouge">TitleFormField</code> is a <a href="#textformfield">text form field</a> with <code class="language-plaintext highlighter-rouge">title</code> as the default id and <code class="language-plaintext highlighter-rouge">wcf.global.title</code> as the default label.</p> | |
786 | ||
787 | <h3 id="urlformfield"><code class="language-plaintext highlighter-rouge">UrlFormField</code></h3> | |
788 | ||
789 | <p><code class="language-plaintext highlighter-rouge">UrlFormField</code> is a <a href="#textformfield">text form field</a> whose values are checked via <code class="language-plaintext highlighter-rouge">Url::is()</code>.</p> | |
790 | ||
791 | <h2 id="specific-fields">Specific Fields</h2> | |
792 | ||
793 | <p>The following form fields are reusable fields that generally are bound to a certain API or <code class="language-plaintext highlighter-rouge">DatabaseObject</code> implementation.</p> | |
794 | ||
795 | <h3 id="aclformfield"><code class="language-plaintext highlighter-rouge">AclFormField</code></h3> | |
796 | ||
797 | <p><code class="language-plaintext highlighter-rouge">AclFormField</code> is used for setting up acl values for specific objects. | |
798 | The class implements <code class="language-plaintext highlighter-rouge">IObjectTypeFormField</code> and requires an object type of the object type definition <code class="language-plaintext highlighter-rouge">com.woltlab.wcf.acl</code>. | |
799 | Additionally, the class provides the methods <code class="language-plaintext highlighter-rouge">categoryName($categoryName)</code> and <code class="language-plaintext highlighter-rouge">getCategoryName()</code> that allow setting a specific name or filter for the acl option categories whose acl options are shown. | |
800 | A category name of <code class="language-plaintext highlighter-rouge">null</code> signals that no category filter is used.</p> | |
801 | ||
802 | <p><code class="language-plaintext highlighter-rouge">AclFormField</code> objects register a <a href="php_api_form_builder-validation_data.html#customformfielddataprocessor">custom form field data processor</a> to add the relevant ACL object type id into the <code class="language-plaintext highlighter-rouge">$parameters</code> array directly using <code class="language-plaintext highlighter-rouge">{$objectProperty}_aclObjectTypeID</code> as the array key. | |
803 | The relevant database object action method is expected, based on the given ACL object type id, to save the ACL option values appropriately.</p> | |
804 | ||
805 | <h3 id="captchaformfield"><code class="language-plaintext highlighter-rouge">CaptchaFormField</code></h3> | |
806 | ||
807 | <p><code class="language-plaintext highlighter-rouge">CaptchaFormField</code> is used to add captcha protection to the form.</p> | |
808 | ||
809 | <p>You must specify a captcha object type (<code class="language-plaintext highlighter-rouge">com.woltlab.wcf.captcha</code>) using the <code class="language-plaintext highlighter-rouge">objectType()</code> method.</p> | |
810 | ||
811 | <h3 id="contentlanguageformfield"><code class="language-plaintext highlighter-rouge">ContentLanguageFormField</code></h3> | |
812 | ||
813 | <p><code class="language-plaintext highlighter-rouge">ContentLanguageFormField</code> is used to select the content language of an object. | |
814 | Fields of this class are only available if multilingualism is enabled and if there are content languages. | |
815 | The class implements <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>.</p> | |
816 | ||
817 | <h3 id="labelformfield"><code class="language-plaintext highlighter-rouge">LabelFormField</code></h3> | |
818 | ||
819 | <p><code class="language-plaintext highlighter-rouge">LabelFormField</code> is used to select a label from a specific label group. | |
820 | The class implements <code class="language-plaintext highlighter-rouge">IObjectTypeFormNode</code>.</p> | |
821 | ||
822 | <p>The <code class="language-plaintext highlighter-rouge">labelGroup(ViewableLabelGroup $labelGroup)</code> and <code class="language-plaintext highlighter-rouge">getLabelGroup()</code> methods are specific to this form field class and can be used to set and get the label group whose labels can be selected. | |
823 | Additionally, there is the static method <code class="language-plaintext highlighter-rouge">createFields($objectType, array $labelGroups, $objectProperty = 'labelIDs)</code> that can be used to create all relevant label form fields for a given list of label groups. | |
824 | In most cases, <code class="language-plaintext highlighter-rouge">LabelFormField::createFields()</code> should be used.</p> | |
825 | ||
826 | <h3 id="optionformfield"><code class="language-plaintext highlighter-rouge">OptionFormField</code></h3> | |
827 | ||
828 | <p><code class="language-plaintext highlighter-rouge">OptionFormField</code> is an <a href="#itemlistformfield">item list form field</a> to set a list of options. | |
829 | The class implements <code class="language-plaintext highlighter-rouge">IPackagesFormField</code> and only options of the set packages are considered available. | |
830 | The default label of instances of this class is <code class="language-plaintext highlighter-rouge">wcf.form.field.option</code> and their default id is <code class="language-plaintext highlighter-rouge">options</code>.</p> | |
831 | ||
832 | <h3 id="simpleaclformfield"><code class="language-plaintext highlighter-rouge">SimpleAclFormField</code></h3> | |
833 | ||
834 | <p><code class="language-plaintext highlighter-rouge">SimpleAclFormField</code> is used for setting up simple acl values (one <code class="language-plaintext highlighter-rouge">yes</code>/<code class="language-plaintext highlighter-rouge">no</code> option per user and user group) for specific objects.</p> | |
835 | ||
836 | <p><code class="language-plaintext highlighter-rouge">SimpleAclFormField</code> objects register a <a href="php_api_form_builder-validation_data.html#customformfielddataprocessor">custom form field data processor</a> to add the relevant simple ACL data array into the <code class="language-plaintext highlighter-rouge">$parameters</code> array directly using the object property as the array key.</p> | |
837 | ||
838 | <h3 id="singlemediaselectionformfield"><code class="language-plaintext highlighter-rouge">SingleMediaSelectionFormField</code></h3> | |
839 | ||
840 | <p><code class="language-plaintext highlighter-rouge">SingleMediaSelectionFormField</code> is used to select a specific media file. | |
841 | The class implements <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>.</p> | |
842 | ||
843 | <p>The following methods are specific to this form field class:</p> | |
844 | ||
845 | <ul> | |
846 | <li><code class="language-plaintext highlighter-rouge">imageOnly($imageOnly = true)</code> and <code class="language-plaintext highlighter-rouge">isImageOnly()</code> can be used to set and check if only images may be selected.</li> | |
847 | <li><code class="language-plaintext highlighter-rouge">getMedia()</code> returns the media file based on the current field value if a field is set.</li> | |
848 | </ul> | |
849 | ||
850 | <h3 id="tagformfield"><code class="language-plaintext highlighter-rouge">TagFormField</code></h3> | |
851 | ||
852 | <p><code class="language-plaintext highlighter-rouge">TagFormField</code> is a form field to enter tags. | |
853 | Arrays passed to <code class="language-plaintext highlighter-rouge">TagFormField::values()</code> can contain tag names as strings and <code class="language-plaintext highlighter-rouge">Tag</code> objects. | |
854 | The default label of instances of this class is <code class="language-plaintext highlighter-rouge">wcf.tagging.tags</code> and their default description is <code class="language-plaintext highlighter-rouge">wcf.tagging.tags.description</code>.</p> | |
855 | ||
856 | <p><code class="language-plaintext highlighter-rouge">TagFormField</code> objects register a <a href="php_api_form_builder-validation_data.html#customformfielddataprocessor">custom form field data processor</a> to add the array with entered tag names into the <code class="language-plaintext highlighter-rouge">$parameters</code> array directly using the object property as the array key.</p> | |
857 | ||
858 | <h3 id="uploadformfield"><code class="language-plaintext highlighter-rouge">UploadFormField</code></h3> | |
859 | ||
860 | <p><code class="language-plaintext highlighter-rouge">UploadFormField</code> is a form field that allows uploading files by the user.</p> | |
861 | ||
862 | <p><code class="language-plaintext highlighter-rouge">UploadFormField</code> objects register a <a href="php_api_form_builder-validation_data.html#customformfielddataprocessor">custom form field data processor</a> to add the array of <code class="language-plaintext highlighter-rouge">wcf\system\file\upload\UploadFile\UploadFile</code> into the <code class="language-plaintext highlighter-rouge">$parameters</code> array directly using the object property as the array key. Also it registers the removed files as an array of <code class="language-plaintext highlighter-rouge">wcf\system\file\upload\UploadFile\UploadFile</code> into the <code class="language-plaintext highlighter-rouge">$parameters</code> array directly using the object property with the suffix <code class="language-plaintext highlighter-rouge">_removedFiles</code> as the array key.</p> | |
863 | ||
864 | <p>The field supports additional settings:</p> | |
865 | <ul> | |
866 | <li><code class="language-plaintext highlighter-rouge">imageOnly($imageOnly = true)</code> and <code class="language-plaintext highlighter-rouge">isImageOnly()</code> can be used to ensure that the uploaded files are only images.</li> | |
867 | <li><code class="language-plaintext highlighter-rouge">allowSvgImage($allowSvgImages = true)</code> and <code class="language-plaintext highlighter-rouge">svgImageAllowed()</code> can be used to allow SVG images, if the image only mode is enabled (otherwise, the method will throw an exception). By default, SVG images are not allowed.</li> | |
868 | </ul> | |
869 | ||
870 | <h4 id="provide-value-from-database-object">Provide value from database object</h4> | |
871 | ||
872 | <p>To provide values from a database object, you should implement the method <code class="language-plaintext highlighter-rouge">get{$objectProperty}UploadFileLocations()</code> to your database object class. This method must return an array of strings with the locations of the files.</p> | |
873 | ||
874 | <h4 id="process-files">Process files</h4> | |
875 | ||
876 | <p>To process files in the database object action class, you must <a href="https://secure.php.net/manual/en/function.rename.php"><code class="language-plaintext highlighter-rouge">rename</code></a> the file to the final destination. You get the temporary location, by calling the method <code class="language-plaintext highlighter-rouge">getLocation()</code> on the given <code class="language-plaintext highlighter-rouge">UploadFile</code> objects. After that, you call <code class="language-plaintext highlighter-rouge">setProcessed($location)</code> with <code class="language-plaintext highlighter-rouge">$location</code> contains the new file location. This method sets the <code class="language-plaintext highlighter-rouge">isProcessed</code> flag to true and saves the new location. For updating files, it is relevant, whether a given file is already processed or not. For this case, the <code class="language-plaintext highlighter-rouge">UploadFile</code> object has an method <code class="language-plaintext highlighter-rouge">isProcessed()</code> which indicates, whether a file is already processed or new uploaded.</p> | |
877 | ||
878 | <h3 id="userformfield"><code class="language-plaintext highlighter-rouge">UserFormField</code></h3> | |
879 | ||
880 | <p><code class="language-plaintext highlighter-rouge">UserFormField</code> is a form field to enter existing users. | |
881 | The class implements <code class="language-plaintext highlighter-rouge">IAutoFocusFormField</code>, <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>, <code class="language-plaintext highlighter-rouge">IMultipleFormField</code>, and <code class="language-plaintext highlighter-rouge">INullableFormField</code>. | |
882 | While the user is presented the names of the specified users in the user interface, the field returns the ids of the users as data. | |
883 | The relevant <code class="language-plaintext highlighter-rouge">UserProfile</code> objects can be accessed via the <code class="language-plaintext highlighter-rouge">getUsers()</code> method.</p> | |
884 | ||
885 | <h3 id="usergroupoptionformfield"><code class="language-plaintext highlighter-rouge">UserGroupOptionFormField</code></h3> | |
886 | ||
887 | <p><code class="language-plaintext highlighter-rouge">UserGroupOptionFormField</code> is an <a href="#itemlistformfield">item list form field</a> to set a list of user group options/permissions. | |
888 | The class implements <code class="language-plaintext highlighter-rouge">IPackagesFormField</code> and only user group options of the set packages are considered available. | |
889 | The default label of instances of this class is <code class="language-plaintext highlighter-rouge">wcf.form.field.userGroupOption</code> and their default id is <code class="language-plaintext highlighter-rouge">permissions</code>.</p> | |
890 | ||
891 | <h3 id="usernameformfield"><code class="language-plaintext highlighter-rouge">UsernameFormField</code></h3> | |
892 | ||
893 | <p><code class="language-plaintext highlighter-rouge">UsernameFormField</code> is used for entering one non-existing username. | |
894 | The class implements <code class="language-plaintext highlighter-rouge">IImmutableFormField</code>, <code class="language-plaintext highlighter-rouge">IMaximumLengthFormField</code>, <code class="language-plaintext highlighter-rouge">IMinimumLengthFormField</code>, <code class="language-plaintext highlighter-rouge">INullableFormField</code>, and <code class="language-plaintext highlighter-rouge">IPlaceholderFormField</code>. | |
895 | As usernames have a system-wide restriction of a minimum length of 3 and a maximum length of 100 characters, these values are also used as the default value for the field’s minimum and maximum length.</p> | |
896 | ||
897 | <h2 id="wysiwyg-form-container">Wysiwyg form container</h2> | |
898 | ||
899 | <p>To integrate a wysiwyg editor into a form, you have to create a <code class="language-plaintext highlighter-rouge">WysiwygFormContainer</code> object. | |
900 | This container takes care of creating all necessary form nodes listed below for a wysiwyg editor.</p> | |
901 | ||
902 | <div class="bs-callout bs-callout-warning">When creating the container object, its id has to be the id of the form field that will manage the actual text.</div> | |
903 | ||
904 | <p>The following methods are specific to this form container class:</p> | |
905 | ||
906 | <ul> | |
907 | <li><code class="language-plaintext highlighter-rouge">addSettingsNode(IFormChildNode $settingsNode)</code> and <code class="language-plaintext highlighter-rouge">addSettingsNodes(array $settingsNodes)</code> can be used to add nodes to the settings tab container.</li> | |
908 | <li><code class="language-plaintext highlighter-rouge">attachmentData($objectType, $parentObjectID)</code> can be used to set the data relevant for attachment support. | |
909 | By default, not attachment data is set, thus attachments are not supported.</li> | |
910 | <li><code class="language-plaintext highlighter-rouge">getAttachmentField()</code>, <code class="language-plaintext highlighter-rouge">getPollContainer()</code>, <code class="language-plaintext highlighter-rouge">getSettingsContainer()</code>, <code class="language-plaintext highlighter-rouge">getSmiliesContainer()</code>, and <code class="language-plaintext highlighter-rouge">getWysiwygField()</code> can be used to get the different components of the wysiwyg form container once the form has been built.</li> | |
911 | <li><code class="language-plaintext highlighter-rouge">enablePreviewButton($enablePreviewButton)</code> can be used to set whether the preview button for the message is shown or not. | |
912 | By default, the preview button is shown. | |
913 | This method is only relevant before the form is built. | |
914 | Afterwards, the preview button availability can not be changed. | |
915 | Only available since WoltLab Suite Core 5.3.</li> | |
916 | <li><code class="language-plaintext highlighter-rouge">getObjectId()</code> returns the id of the edited object or <code class="language-plaintext highlighter-rouge">0</code> if no object is edited.</li> | |
917 | <li><code class="language-plaintext highlighter-rouge">getPreselect()</code>, <code class="language-plaintext highlighter-rouge">preselect($preselect)</code> can be used to set the value of the wysiwyg tab menu’s <code class="language-plaintext highlighter-rouge">data-preselect</code> attribute used to determine which tab is preselected. | |
918 | By default, the preselect is <code class="language-plaintext highlighter-rouge">'true'</code> which is used to pre-select the first tab.</li> | |
919 | <li><code class="language-plaintext highlighter-rouge">messageObjectType($messageObjectType)</code> can be used to set the message object type.</li> | |
920 | <li><code class="language-plaintext highlighter-rouge">pollObjectType($pollObjectType)</code> can be used to set the poll object type. | |
921 | By default, no poll object type is set, thus the poll form field container is not available.</li> | |
922 | <li><code class="language-plaintext highlighter-rouge">supportMentions($supportMentions)</code> can be used to set if mentions are supported. | |
923 | By default, mentions are not supported. | |
924 | This method is only relevant before the form is built. | |
925 | Afterwards, mention support can only be changed via the wysiwyg form field.</li> | |
926 | <li><code class="language-plaintext highlighter-rouge">supportSmilies($supportSmilies)</code> can be used to set if smilies are supported. | |
927 | By default, smilies are supported. | |
928 | This method is only relevant before the form is built. | |
929 | Afterwards, smiley availability can only be changed via changing the availability of the smilies form container.</li> | |
930 | </ul> | |
931 | ||
932 | <h3 id="wysiwygattachmentformfield"><code class="language-plaintext highlighter-rouge">WysiwygAttachmentFormField</code></h3> | |
933 | ||
934 | <p><code class="language-plaintext highlighter-rouge">WysiwygAttachmentFormField</code> provides attachment support for a wysiwyg editor via a tab in the menu below the editor. | |
935 | This class should not be used directly but only via <code class="language-plaintext highlighter-rouge">WysiwygFormContainer</code>. | |
936 | The methods <code class="language-plaintext highlighter-rouge">attachmentHandler(AttachmentHandler $attachmentHandler)</code> and <code class="language-plaintext highlighter-rouge">getAttachmentHandler()</code> can be used to set and get the <code class="language-plaintext highlighter-rouge">AttachmentHandler</code> object that is used for uploaded attachments.</p> | |
937 | ||
938 | <h3 id="wysiwygpollformcontainer"><code class="language-plaintext highlighter-rouge">WysiwygPollFormContainer</code></h3> | |
939 | ||
940 | <p><code class="language-plaintext highlighter-rouge">WysiwygPollFormContainer</code> provides poll support for a wysiwyg editor via a tab in the menu below the editor. | |
941 | This class should not be used directly but only via <code class="language-plaintext highlighter-rouge">WysiwygFormContainer</code>. | |
942 | <code class="language-plaintext highlighter-rouge">WysiwygPollFormContainer</code> contains all form fields that are required to create polls and requires edited objects to implement <code class="language-plaintext highlighter-rouge">IPollContainer</code>.</p> | |
943 | ||
944 | <p>The following methods are specific to this form container class:</p> | |
945 | ||
946 | <ul> | |
947 | <li><code class="language-plaintext highlighter-rouge">getEndTimeField()</code> returns the form field to set the end time of the poll once the form has been built.</li> | |
948 | <li><code class="language-plaintext highlighter-rouge">getIsChangeableField()</code> returns the form field to set if poll votes can be changed once the form has been built.</li> | |
949 | <li><code class="language-plaintext highlighter-rouge">getIsPublicField()</code> returns the form field to set if poll results are public once the form has been built.</li> | |
950 | <li><code class="language-plaintext highlighter-rouge">getMaxVotesField()</code> returns the form field to set the maximum number of votes once the form has been built.</li> | |
951 | <li><code class="language-plaintext highlighter-rouge">getOptionsField()</code> returns the form field to set the poll options once the form has been built.</li> | |
952 | <li><code class="language-plaintext highlighter-rouge">getQuestionField()</code> returns the form field to set the poll question once the form has been built.</li> | |
953 | <li><code class="language-plaintext highlighter-rouge">getResultsRequireVoteField()</code> returns the form field to set if viewing the poll results requires voting once the form has been built.</li> | |
954 | <li><code class="language-plaintext highlighter-rouge">getSortByVotesField()</code> returns the form field to set if the results are sorted by votes once the form has been built.</li> | |
955 | </ul> | |
956 | ||
957 | <h3 id="wysiwygsmileyformcontainer"><code class="language-plaintext highlighter-rouge">WysiwygSmileyFormContainer</code></h3> | |
958 | ||
959 | <p><code class="language-plaintext highlighter-rouge">WysiwygSmileyFormContainer</code> provides smiley support for a wysiwyg editor via a tab in the menu below the editor. | |
960 | This class should not be used directly but only via <code class="language-plaintext highlighter-rouge">WysiwygFormContainer</code>. | |
961 | <code class="language-plaintext highlighter-rouge">WysiwygSmileyFormContainer</code> creates a sub-tab for each smiley category.</p> | |
962 | ||
963 | <h4 id="wysiwygsmileyformnode"><code class="language-plaintext highlighter-rouge">WysiwygSmileyFormNode</code></h4> | |
964 | ||
965 | <p><code class="language-plaintext highlighter-rouge">WysiwygSmileyFormNode</code> is contains the smilies of a specific category. | |
966 | This class should not be used directly but only via <code class="language-plaintext highlighter-rouge">WysiwygSmileyFormContainer</code>.</p> | |
967 | ||
968 | <h3 id="example">Example</h3> | |
969 | ||
970 | <p>The following code creates a WYSIWYG editor component for a <code class="language-plaintext highlighter-rouge">message</code> object property. | |
971 | As smilies are supported by default and an attachment object type is given, the tab menu below the editor has two tabs: “Smilies” and “Attachments”. | |
972 | Additionally, mentions and quotes are supported.</p> | |
973 | ||
974 | <div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">WysiwygFormContainer</span><span class="o">::</span><span class="na">create</span><span class="p">(</span><span class="s1">'message'</span><span class="p">)</span> | |
975 | <span class="o">-></span><span class="na">label</span><span class="p">(</span><span class="s1">'foo.bar.message'</span><span class="p">)</span> | |
976 | <span class="o">-></span><span class="na">messageObjectType</span><span class="p">(</span><span class="s1">'com.example.foo.bar'</span><span class="p">)</span> | |
977 | <span class="o">-></span><span class="na">attachmentData</span><span class="p">(</span><span class="s1">'com.example.foo.bar'</span><span class="p">)</span> | |
978 | <span class="o">-></span><span class="na">supportMentions</span><span class="p">()</span> | |
979 | <span class="o">-></span><span class="na">supportQuotes</span><span class="p">()</span> | |
980 | </code></pre></div></div> | |
981 | ||
982 | <h3 id="wysiwygformfield"><code class="language-plaintext highlighter-rouge">WysiwygFormField</code></h3> | |
983 | ||
984 | <p><code class="language-plaintext highlighter-rouge">WysiwygFormField</code> is used for wysiwyg editor form fields. | |
985 | This class should, in general, not be used directly but only via <code class="language-plaintext highlighter-rouge">WysiwygFormContainer</code>. | |
986 | The class implements <code class="language-plaintext highlighter-rouge">IMaximumLengthFormField</code>, <code class="language-plaintext highlighter-rouge">IMinimumLengthFormField</code>, and <code class="language-plaintext highlighter-rouge">IObjectTypeFormNode</code> and requires an object type of the object type definition <code class="language-plaintext highlighter-rouge">com.woltlab.wcf.message</code>. | |
987 | The following methods are specific to this form field class:</p> | |
988 | ||
989 | <ul> | |
990 | <li><code class="language-plaintext highlighter-rouge">autosaveId($autosaveId)</code> and <code class="language-plaintext highlighter-rouge">getAutosaveId()</code> can be used enable automatically saving the current editor contents in the browser using the given id. | |
991 | An empty string signals that autosaving is disabled.</li> | |
992 | <li><code class="language-plaintext highlighter-rouge">lastEditTime($lastEditTime)</code> and <code class="language-plaintext highlighter-rouge">getLastEditTime()</code> can be used to set the last time the contents have been edited and saved so that the JavaScript can determine if the contents stored in the browser are older or newer. | |
993 | <code class="language-plaintext highlighter-rouge">0</code> signals that no last edit time has been set.</li> | |
994 | <li> | |
995 | <p><code class="language-plaintext highlighter-rouge">supportAttachments($supportAttachments)</code> and <code class="language-plaintext highlighter-rouge">supportsAttachments()</code> can be used to set and check if the form field supports attachments.</p> | |
996 | ||
997 | <div class="bs-callout bs-callout-warning">It is not sufficient to simply signal attachment support via these methods for attachments to work. These methods are relevant internally to signal the Javascript code that the editor supports attachments. Actual attachment support is provided by <code class="language-plaintext highlighter-rouge">WysiwygAttachmentFormField</code>.</div> | |
998 | </li> | |
999 | <li><code class="language-plaintext highlighter-rouge">supportMentions($supportMentions)</code> and <code class="language-plaintext highlighter-rouge">supportsMentions()</code> can be used to set and check if the form field supports mentions of other users.</li> | |
1000 | </ul> | |
1001 | ||
1002 | <p><code class="language-plaintext highlighter-rouge">WysiwygFormField</code> objects register a <a href="php_api_form_builder-validation_data.html#customformfielddataprocessor">custom form field data processor</a> to add the relevant simple ACL data array into the <code class="language-plaintext highlighter-rouge">$parameters</code> array directly using the object property as the array key.</p> | |
1003 | ||
1004 | <h3 id="twysiwygformnode"><code class="language-plaintext highlighter-rouge">TWysiwygFormNode</code></h3> | |
1005 | ||
1006 | <p>All form nodes that need to know the id of the <code class="language-plaintext highlighter-rouge">WysiwygFormField</code> field should use <code class="language-plaintext highlighter-rouge">TWysiwygFormNode</code>. | |
1007 | This trait provides <code class="language-plaintext highlighter-rouge">getWysiwygId()</code> and <code class="language-plaintext highlighter-rouge">wysiwygId($wysiwygId)</code> to get and set the relevant wysiwyg editor id.</p> | |
1008 | ||
1009 | <h2 id="single-use-form-fields">Single-Use Form Fields</h2> | |
1010 | ||
1011 | <p>The following form fields are specific for certain forms and hardly reusable in other contexts.</p> | |
1012 | ||
1013 | <h3 id="bbcodeattributesformfield"><code class="language-plaintext highlighter-rouge">BBCodeAttributesFormField</code></h3> | |
1014 | ||
1015 | <p><code class="language-plaintext highlighter-rouge">DevtoolsProjectExcludedPackagesFormField</code> is a form field for setting the attributes of a BBCode.</p> | |
1016 | ||
1017 | <h3 id="devtoolsprojectexcludedpackagesformfield"><code class="language-plaintext highlighter-rouge">DevtoolsProjectExcludedPackagesFormField</code></h3> | |
1018 | ||
1019 | <p><code class="language-plaintext highlighter-rouge">DevtoolsProjectExcludedPackagesFormField</code> is a form field for setting the excluded packages of a devtools project.</p> | |
1020 | ||
1021 | <h3 id="devtoolsprojectinstructionsformfield"><code class="language-plaintext highlighter-rouge">DevtoolsProjectInstructionsFormField</code></h3> | |
1022 | ||
1023 | <p><code class="language-plaintext highlighter-rouge">DevtoolsProjectExcludedPackagesFormField</code> is a form field for setting the installation and update instructions of a devtools project.</p> | |
1024 | ||
1025 | <h3 id="devtoolsprojectoptionalpackagesformfield"><code class="language-plaintext highlighter-rouge">DevtoolsProjectOptionalPackagesFormField</code></h3> | |
1026 | ||
1027 | <p><code class="language-plaintext highlighter-rouge">DevtoolsProjectExcludedPackagesFormField</code> is a form field for setting the optional packages of a devtools project.</p> | |
1028 | ||
1029 | <h3 id="devtoolsprojectrequiredpackagesformfield"><code class="language-plaintext highlighter-rouge">DevtoolsProjectRequiredPackagesFormField</code></h3> | |
1030 | ||
1031 | <p><code class="language-plaintext highlighter-rouge">DevtoolsProjectExcludedPackagesFormField</code> is a form field for setting the required packages of a devtools project.</p> | |
1032 | ||
1033 | ||
1034 | <div class="tags"> | |
1035 | ||
1036 | </div> | |
1037 | ||
1038 | ||
1039 | ||
1040 | </div> | |
1041 | ||
1042 | </div> | |
1043 | </div> | |
1044 | </div> | |
1045 | ||
1046 | <div class="footerBox"> | |
1047 | <div class="container"> | |
1048 | <div class="footerBoxLeft"> | |
1049 | ||
1050 | <a target="_blank" href="https://github.com/woltlab/woltlab.github.io/blob/master/pages/php/api/formBuilder/php_api_form_builder-form_fields.md" class="btn btn-default githubEditButton no_icon" role="button"><i class="fa fa-github fa-lg"></i> Edit on GitHub</a> | |
e2f8eee7 | 1051 | <p>Site last generated: Mar 5, 2021</p> |
d9cdc0cc TD |
1052 | </div> |
1053 | <div class="footerBoxRight"> | |
e2f8eee7 | 1054 | <a class="no_icon" href="https://www.woltlab.com"><img src="https://docs.woltlab.com/5.3/images/woltlab-black.png" srcset="https://docs.woltlab.com/5.3/images/woltlab-black@2x.png 2x" height="40" width="204" alt=""></a> |
d9cdc0cc TD |
1055 | </div> |
1056 | </div> | |
1057 | </div> | |
1058 | ||
1059 | <div class="pageFooter"> | |
1060 | <div class="container"> | |
1061 | © 2001 ‐ 2021 <a class="no_icon" href="https://www.woltlab.com">WoltLab GmbH</a>. All rights reserved. | <a class="no_icon" href="https://www.woltlab.com/legal-notice/">Legal Notice</a> | <a class="no_icon" href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a> | |
1062 | </div> | |
1063 | </div> | |
1064 | </body> | |
1065 | ||
1066 | </html> |