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