5.4/php/api/form_builder/overview/index.html

   1
   2 <!doctype html>
   3 <html lang="en" class="no-js">
   4   <head>
   5
   6       <meta charset="utf-8">
   7       <meta name="viewport" content="width=device-width,initial-scale=1">
   8
   9
  10
  11
  12       <link rel="icon" href="../../../../assets/default.favicon.ico">
  13       <meta name="generator" content="mkdocs-1.1.2, mkdocs-material-7.1.0">
  14
  15
  16
  17         <title>Overview - WoltLab Suite Documentation</title>
  18
  19
  20
  21       <link rel="stylesheet" href="../../../../assets/stylesheets/main.33e2939f.min.css">
  22
  23
  24         <link rel="stylesheet" href="../../../../assets/stylesheets/palette.ef6f36e2.min.css">
  25
  26
  27
  28           <meta name="theme-color" content="#009485">
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38       <link rel="stylesheet" href="../../../../stylesheets/extra.css">
  39
  40
  41
  42
  43
  44   </head>
  45
  46
  47
  48
  49
  50
  51
  52     <body dir="ltr" data-md-color-scheme="" data-md-color-primary="teal" data-md-color-accent="">
  53
  54
  55     <script>function __prefix(e){return new URL("../../../..",location).pathname+"."+e}function __get(e,t=localStorage){return JSON.parse(t.getItem(__prefix(e)))}</script>
  56
  57     <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
  58     <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
  59     <label class="md-overlay" for="__drawer"></label>
  60     <div data-md-component="skip">
  61
  62
  63         <a href="#form-builder" class="md-skip">
  64           Skip to content
  65         </a>
  66
  67     </div>
  68     <div data-md-component="announce">
  69
  70         <aside class="md-announce">
  71           <div class="md-announce__inner md-grid md-typeset">
  72
  73     <a href="https://www.woltlab.com">Back to <strong>woltlab.com</strong></a>
  74
  75           </div>
  76         </aside>
  77
  78     </div>
  79
  80       <header class="md-header" data-md-component="header">
  81   <nav class="md-header__inner md-grid" aria-label="Header">
  82     <a href="../../../.." title="WoltLab Suite Documentation" class="md-header__button md-logo" aria-label="WoltLab Suite Documentation" data-md-component="logo">
  83
  84   <img src="../../../../assets/logo.png" alt="logo">
  85
  86     </a>
  87     <label class="md-header__button md-icon" for="__drawer">
  88       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
  89     </label>
  90     <div class="md-header__title" data-md-component="header-title">
  91       <div class="md-header__ellipsis">
  92         <div class="md-header__topic">
  93           <span class="md-ellipsis">
  94             WoltLab Suite Documentation
  95           </span>
  96         </div>
  97         <div class="md-header__topic" data-md-component="header-topic">
  98           <span class="md-ellipsis">
  99
 100               Overview
 101
 102           </span>
 103         </div>
 104       </div>
 105     </div>
 106
 107
 108
 109       <label class="md-header__button md-icon" for="__search">
 110         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
 111       </label>
 112
 113 <div class="md-search" data-md-component="search" role="dialog">
 114   <label class="md-search__overlay" for="__search"></label>
 115   <div class="md-search__inner" role="search">
 116     <form class="md-search__form" name="search">
 117       <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
 118       <label class="md-search__icon md-icon" for="__search">
 119         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
 120         <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>
 121       </label>
 122       <button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1">
 123         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg>
 124       </button>
 125     </form>
 126     <div class="md-search__output">
 127       <div class="md-search__scrollwrap" data-md-scrollfix>
 128         <div class="md-search-result" data-md-component="search-result">
 129           <div class="md-search-result__meta">
 130             Initializing search
 131           </div>
 132           <ol class="md-search-result__list"></ol>
 133         </div>
 134       </div>
 135     </div>
 136   </div>
 137 </div>
 138
 139
 140       <div class="md-header__source">
 141
 142 <a href="https://github.com/WoltLab/docs.woltlab.com/" title="Go to repository" class="md-source" data-md-component="source">
 143   <div class="md-source__icon md-icon">
 144
 145     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 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>
 146   </div>
 147   <div class="md-source__repository">
 148     GitHub
 149   </div>
 150 </a>
 151       </div>
 152
 153   </nav>
 154 </header>
 155
 156     <div class="md-container" data-md-component="container">
 157
 158
 159
 160
 161       <main class="md-main" data-md-component="main">
 162         <div class="md-main__inner md-grid">
 163
 164
 165
 166               <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
 167                 <div class="md-sidebar__scrollwrap">
 168                   <div class="md-sidebar__inner">
 169
 170
 171
 172 <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
 173   <label class="md-nav__title" for="__drawer">
 174     <a href="../../../.." title="WoltLab Suite Documentation" class="md-nav__button md-logo" aria-label="WoltLab Suite Documentation" data-md-component="logo">
 175
 176   <img src="../../../../assets/logo.png" alt="logo">
 177
 178     </a>
 179     WoltLab Suite Documentation
 180   </label>
 181
 182     <div class="md-nav__source">
 183
 184 <a href="https://github.com/WoltLab/docs.woltlab.com/" title="Go to repository" class="md-source" data-md-component="source">
 185   <div class="md-source__icon md-icon">
 186
 187     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05 244 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>
 188   </div>
 189   <div class="md-source__repository">
 190     GitHub
 191   </div>
 192 </a>
 193     </div>
 194
 195   <ul class="md-nav__list" data-md-scrollfix>
 196
 197
 198
 199
 200
 201
 202
 203
 204     <li class="md-nav__item">
 205       <a href="../../../../getting-started/" class="md-nav__link">
 206         Getting Started
 207       </a>
 208     </li>
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222     <li class="md-nav__item md-nav__item--active md-nav__item--nested">
 223
 224
 225         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" checked>
 226
 227       <label class="md-nav__link" for="__nav_2">
 228         PHP API
 229         <span class="md-nav__icon md-icon"></span>
 230       </label>
 231       <nav class="md-nav" aria-label="PHP API" data-md-level="1">
 232         <label class="md-nav__title" for="__nav_2">
 233           <span class="md-nav__icon md-icon"></span>
 234           PHP API
 235         </label>
 236         <ul class="md-nav__list" data-md-scrollfix>
 237
 238
 239
 240
 241
 242     <li class="md-nav__item">
 243       <a href="../../../pages/" class="md-nav__link">
 244         Pages
 245       </a>
 246     </li>
 247
 248
 249
 250
 251
 252
 253
 254     <li class="md-nav__item">
 255       <a href="../../../database-objects/" class="md-nav__link">
 256         Database Objects
 257       </a>
 258     </li>
 259
 260
 261
 262
 263
 264
 265
 266     <li class="md-nav__item">
 267       <a href="../../../database-access/" class="md-nav__link">
 268         Database Access
 269       </a>
 270     </li>
 271
 272
 273
 274
 275
 276
 277
 278     <li class="md-nav__item">
 279       <a href="../../../exceptions/" class="md-nav__link">
 280         Exceptions
 281       </a>
 282     </li>
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293     <li class="md-nav__item md-nav__item--active md-nav__item--nested">
 294
 295
 296         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5" type="checkbox" id="__nav_2_5" checked>
 297
 298       <label class="md-nav__link" for="__nav_2_5">
 299         API
 300         <span class="md-nav__icon md-icon"></span>
 301       </label>
 302       <nav class="md-nav" aria-label="API" data-md-level="2">
 303         <label class="md-nav__title" for="__nav_2_5">
 304           <span class="md-nav__icon md-icon"></span>
 305           API
 306         </label>
 307         <ul class="md-nav__list" data-md-scrollfix>
 308
 309
 310
 311
 312
 313
 314     <li class="md-nav__item md-nav__item--nested">
 315
 316
 317         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5_1" type="checkbox" id="__nav_2_5_1" >
 318
 319       <label class="md-nav__link" for="__nav_2_5_1">
 320         Caches
 321         <span class="md-nav__icon md-icon"></span>
 322       </label>
 323       <nav class="md-nav" aria-label="Caches" data-md-level="3">
 324         <label class="md-nav__title" for="__nav_2_5_1">
 325           <span class="md-nav__icon md-icon"></span>
 326           Caches
 327         </label>
 328         <ul class="md-nav__list" data-md-scrollfix>
 329
 330
 331
 332
 333
 334     <li class="md-nav__item">
 335       <a href="../../caches/" class="md-nav__link">
 336         Overview
 337       </a>
 338     </li>
 339
 340
 341
 342
 343
 344
 345
 346     <li class="md-nav__item">
 347       <a href="../../caches_persistent-caches/" class="md-nav__link">
 348         Persistent Caches
 349       </a>
 350     </li>
 351
 352
 353
 354
 355
 356
 357
 358     <li class="md-nav__item">
 359       <a href="../../caches_runtime-caches/" class="md-nav__link">
 360         Runtime Caches
 361       </a>
 362     </li>
 363
 364
 365
 366         </ul>
 367       </nav>
 368     </li>
 369
 370
 371
 372
 373
 374
 375
 376     <li class="md-nav__item">
 377       <a href="../../comments/" class="md-nav__link">
 378         Comments
 379       </a>
 380     </li>
 381
 382
 383
 384
 385
 386
 387
 388     <li class="md-nav__item">
 389       <a href="../../cronjobs/" class="md-nav__link">
 390         Cronjobs
 391       </a>
 392     </li>
 393
 394
 395
 396
 397
 398
 399
 400     <li class="md-nav__item">
 401       <a href="../../events/" class="md-nav__link">
 402         Events
 403       </a>
 404     </li>
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415     <li class="md-nav__item md-nav__item--active md-nav__item--nested">
 416
 417
 418         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5_5" type="checkbox" id="__nav_2_5_5" checked>
 419
 420       <label class="md-nav__link" for="__nav_2_5_5">
 421         Form Builder
 422         <span class="md-nav__icon md-icon"></span>
 423       </label>
 424       <nav class="md-nav" aria-label="Form Builder" data-md-level="3">
 425         <label class="md-nav__title" for="__nav_2_5_5">
 426           <span class="md-nav__icon md-icon"></span>
 427           Form Builder
 428         </label>
 429         <ul class="md-nav__list" data-md-scrollfix>
 430
 431
 432
 433
 434
 435
 436
 437     <li class="md-nav__item md-nav__item--active">
 438
 439       <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
 440
 441
 442
 443
 444         <label class="md-nav__link md-nav__link--active" for="__toc">
 445           Overview
 446           <span class="md-nav__icon md-icon"></span>
 447         </label>
 448
 449       <a href="./" class="md-nav__link md-nav__link--active">
 450         Overview
 451       </a>
 452
 453
 454 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
 455
 456
 457
 458
 459
 460     <label class="md-nav__title" for="__toc">
 461       <span class="md-nav__icon md-icon"></span>
 462       Table of contents
 463     </label>
 464     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 465
 466         <li class="md-nav__item">
 467   <a href="#advantages-of-form-builder" class="md-nav__link">
 468     Advantages of Form Builder
 469   </a>
 470
 471 </li>
 472
 473         <li class="md-nav__item">
 474   <a href="#form-builder-components" class="md-nav__link">
 475     Form Builder Components
 476   </a>
 477
 478 </li>
 479
 480         <li class="md-nav__item">
 481   <a href="#abstractformbuilderform" class="md-nav__link">
 482     AbstractFormBuilderForm
 483   </a>
 484
 485 </li>
 486
 487         <li class="md-nav__item">
 488   <a href="#dialogformdocument" class="md-nav__link">
 489     DialogFormDocument
 490   </a>
 491
 492 </li>
 493
 494     </ul>
 495
 496 </nav>
 497
 498     </li>
 499
 500
 501
 502
 503
 504
 505
 506     <li class="md-nav__item">
 507       <a href="../structure/" class="md-nav__link">
 508         Structure
 509       </a>
 510     </li>
 511
 512
 513
 514
 515
 516
 517
 518     <li class="md-nav__item">
 519       <a href="../form_fields/" class="md-nav__link">
 520         Fields
 521       </a>
 522     </li>
 523
 524
 525
 526
 527
 528
 529
 530     <li class="md-nav__item">
 531       <a href="../validation_data/" class="md-nav__link">
 532         Validation and Data
 533       </a>
 534     </li>
 535
 536
 537
 538
 539
 540
 541
 542     <li class="md-nav__item">
 543       <a href="../dependencies/" class="md-nav__link">
 544         Dependencies
 545       </a>
 546     </li>
 547
 548
 549
 550         </ul>
 551       </nav>
 552     </li>
 553
 554
 555
 556
 557
 558
 559
 560     <li class="md-nav__item">
 561       <a href="../../package_installation_plugins/" class="md-nav__link">
 562         Package Installation Plugins
 563       </a>
 564     </li>
 565
 566
 567
 568
 569
 570
 571
 572     <li class="md-nav__item">
 573       <a href="../../user_activity_points/" class="md-nav__link">
 574         User Activity Points
 575       </a>
 576     </li>
 577
 578
 579
 580
 581
 582
 583
 584     <li class="md-nav__item">
 585       <a href="../../user_notifications/" class="md-nav__link">
 586         User Notifications
 587       </a>
 588     </li>
 589
 590
 591
 592
 593
 594
 595
 596     <li class="md-nav__item">
 597       <a href="../../sitemaps/" class="md-nav__link">
 598         Sitemaps
 599       </a>
 600     </li>
 601
 602
 603
 604         </ul>
 605       </nav>
 606     </li>
 607
 608
 609
 610
 611
 612
 613
 614     <li class="md-nav__item">
 615       <a href="../../../code-style/" class="md-nav__link">
 616         Code Style
 617       </a>
 618     </li>
 619
 620
 621
 622
 623
 624
 625
 626     <li class="md-nav__item">
 627       <a href="../../../apps/" class="md-nav__link">
 628         Apps
 629       </a>
 630     </li>
 631
 632
 633
 634
 635
 636
 637
 638     <li class="md-nav__item">
 639       <a href="../../../gdpr/" class="md-nav__link">
 640         GDPR
 641       </a>
 642     </li>
 643
 644
 645
 646         </ul>
 647       </nav>
 648     </li>
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660     <li class="md-nav__item md-nav__item--nested">
 661
 662
 663         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" >
 664
 665       <label class="md-nav__link" for="__nav_3">
 666         Languages, Templates & CSS
 667         <span class="md-nav__icon md-icon"></span>
 668       </label>
 669       <nav class="md-nav" aria-label="Languages, Templates & CSS" data-md-level="1">
 670         <label class="md-nav__title" for="__nav_3">
 671           <span class="md-nav__icon md-icon"></span>
 672           Languages, Templates & CSS
 673         </label>
 674         <ul class="md-nav__list" data-md-scrollfix>
 675
 676
 677
 678
 679
 680     <li class="md-nav__item">
 681       <a href="../../../../view/languages/" class="md-nav__link">
 682         Languages
 683       </a>
 684     </li>
 685
 686
 687
 688
 689
 690
 691
 692     <li class="md-nav__item">
 693       <a href="../../../../view/templates/" class="md-nav__link">
 694         Templates
 695       </a>
 696     </li>
 697
 698
 699
 700
 701
 702
 703
 704     <li class="md-nav__item">
 705       <a href="../../../../view/template-plugins/" class="md-nav__link">
 706         Template Plugins
 707       </a>
 708     </li>
 709
 710
 711
 712
 713
 714
 715
 716     <li class="md-nav__item">
 717       <a href="../../../../view/css/" class="md-nav__link">
 718         CSS
 719       </a>
 720     </li>
 721
 722
 723
 724         </ul>
 725       </nav>
 726     </li>
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738     <li class="md-nav__item md-nav__item--nested">
 739
 740
 741         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" >
 742
 743       <label class="md-nav__link" for="__nav_4">
 744         TypeScript and JavaScript API
 745         <span class="md-nav__icon md-icon"></span>
 746       </label>
 747       <nav class="md-nav" aria-label="TypeScript and JavaScript API" data-md-level="1">
 748         <label class="md-nav__title" for="__nav_4">
 749           <span class="md-nav__icon md-icon"></span>
 750           TypeScript and JavaScript API
 751         </label>
 752         <ul class="md-nav__list" data-md-scrollfix>
 753
 754
 755
 756
 757
 758     <li class="md-nav__item">
 759       <a href="../../../../javascript/general-usage/" class="md-nav__link">
 760         General Usage
 761       </a>
 762     </li>
 763
 764
 765
 766
 767
 768
 769
 770     <li class="md-nav__item">
 771       <a href="../../../../javascript/typescript/" class="md-nav__link">
 772         TypeScript
 773       </a>
 774     </li>
 775
 776
 777
 778
 779
 780
 781
 782
 783     <li class="md-nav__item md-nav__item--nested">
 784
 785
 786         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4_3" type="checkbox" id="__nav_4_3" >
 787
 788       <label class="md-nav__link" for="__nav_4_3">
 789         New API
 790         <span class="md-nav__icon md-icon"></span>
 791       </label>
 792       <nav class="md-nav" aria-label="New API" data-md-level="2">
 793         <label class="md-nav__title" for="__nav_4_3">
 794           <span class="md-nav__icon md-icon"></span>
 795           New API
 796         </label>
 797         <ul class="md-nav__list" data-md-scrollfix>
 798
 799
 800
 801
 802
 803     <li class="md-nav__item">
 804       <a href="../../../../javascript/new-api_writing-a-module/" class="md-nav__link">
 805         Writing a module
 806       </a>
 807     </li>
 808
 809
 810
 811
 812
 813
 814
 815     <li class="md-nav__item">
 816       <a href="../../../../javascript/new-api_data-structures/" class="md-nav__link">
 817         Data Structures
 818       </a>
 819     </li>
 820
 821
 822
 823
 824
 825
 826
 827     <li class="md-nav__item">
 828       <a href="../../../../javascript/new-api_core/" class="md-nav__link">
 829         Core Functions
 830       </a>
 831     </li>
 832
 833
 834
 835
 836
 837
 838
 839     <li class="md-nav__item">
 840       <a href="../../../../javascript/new-api_dom/" class="md-nav__link">
 841         DOM
 842       </a>
 843     </li>
 844
 845
 846
 847
 848
 849
 850
 851     <li class="md-nav__item">
 852       <a href="../../../../javascript/new-api_events/" class="md-nav__link">
 853         Event Handling
 854       </a>
 855     </li>
 856
 857
 858
 859
 860
 861
 862
 863     <li class="md-nav__item">
 864       <a href="../../../../javascript/new-api_ajax/" class="md-nav__link">
 865         Ajax
 866       </a>
 867     </li>
 868
 869
 870
 871
 872
 873
 874
 875     <li class="md-nav__item">
 876       <a href="../../../../javascript/new-api_dialogs/" class="md-nav__link">
 877         Dialogs
 878       </a>
 879     </li>
 880
 881
 882
 883
 884
 885
 886
 887     <li class="md-nav__item">
 888       <a href="../../../../javascript/new-api_browser/" class="md-nav__link">
 889         Browser and Screen Sizes
 890       </a>
 891     </li>
 892
 893
 894
 895
 896
 897
 898
 899     <li class="md-nav__item">
 900       <a href="../../../../javascript/new-api_ui/" class="md-nav__link">
 901         User Interface
 902       </a>
 903     </li>
 904
 905
 906
 907         </ul>
 908       </nav>
 909     </li>
 910
 911
 912
 913
 914
 915
 916
 917     <li class="md-nav__item">
 918       <a href="../../../../javascript/legacy-api/" class="md-nav__link">
 919         Legacy API
 920       </a>
 921     </li>
 922
 923
 924
 925
 926
 927
 928
 929     <li class="md-nav__item">
 930       <a href="../../../../javascript/helper-functions/" class="md-nav__link">
 931         Helper Functions
 932       </a>
 933     </li>
 934
 935
 936
 937
 938
 939
 940
 941     <li class="md-nav__item">
 942       <a href="../../../../javascript/code-snippets/" class="md-nav__link">
 943         Code Snippets
 944       </a>
 945     </li>
 946
 947
 948
 949         </ul>
 950       </nav>
 951     </li>
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963     <li class="md-nav__item md-nav__item--nested">
 964
 965
 966         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
 967
 968       <label class="md-nav__link" for="__nav_5">
 969         Package Components
 970         <span class="md-nav__icon md-icon"></span>
 971       </label>
 972       <nav class="md-nav" aria-label="Package Components" data-md-level="1">
 973         <label class="md-nav__title" for="__nav_5">
 974           <span class="md-nav__icon md-icon"></span>
 975           Package Components
 976         </label>
 977         <ul class="md-nav__list" data-md-scrollfix>
 978
 979
 980
 981
 982
 983     <li class="md-nav__item">
 984       <a href="../../../../package/package-xml/" class="md-nav__link">
 985         package.xml
 986       </a>
 987     </li>
 988
 989
 990
 991
 992
 993
 994
 995
 996     <li class="md-nav__item md-nav__item--nested">
 997
 998
 999         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5_2" type="checkbox" id="__nav_5_2" >
1000
1001       <label class="md-nav__link" for="__nav_5_2">
1002         PIPs
1003         <span class="md-nav__icon md-icon"></span>
1004       </label>
1005       <nav class="md-nav" aria-label="PIPs" data-md-level="2">
1006         <label class="md-nav__title" for="__nav_5_2">
1007           <span class="md-nav__icon md-icon"></span>
1008           PIPs
1009         </label>
1010         <ul class="md-nav__list" data-md-scrollfix>
1011
1012
1013
1014
1015
1016     <li class="md-nav__item">
1017       <a href="../../../../package/pip/" class="md-nav__link">
1018         Overview
1019       </a>
1020     </li>
1021
1022
1023
1024
1025
1026
1027
1028     <li class="md-nav__item">
1029       <a href="../../../../package/pip/acl-option/" class="md-nav__link">
1030         aclOption
1031       </a>
1032     </li>
1033
1034
1035
1036
1037
1038
1039
1040     <li class="md-nav__item">
1041       <a href="../../../../package/pip/acp-menu/" class="md-nav__link">
1042         acpMenu
1043       </a>
1044     </li>
1045
1046
1047
1048
1049
1050
1051
1052     <li class="md-nav__item">
1053       <a href="../../../../package/pip/acp-search-provider/" class="md-nav__link">
1054         acpSearchProvider
1055       </a>
1056     </li>
1057
1058
1059
1060
1061
1062
1063
1064     <li class="md-nav__item">
1065       <a href="../../../../package/pip/acp-template/" class="md-nav__link">
1066         acpTemplate
1067       </a>
1068     </li>
1069
1070
1071
1072
1073
1074
1075
1076     <li class="md-nav__item">
1077       <a href="../../../../package/pip/bbcode/" class="md-nav__link">
1078         bbcode
1079       </a>
1080     </li>
1081
1082
1083
1084
1085
1086
1087
1088     <li class="md-nav__item">
1089       <a href="../../../../package/pip/box/" class="md-nav__link">
1090         box
1091       </a>
1092     </li>
1093
1094
1095
1096
1097
1098
1099
1100     <li class="md-nav__item">
1101       <a href="../../../../package/pip/clipboard-action/" class="md-nav__link">
1102         clipboardAction
1103       </a>
1104     </li>
1105
1106
1107
1108
1109
1110
1111
1112     <li class="md-nav__item">
1113       <a href="../../../../package/pip/core-object/" class="md-nav__link">
1114         coreObject
1115       </a>
1116     </li>
1117
1118
1119
1120
1121
1122
1123
1124     <li class="md-nav__item">
1125       <a href="../../../../package/pip/cronjob/" class="md-nav__link">
1126         cronjob
1127       </a>
1128     </li>
1129
1130
1131
1132
1133
1134
1135
1136     <li class="md-nav__item">
1137       <a href="../../../../package/pip/database/" class="md-nav__link">
1138         database
1139       </a>
1140     </li>
1141
1142
1143
1144
1145
1146
1147
1148     <li class="md-nav__item">
1149       <a href="../../../../package/pip/event-listener/" class="md-nav__link">
1150         eventListener
1151       </a>
1152     </li>
1153
1154
1155
1156
1157
1158
1159
1160     <li class="md-nav__item">
1161       <a href="../../../../package/pip/file/" class="md-nav__link">
1162         file
1163       </a>
1164     </li>
1165
1166
1167
1168
1169
1170
1171
1172     <li class="md-nav__item">
1173       <a href="../../../../package/pip/language/" class="md-nav__link">
1174         language
1175       </a>
1176     </li>
1177
1178
1179
1180
1181
1182
1183
1184     <li class="md-nav__item">
1185       <a href="../../../../package/pip/media-provider/" class="md-nav__link">
1186         mediaProvider
1187       </a>
1188     </li>
1189
1190
1191
1192
1193
1194
1195
1196     <li class="md-nav__item">
1197       <a href="../../../../package/pip/menu/" class="md-nav__link">
1198         menu
1199       </a>
1200     </li>
1201
1202
1203
1204
1205
1206
1207
1208     <li class="md-nav__item">
1209       <a href="../../../../package/pip/menu-item/" class="md-nav__link">
1210         menuItem
1211       </a>
1212     </li>
1213
1214
1215
1216
1217
1218
1219
1220     <li class="md-nav__item">
1221       <a href="../../../../package/pip/object-type/" class="md-nav__link">
1222         objectType
1223       </a>
1224     </li>
1225
1226
1227
1228
1229
1230
1231
1232     <li class="md-nav__item">
1233       <a href="../../../../package/pip/object-type-definition/" class="md-nav__link">
1234         objectTypeDefinition
1235       </a>
1236     </li>
1237
1238
1239
1240
1241
1242
1243
1244     <li class="md-nav__item">
1245       <a href="../../../../package/pip/option/" class="md-nav__link">
1246         option
1247       </a>
1248     </li>
1249
1250
1251
1252
1253
1254
1255
1256     <li class="md-nav__item">
1257       <a href="../../../../package/pip/page/" class="md-nav__link">
1258         page
1259       </a>
1260     </li>
1261
1262
1263
1264
1265
1266
1267
1268     <li class="md-nav__item">
1269       <a href="../../../../package/pip/pip/" class="md-nav__link">
1270         pip
1271       </a>
1272     </li>
1273
1274
1275
1276
1277
1278
1279
1280     <li class="md-nav__item">
1281       <a href="../../../../package/pip/script/" class="md-nav__link">
1282         script
1283       </a>
1284     </li>
1285
1286
1287
1288
1289
1290
1291
1292     <li class="md-nav__item">
1293       <a href="../../../../package/pip/smiley/" class="md-nav__link">
1294         smiley
1295       </a>
1296     </li>
1297
1298
1299
1300
1301
1302
1303
1304     <li class="md-nav__item">
1305       <a href="../../../../package/pip/sql/" class="md-nav__link">
1306         sql
1307       </a>
1308     </li>
1309
1310
1311
1312
1313
1314
1315
1316     <li class="md-nav__item">
1317       <a href="../../../../package/pip/style/" class="md-nav__link">
1318         style
1319       </a>
1320     </li>
1321
1322
1323
1324
1325
1326
1327
1328     <li class="md-nav__item">
1329       <a href="../../../../package/pip/template/" class="md-nav__link">
1330         template
1331       </a>
1332     </li>
1333
1334
1335
1336
1337
1338
1339
1340     <li class="md-nav__item">
1341       <a href="../../../../package/pip/template-listener/" class="md-nav__link">
1342         templateListener
1343       </a>
1344     </li>
1345
1346
1347
1348
1349
1350
1351
1352     <li class="md-nav__item">
1353       <a href="../../../../package/pip/user-group-option/" class="md-nav__link">
1354         userGroupOption
1355       </a>
1356     </li>
1357
1358
1359
1360
1361
1362
1363
1364     <li class="md-nav__item">
1365       <a href="../../../../package/pip/user-menu/" class="md-nav__link">
1366         userMenu
1367       </a>
1368     </li>
1369
1370
1371
1372
1373
1374
1375
1376     <li class="md-nav__item">
1377       <a href="../../../../package/pip/user-notification-event/" class="md-nav__link">
1378         userNotificationEvent
1379       </a>
1380     </li>
1381
1382
1383
1384
1385
1386
1387
1388     <li class="md-nav__item">
1389       <a href="../../../../package/pip/user-option/" class="md-nav__link">
1390         userOption
1391       </a>
1392     </li>
1393
1394
1395
1396
1397
1398
1399
1400     <li class="md-nav__item">
1401       <a href="../../../../package/pip/user-profile-menu/" class="md-nav__link">
1402         userProfileMenu
1403       </a>
1404     </li>
1405
1406
1407
1408         </ul>
1409       </nav>
1410     </li>
1411
1412
1413
1414
1415
1416
1417
1418     <li class="md-nav__item">
1419       <a href="../../../../package/database-php-api/" class="md-nav__link">
1420         Database PHP API
1421       </a>
1422     </li>
1423
1424
1425
1426         </ul>
1427       </nav>
1428     </li>
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440     <li class="md-nav__item md-nav__item--nested">
1441
1442
1443         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" >
1444
1445       <label class="md-nav__link" for="__nav_6">
1446         Migration
1447         <span class="md-nav__icon md-icon"></span>
1448       </label>
1449       <nav class="md-nav" aria-label="Migration" data-md-level="1">
1450         <label class="md-nav__title" for="__nav_6">
1451           <span class="md-nav__icon md-icon"></span>
1452           Migration
1453         </label>
1454         <ul class="md-nav__list" data-md-scrollfix>
1455
1456
1457
1458
1459
1460
1461     <li class="md-nav__item md-nav__item--nested">
1462
1463
1464         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_1" type="checkbox" id="__nav_6_1" >
1465
1466       <label class="md-nav__link" for="__nav_6_1">
1467         Migrating from WSC 5.3
1468         <span class="md-nav__icon md-icon"></span>
1469       </label>
1470       <nav class="md-nav" aria-label="Migrating from WSC 5.3" data-md-level="2">
1471         <label class="md-nav__title" for="__nav_6_1">
1472           <span class="md-nav__icon md-icon"></span>
1473           Migrating from WSC 5.3
1474         </label>
1475         <ul class="md-nav__list" data-md-scrollfix>
1476
1477
1478
1479
1480
1481     <li class="md-nav__item">
1482       <a href="../../../../migration/wsc53/php/" class="md-nav__link">
1483         PHP API
1484       </a>
1485     </li>
1486
1487
1488
1489
1490
1491
1492
1493     <li class="md-nav__item">
1494       <a href="../../../../migration/wsc53/session/" class="md-nav__link">
1495         Session Handling and Authentication
1496       </a>
1497     </li>
1498
1499
1500
1501
1502
1503
1504
1505     <li class="md-nav__item">
1506       <a href="../../../../migration/wsc53/javascript/" class="md-nav__link">
1507         TypeScript and JavaScript
1508       </a>
1509     </li>
1510
1511
1512
1513
1514
1515
1516
1517     <li class="md-nav__item">
1518       <a href="../../../../migration/wsc53/templates/" class="md-nav__link">
1519         Templates
1520       </a>
1521     </li>
1522
1523
1524
1525
1526
1527
1528
1529     <li class="md-nav__item">
1530       <a href="../../../../migration/wsc53/libraries/" class="md-nav__link">
1531         Third Party Libraries
1532       </a>
1533     </li>
1534
1535
1536
1537         </ul>
1538       </nav>
1539     </li>
1540
1541
1542
1543
1544
1545
1546
1547
1548     <li class="md-nav__item md-nav__item--nested">
1549
1550
1551         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_2" type="checkbox" id="__nav_6_2" >
1552
1553       <label class="md-nav__link" for="__nav_6_2">
1554         Migrating from WSC 5.2
1555         <span class="md-nav__icon md-icon"></span>
1556       </label>
1557       <nav class="md-nav" aria-label="Migrating from WSC 5.2" data-md-level="2">
1558         <label class="md-nav__title" for="__nav_6_2">
1559           <span class="md-nav__icon md-icon"></span>
1560           Migrating from WSC 5.2
1561         </label>
1562         <ul class="md-nav__list" data-md-scrollfix>
1563
1564
1565
1566
1567
1568     <li class="md-nav__item">
1569       <a href="../../../../migration/wsc52/php/" class="md-nav__link">
1570         PHP API
1571       </a>
1572     </li>
1573
1574
1575
1576
1577
1578
1579
1580     <li class="md-nav__item">
1581       <a href="../../../../migration/wsc52/templates/" class="md-nav__link">
1582         Templates and Languages
1583       </a>
1584     </li>
1585
1586
1587
1588
1589
1590
1591
1592     <li class="md-nav__item">
1593       <a href="../../../../migration/wsc52/libraries/" class="md-nav__link">
1594         Third Party Libraries
1595       </a>
1596     </li>
1597
1598
1599
1600         </ul>
1601       </nav>
1602     </li>
1603
1604
1605
1606
1607
1608
1609
1610
1611     <li class="md-nav__item md-nav__item--nested">
1612
1613
1614         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_3" type="checkbox" id="__nav_6_3" >
1615
1616       <label class="md-nav__link" for="__nav_6_3">
1617         Migrating from WSC 3.1
1618         <span class="md-nav__icon md-icon"></span>
1619       </label>
1620       <nav class="md-nav" aria-label="Migrating from WSC 3.1" data-md-level="2">
1621         <label class="md-nav__title" for="__nav_6_3">
1622           <span class="md-nav__icon md-icon"></span>
1623           Migrating from WSC 3.1
1624         </label>
1625         <ul class="md-nav__list" data-md-scrollfix>
1626
1627
1628
1629
1630
1631     <li class="md-nav__item">
1632       <a href="../../../../migration/wsc31/php/" class="md-nav__link">
1633         PHP API
1634       </a>
1635     </li>
1636
1637
1638
1639         </ul>
1640       </nav>
1641     </li>
1642
1643
1644
1645
1646
1647
1648
1649
1650     <li class="md-nav__item md-nav__item--nested">
1651
1652
1653         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_4" type="checkbox" id="__nav_6_4" >
1654
1655       <label class="md-nav__link" for="__nav_6_4">
1656         Migrating from WSC 3.0
1657         <span class="md-nav__icon md-icon"></span>
1658       </label>
1659       <nav class="md-nav" aria-label="Migrating from WSC 3.0" data-md-level="2">
1660         <label class="md-nav__title" for="__nav_6_4">
1661           <span class="md-nav__icon md-icon"></span>
1662           Migrating from WSC 3.0
1663         </label>
1664         <ul class="md-nav__list" data-md-scrollfix>
1665
1666
1667
1668
1669
1670     <li class="md-nav__item">
1671       <a href="../../../../migration/wsc30/php/" class="md-nav__link">
1672         PHP API
1673       </a>
1674     </li>
1675
1676
1677
1678
1679
1680
1681
1682     <li class="md-nav__item">
1683       <a href="../../../../migration/wsc30/javascript/" class="md-nav__link">
1684         JavaScript API
1685       </a>
1686     </li>
1687
1688
1689
1690
1691
1692
1693
1694     <li class="md-nav__item">
1695       <a href="../../../../migration/wsc30/templates/" class="md-nav__link">
1696         Templates
1697       </a>
1698     </li>
1699
1700
1701
1702
1703
1704
1705
1706     <li class="md-nav__item">
1707       <a href="../../../../migration/wsc30/css/" class="md-nav__link">
1708         CSS
1709       </a>
1710     </li>
1711
1712
1713
1714
1715
1716
1717
1718     <li class="md-nav__item">
1719       <a href="../../../../migration/wsc30/package/" class="md-nav__link">
1720         Package Components
1721       </a>
1722     </li>
1723
1724
1725
1726         </ul>
1727       </nav>
1728     </li>
1729
1730
1731
1732
1733
1734
1735
1736
1737     <li class="md-nav__item md-nav__item--nested">
1738
1739
1740         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_5" type="checkbox" id="__nav_6_5" >
1741
1742       <label class="md-nav__link" for="__nav_6_5">
1743         Migrating from WCF 2.1
1744         <span class="md-nav__icon md-icon"></span>
1745       </label>
1746       <nav class="md-nav" aria-label="Migrating from WCF 2.1" data-md-level="2">
1747         <label class="md-nav__title" for="__nav_6_5">
1748           <span class="md-nav__icon md-icon"></span>
1749           Migrating from WCF 2.1
1750         </label>
1751         <ul class="md-nav__list" data-md-scrollfix>
1752
1753
1754
1755
1756
1757     <li class="md-nav__item">
1758       <a href="../../../../migration/wcf21/php/" class="md-nav__link">
1759         PHP API
1760       </a>
1761     </li>
1762
1763
1764
1765
1766
1767
1768
1769     <li class="md-nav__item">
1770       <a href="../../../../migration/wcf21/templates/" class="md-nav__link">
1771         Templates
1772       </a>
1773     </li>
1774
1775
1776
1777
1778
1779
1780
1781     <li class="md-nav__item">
1782       <a href="../../../../migration/wcf21/css/" class="md-nav__link">
1783         CSS
1784       </a>
1785     </li>
1786
1787
1788
1789
1790
1791
1792
1793     <li class="md-nav__item">
1794       <a href="../../../../migration/wcf21/package/" class="md-nav__link">
1795         Package Components
1796       </a>
1797     </li>
1798
1799
1800
1801         </ul>
1802       </nav>
1803     </li>
1804
1805
1806
1807         </ul>
1808       </nav>
1809     </li>
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821     <li class="md-nav__item md-nav__item--nested">
1822
1823
1824         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" >
1825
1826       <label class="md-nav__link" for="__nav_7">
1827         Tutorials
1828         <span class="md-nav__icon md-icon"></span>
1829       </label>
1830       <nav class="md-nav" aria-label="Tutorials" data-md-level="1">
1831         <label class="md-nav__title" for="__nav_7">
1832           <span class="md-nav__icon md-icon"></span>
1833           Tutorials
1834         </label>
1835         <ul class="md-nav__list" data-md-scrollfix>
1836
1837
1838
1839
1840
1841
1842     <li class="md-nav__item md-nav__item--nested">
1843
1844
1845         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_1" type="checkbox" id="__nav_7_1" >
1846
1847       <label class="md-nav__link" for="__nav_7_1">
1848         Tutorial Series
1849         <span class="md-nav__icon md-icon"></span>
1850       </label>
1851       <nav class="md-nav" aria-label="Tutorial Series" data-md-level="2">
1852         <label class="md-nav__title" for="__nav_7_1">
1853           <span class="md-nav__icon md-icon"></span>
1854           Tutorial Series
1855         </label>
1856         <ul class="md-nav__list" data-md-scrollfix>
1857
1858
1859
1860
1861
1862     <li class="md-nav__item">
1863       <a href="../../../../tutorial/series/overview/" class="md-nav__link">
1864         Overview
1865       </a>
1866     </li>
1867
1868
1869
1870
1871
1872
1873
1874     <li class="md-nav__item">
1875       <a href="../../../../tutorial/series/part_1/" class="md-nav__link">
1876         Part 1
1877       </a>
1878     </li>
1879
1880
1881
1882
1883
1884
1885
1886     <li class="md-nav__item">
1887       <a href="../../../../tutorial/series/part_2/" class="md-nav__link">
1888         Part 2
1889       </a>
1890     </li>
1891
1892
1893
1894
1895
1896
1897
1898     <li class="md-nav__item">
1899       <a href="../../../../tutorial/series/part_3/" class="md-nav__link">
1900         Part 3
1901       </a>
1902     </li>
1903
1904
1905
1906         </ul>
1907       </nav>
1908     </li>
1909
1910
1911
1912         </ul>
1913       </nav>
1914     </li>
1915
1916
1917
1918   </ul>
1919 </nav>
1920                   </div>
1921                 </div>
1922               </div>
1923
1924
1925
1926               <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
1927                 <div class="md-sidebar__scrollwrap">
1928                   <div class="md-sidebar__inner">
1929
1930 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1931
1932
1933
1934
1935
1936     <label class="md-nav__title" for="__toc">
1937       <span class="md-nav__icon md-icon"></span>
1938       Table of contents
1939     </label>
1940     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1941
1942         <li class="md-nav__item">
1943   <a href="#advantages-of-form-builder" class="md-nav__link">
1944     Advantages of Form Builder
1945   </a>
1946
1947 </li>
1948
1949         <li class="md-nav__item">
1950   <a href="#form-builder-components" class="md-nav__link">
1951     Form Builder Components
1952   </a>
1953
1954 </li>
1955
1956         <li class="md-nav__item">
1957   <a href="#abstractformbuilderform" class="md-nav__link">
1958     AbstractFormBuilderForm
1959   </a>
1960
1961 </li>
1962
1963         <li class="md-nav__item">
1964   <a href="#dialogformdocument" class="md-nav__link">
1965     DialogFormDocument
1966   </a>
1967
1968 </li>
1969
1970     </ul>
1971
1972 </nav>
1973                   </div>
1974                 </div>
1975               </div>
1976
1977
1978           <div class="md-content" data-md-component="content">
1979             <article class="md-content__inner md-typeset">
1980
1981
1982                   <a href="https://github.com/WoltLab/docs.woltlab.com/edit/5.4/docs/php/api/form_builder/overview.md" title="Edit this page" class="md-content__button md-icon">
1983                     <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>
1984                   </a>
1985
1986
1987                 <h1 id="form-builder">Form Builder<a class="headerlink" href="#form-builder" title="Permanent link">#</a></h1>
1988 <div class="admonition info">
1989 <p class="admonition-title">Form builder is only available since WoltLab Suite Core 5.2.</p>
1990 </div>
1991 <div class="admonition info">
1992 <p class="admonition-title">The <a href="../../../../migration/wsc31/form-builder/">migration guide for WoltLab Suite Core 5.2</a> provides some examples of how to migrate existing forms to form builder that can also help in understanding form builder if the old way of creating forms is familiar.</p>
1993 </div>
1994 <h2 id="advantages-of-form-builder">Advantages of Form Builder<a class="headerlink" href="#advantages-of-form-builder" title="Permanent link">#</a></h2>
1995 <p>WoltLab Suite 5.2 introduces a new powerful way of creating forms: form builder.
1996 Before taking a closer look at form builder, let us recap how forms are created in previous versions:
1997 In general, for each form field, there is a corresponding property of the form's PHP class whose value has to be read from the request data, validated, and passed to the database object action to store the value in a database table.
1998 When editing an object, the property's value has to be set using the value of the corresponding property of the edited object.
1999 In the form's template, you have to write the <code>&lt;form&gt;</code> element with all of its children: the <code>&lt;section&gt;</code> elements, the <code>&lt;dl&gt;</code> elements, and, of course, the form fields themselves.
2000 In summary, this way of creating forms creates much duplicate or at least very similar code and makes it very time consuming if the structure of forms in general or a specific type of form field has to be changed.</p>
2001 <p>Form builder, in contrast, relies on PHP objects representing each component of the form, from the form itself down to each form field.
2002 This approach makes creating forms as easy as creating some PHP objects, populating them with all the relevant data, and one line of code in the template to print the form.</p>
2003 <h2 id="form-builder-components">Form Builder Components<a class="headerlink" href="#form-builder-components" title="Permanent link">#</a></h2>
2004 <p>Form builder consists of several components that are presented on the following pages:</p>
2005 <ol>
2006 <li><a href="../structure/">Structure of form builder</a></li>
2007 <li><a href="../validation_data/">Form validation and form data</a></li>
2008 <li><a href="../dependencies/">Form node dependencies</a></li>
2009 </ol>
2010 <div class="admonition warning">
2011 <p class="admonition-title">In general, form builder provides default implementation of interfaces by providing either abstract classes or traits. It is expected that the interfaces are always implemented using these abstract classes and traits! This way, if new methods are added to the interfaces, default implementations can be provided by the abstract classes and traits without causing backwards compatibility problems.</p>
2012 </div>
2013 <h2 id="abstractformbuilderform"><code>AbstractFormBuilderForm</code><a class="headerlink" href="#abstractformbuilderform" title="Permanent link">#</a></h2>
2014 <p>To make using form builder easier, <code>AbstractFormBuilderForm</code> extends <code>AbstractForm</code> and provides most of the code needed to set up a form (of course without specific fields, those have to be added by the concrete form class), like reading and validating form values and using a database object action to use the form data to create or update a database object.</p>
2015 <p>In addition to the existing methods inherited by <code>AbstractForm</code>, <code>AbstractFormBuilderForm</code> provides the following methods:</p>
2016 <ul>
2017 <li>
2018 <p><code>buildForm()</code> builds the form in the following steps:</p>
2019 </li>
2020 <li>
2021 <p>Call <code>AbtractFormBuilderForm::createForm()</code> to create the <code>IFormDocument</code> object and add the form fields.</p>
2022 </li>
2023 <li>Call <code>IFormDocument::build()</code> to build the form.</li>
2024 <li>Call <code>AbtractFormBuilderForm::finalizeForm()</code> to finalize the form like adding dependencies.</li>
2025 </ul>
2026 <p>Additionally, between steps 1 and 2 and after step 3, the method provides two events, <code>createForm</code> and <code>buildForm</code> to allow plugins to register event listeners to execute additional code at the right point in time.
2027 - <code>createForm()</code> creates the <code>FormDocument</code> object and sets the form mode.
2028   Classes extending <code>AbstractFormBuilderForm</code> have to override this method (and call <code>parent::createForm()</code> as the first line in the overridden method) to add concrete form containers and form fields to the bare form document.
2029 - <code>finalizeForm()</code> is called after the form has been built and the complete form hierarchy has been established.
2030   This method should be overridden to add dependencies, for example.
2031 - <code>setFormAction()</code> is called at the end of <code>readData()</code> and sets the form document’s action based on the controller class name and whether an object is currently edited.
2032 - If an object is edited, at the beginning of <code>readData()</code>, <code>setFormObjectData()</code> is called which calls <code>IFormDocument::loadValuesFromObject()</code>.
2033   If values need to be loaded from additional sources, this method should be used for that.</p>
2034 <p><code>AbstractFormBuilderForm</code> also provides the following (public) properties:</p>
2035 <ul>
2036 <li><code>$form</code> contains the <code>IFormDocument</code> object created in <code>createForm()</code>.</li>
2037 <li><code>$formAction</code> is either <code>create</code> (default) or <code>edit</code> and handles which method of the database object is called by default (<code>create</code> is called for <code>$formAction = 'create'</code> and <code>update</code> is called for <code>$formAction = 'edit'</code>) and is used to set the value of the <code>action</code> template variable.</li>
2038 <li><code>$formObject</code> contains the <code>IStorableObject</code> if the form is used to edit an existing object.
2039   For forms used to create objects, <code>$formObject</code> is always <code>null</code>.
2040   Edit forms have to manually identify the edited object based on the request data and set the value of <code>$formObject</code>. </li>
2041 <li><code>$objectActionName</code> can be used to set an alternative action to be executed by the database object action that deviates from the default action determined by the value of <code>$formAction</code>.</li>
2042 <li><code>$objectActionClass</code> is the name of the database object action class that is used to create or update the database object.</li>
2043 </ul>
2044 <h2 id="dialogformdocument"><code>DialogFormDocument</code><a class="headerlink" href="#dialogformdocument" title="Permanent link">#</a></h2>
2045 <p>Form builder forms can also be used in dialogs.
2046 For such forms, <code>DialogFormDocument</code> should be used which provides the additional methods <code>cancelable($cancelable = true)</code> and <code>isCancelable()</code> to set and check if the dialog can be canceled.
2047 If a dialog form can be canceled, a cancel button is added.</p>
2048 <p>If the dialog form is fetched via an AJAX request, <code>IFormDocument::ajax()</code> has to be called.
2049 AJAX forms are registered with <code>WoltLabSuite/Core/Form/Builder/Manager</code> which also supports getting all of the data of a form via the <code>getData(formId)</code> function.
2050 The <code>getData()</code> function relies on all form fields creating and registering a <code>WoltLabSuite/Core/Form/Builder/Field/Field</code> object that provides the data of a specific field.</p>
2051 <p>To make it as easy as possible to work with AJAX forms in dialogs, <code>WoltLabSuite/Core/Form/Builder/Dialog</code> (abbreviated as <code>FormBuilderDialog</code> from now on) should generally be used instead of <code>WoltLabSuite/Core/Form/Builder/Manager</code> directly.
2052 The constructor of <code>FormBuilderDialog</code> expects the following parameters:</p>
2053 <ul>
2054 <li><code>dialogId</code>: id of the dialog element</li>
2055 <li><code>className</code>: PHP class used to get the form dialog (and save the data if <code>options.submitActionName</code> is set)</li>
2056 <li><code>actionName</code>: name of the action/method of <code>className</code> that returns the dialog; the method is expected to return an array with <code>formId</code> containg the id of the returned form and <code>dialog</code> containing the rendered form dialog</li>
2057 <li><code>options</code>: additional options:</li>
2058 <li><code>actionParameters</code> (default: empty): additional parameters sent during AJAX requests</li>
2059 <li><code>destroyOnClose</code> (default: <code>false</code>): if <code>true</code>, whenever the dialog is closed, the form is destroyed so that a new form is fetched if the dialog is opened again</li>
2060 <li><code>dialog</code>: additional dialog options used as <code>options</code> during dialog setup</li>
2061 <li><code>onSubmit</code>: callback when the form is submitted (takes precedence over <code>submitActionName</code>)</li>
2062 <li><code>submitActionName</code> (default: not set): name of the action/method of <code>className</code> called when the form is submitted</li>
2063 </ul>
2064 <p>The three public functions of <code>FormBuilderDialog</code> are:</p>
2065 <ul>
2066 <li><code>destroy()</code> destroys the dialog, the form, and all of the form fields.</li>
2067 <li><code>getData()</code> returns a Promise that returns the form data.</li>
2068 <li><code>open()</code> opens the dialog.</li>
2069 </ul>
2070 <p>Example:</p>
2071 <div class="highlight"><pre><span></span><code><span class="nx">require</span><span class="p">([</span><span class="s1">&#39;WoltLabSuite/Core/Form/Builder/Dialog&#39;</span><span class="p">],</span> <span class="kd">function</span><span class="p">(</span><span class="nx">FormBuilderDialog</span><span class="p">)</span> <span class="p">{</span>
2072     <span class="kd">var</span> <span class="nx">dialog</span> <span class="o">=</span> <span class="k">new</span> <span class="nx">FormBuilderDialog</span><span class="p">(</span>
2073         <span class="s1">&#39;testDialog&#39;</span><span class="p">,</span>
2074         <span class="s1">&#39;wcf\\data\\test\\TestAction&#39;</span><span class="p">,</span>
2075         <span class="s1">&#39;getDialog&#39;</span><span class="p">,</span>
2076         <span class="p">{</span>
2077             <span class="nx">destroyOnClose</span><span class="o">:</span> <span class="kc">true</span><span class="p">,</span>
2078             <span class="nx">dialog</span><span class="o">:</span> <span class="p">{</span>
2079                 <span class="nx">title</span><span class="o">:</span> <span class="s1">&#39;Test Dialog&#39;</span>
2080             <span class="p">},</span>
2081             <span class="nx">submitActionName</span><span class="o">:</span> <span class="s1">&#39;saveDialog&#39;</span>
2082         <span class="p">}</span>
2083     <span class="p">);</span>
2084
2085     <span class="nx">elById</span><span class="p">(</span><span class="s1">&#39;testDialogButton&#39;</span><span class="p">).</span><span class="nx">addEventListener</span><span class="p">(</span><span class="s1">&#39;click&#39;</span><span class="p">,</span> <span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
2086         <span class="nx">dialog</span><span class="p">.</span><span class="nx">open</span><span class="p">();</span>
2087     <span class="p">});</span>
2088 <span class="p">});</span>
2089 </code></pre></div>
2090
2091
2092
2093
2094 <hr>
2095 <div class="md-source-date">
2096   <small>
2097
2098       Last update: 2021-01-15
2099
2100   </small>
2101 </div>
2102
2103
2104
2105
2106
2107
2108
2109
2110             </article>
2111           </div>
2112         </div>
2113
2114       </main>
2115
2116
2117 <footer class="md-footer">
2118
2119     <nav class="md-footer__inner md-grid" aria-label="Footer">
2120
2121         <a href="../../events/" class="md-footer__link md-footer__link--prev" rel="prev">
2122           <div class="md-footer__button md-icon">
2123             <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>
2124           </div>
2125           <div class="md-footer__title">
2126             <div class="md-ellipsis">
2127               <span class="md-footer__direction">
2128                 Previous
2129               </span>
2130               Events
2131             </div>
2132           </div>
2133         </a>
2134
2135
2136         <a href="../structure/" class="md-footer__link md-footer__link--next" rel="next">
2137           <div class="md-footer__title">
2138             <div class="md-ellipsis">
2139               <span class="md-footer__direction">
2140                 Next
2141               </span>
2142               Structure
2143             </div>
2144           </div>
2145           <div class="md-footer__button md-icon">
2146             <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>
2147           </div>
2148         </a>
2149
2150     </nav>
2151
2152   <div class="md-footer-meta md-typeset">
2153     <div class="md-footer-meta__inner md-grid">
2154       <div class="md-footer-copyright">
2155
2156           <div class="md-footer-copyright__highlight">
2157             Copyright © 2020 WoltLab GmbH
2158           </div>
2159
2160         Made with
2161         <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
2162           Material for MkDocs
2163         </a>
2164
2165       </div>
2166       <div class="md-footer-copyright">
2167         <a href="https://www.woltlab.com/legal-notice/">Legal Notice</a>
2168         <a href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
2169 </div>
2170     </div>
2171   </div>
2172 </footer>
2173
2174     </div>
2175     <div class="md-dialog" data-md-component="dialog">
2176       <div class="md-dialog__inner md-typeset"></div>
2177     </div>
2178     <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.fe42c31b.min.js", "version": {"provider": "mike"}}</script>
2179
2180
2181       <script src="../../../../assets/javascripts/bundle.d892486b.min.js"></script>
2182
2183
2184   </body>
2185 </html>