5.4/javascript/general-usage/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="canonical" href="https://docs.woltlab.com/5.4/javascript/general-usage/">
  13
  14       <link rel="icon" href="../../assets/default.favicon.ico">
  15       <meta name="generator" content="mkdocs-1.1.2, mkdocs-material-7.1.3">
  16
  17
  18
  19         <title>General Usage - WoltLab Suite Documentation</title>
  20
  21
  22
  23       <link rel="stylesheet" href="../../assets/stylesheets/main.e35208c4.min.css">
  24
  25
  26         <link rel="stylesheet" href="../../assets/stylesheets/palette.ef6f36e2.min.css">
  27
  28
  29
  30           <meta name="theme-color" content="#009485">
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40       <link rel="stylesheet" href="../../stylesheets/extra.css">
  41
  42
  43
  44
  45
  46   </head>
  47
  48
  49
  50
  51
  52
  53
  54     <body dir="ltr" data-md-color-scheme="" data-md-color-primary="teal" data-md-color-accent="">
  55
  56
  57     <script>function __prefix(e){return new URL("../..",location).pathname+"."+e}function __get(e,t=localStorage){return JSON.parse(t.getItem(__prefix(e)))}</script>
  58
  59     <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
  60     <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
  61     <label class="md-overlay" for="__drawer"></label>
  62     <div data-md-component="skip">
  63
  64
  65         <a href="#general-javascript-usage" class="md-skip">
  66           Skip to content
  67         </a>
  68
  69     </div>
  70     <div data-md-component="announce">
  71
  72         <aside class="md-announce">
  73           <div class="md-announce__inner md-grid md-typeset">
  74
  75     <a href="https://www.woltlab.com">Back to <strong>woltlab.com</strong></a>
  76
  77           </div>
  78         </aside>
  79
  80     </div>
  81
  82       <header class="md-header" data-md-component="header">
  83   <nav class="md-header__inner md-grid" aria-label="Header">
  84     <a href="../.." title="WoltLab Suite Documentation" class="md-header__button md-logo" aria-label="WoltLab Suite Documentation" data-md-component="logo">
  85
  86   <img src="../../assets/logo.png" alt="logo">
  87
  88     </a>
  89     <label class="md-header__button md-icon" for="__drawer">
  90       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
  91     </label>
  92     <div class="md-header__title" data-md-component="header-title">
  93       <div class="md-header__ellipsis">
  94         <div class="md-header__topic">
  95           <span class="md-ellipsis">
  96             WoltLab Suite Documentation
  97           </span>
  98         </div>
  99         <div class="md-header__topic" data-md-component="header-topic">
 100           <span class="md-ellipsis">
 101
 102               General Usage
 103
 104           </span>
 105         </div>
 106       </div>
 107     </div>
 108
 109
 110
 111       <label class="md-header__button md-icon" for="__search">
 112         <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>
 113       </label>
 114
 115 <div class="md-search" data-md-component="search" role="dialog">
 116   <label class="md-search__overlay" for="__search"></label>
 117   <div class="md-search__inner" role="search">
 118     <form class="md-search__form" name="search">
 119       <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>
 120       <label class="md-search__icon md-icon" for="__search">
 121         <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>
 122         <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>
 123       </label>
 124       <button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1">
 125         <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>
 126       </button>
 127     </form>
 128     <div class="md-search__output">
 129       <div class="md-search__scrollwrap" data-md-scrollfix>
 130         <div class="md-search-result" data-md-component="search-result">
 131           <div class="md-search-result__meta">
 132             Initializing search
 133           </div>
 134           <ol class="md-search-result__list"></ol>
 135         </div>
 136       </div>
 137     </div>
 138   </div>
 139 </div>
 140
 141
 142       <div class="md-header__source">
 143
 144 <a href="https://github.com/WoltLab/docs.woltlab.com/" title="Go to repository" class="md-source" data-md-component="source">
 145   <div class="md-source__icon md-icon">
 146
 147     <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>
 148   </div>
 149   <div class="md-source__repository">
 150     GitHub
 151   </div>
 152 </a>
 153       </div>
 154
 155   </nav>
 156 </header>
 157
 158     <div class="md-container" data-md-component="container">
 159
 160
 161
 162
 163       <main class="md-main" data-md-component="main">
 164         <div class="md-main__inner md-grid">
 165
 166
 167
 168               <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
 169                 <div class="md-sidebar__scrollwrap">
 170                   <div class="md-sidebar__inner">
 171
 172
 173
 174 <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
 175   <label class="md-nav__title" for="__drawer">
 176     <a href="../.." title="WoltLab Suite Documentation" class="md-nav__button md-logo" aria-label="WoltLab Suite Documentation" data-md-component="logo">
 177
 178   <img src="../../assets/logo.png" alt="logo">
 179
 180     </a>
 181     WoltLab Suite Documentation
 182   </label>
 183
 184     <div class="md-nav__source">
 185
 186 <a href="https://github.com/WoltLab/docs.woltlab.com/" title="Go to repository" class="md-source" data-md-component="source">
 187   <div class="md-source__icon md-icon">
 188
 189     <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>
 190   </div>
 191   <div class="md-source__repository">
 192     GitHub
 193   </div>
 194 </a>
 195     </div>
 196
 197   <ul class="md-nav__list" data-md-scrollfix>
 198
 199
 200
 201
 202
 203
 204
 205
 206     <li class="md-nav__item">
 207       <a href="../../getting-started/" class="md-nav__link">
 208         Getting Started
 209       </a>
 210     </li>
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222     <li class="md-nav__item md-nav__item--nested">
 223
 224
 225         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" >
 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="../../php/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="../../php/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="../../php/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="../../php/exceptions/" class="md-nav__link">
 280         Exceptions
 281       </a>
 282     </li>
 283
 284
 285
 286
 287
 288
 289
 290
 291     <li class="md-nav__item md-nav__item--nested">
 292
 293
 294         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5" type="checkbox" id="__nav_2_5" >
 295
 296       <label class="md-nav__link" for="__nav_2_5">
 297         API
 298         <span class="md-nav__icon md-icon"></span>
 299       </label>
 300       <nav class="md-nav" aria-label="API" data-md-level="2">
 301         <label class="md-nav__title" for="__nav_2_5">
 302           <span class="md-nav__icon md-icon"></span>
 303           API
 304         </label>
 305         <ul class="md-nav__list" data-md-scrollfix>
 306
 307
 308
 309
 310
 311
 312     <li class="md-nav__item md-nav__item--nested">
 313
 314
 315         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5_1" type="checkbox" id="__nav_2_5_1" >
 316
 317       <label class="md-nav__link" for="__nav_2_5_1">
 318         Caches
 319         <span class="md-nav__icon md-icon"></span>
 320       </label>
 321       <nav class="md-nav" aria-label="Caches" data-md-level="3">
 322         <label class="md-nav__title" for="__nav_2_5_1">
 323           <span class="md-nav__icon md-icon"></span>
 324           Caches
 325         </label>
 326         <ul class="md-nav__list" data-md-scrollfix>
 327
 328
 329
 330
 331
 332     <li class="md-nav__item">
 333       <a href="../../php/api/caches/" class="md-nav__link">
 334         Overview
 335       </a>
 336     </li>
 337
 338
 339
 340
 341
 342
 343
 344     <li class="md-nav__item">
 345       <a href="../../php/api/caches_persistent-caches/" class="md-nav__link">
 346         Persistent Caches
 347       </a>
 348     </li>
 349
 350
 351
 352
 353
 354
 355
 356     <li class="md-nav__item">
 357       <a href="../../php/api/caches_runtime-caches/" class="md-nav__link">
 358         Runtime Caches
 359       </a>
 360     </li>
 361
 362
 363
 364         </ul>
 365       </nav>
 366     </li>
 367
 368
 369
 370
 371
 372
 373
 374     <li class="md-nav__item">
 375       <a href="../../php/api/comments/" class="md-nav__link">
 376         Comments
 377       </a>
 378     </li>
 379
 380
 381
 382
 383
 384
 385
 386     <li class="md-nav__item">
 387       <a href="../../php/api/cronjobs/" class="md-nav__link">
 388         Cronjobs
 389       </a>
 390     </li>
 391
 392
 393
 394
 395
 396
 397
 398     <li class="md-nav__item">
 399       <a href="../../php/api/events/" class="md-nav__link">
 400         Events
 401       </a>
 402     </li>
 403
 404
 405
 406
 407
 408
 409
 410
 411     <li class="md-nav__item md-nav__item--nested">
 412
 413
 414         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5_5" type="checkbox" id="__nav_2_5_5" >
 415
 416       <label class="md-nav__link" for="__nav_2_5_5">
 417         Form Builder
 418         <span class="md-nav__icon md-icon"></span>
 419       </label>
 420       <nav class="md-nav" aria-label="Form Builder" data-md-level="3">
 421         <label class="md-nav__title" for="__nav_2_5_5">
 422           <span class="md-nav__icon md-icon"></span>
 423           Form Builder
 424         </label>
 425         <ul class="md-nav__list" data-md-scrollfix>
 426
 427
 428
 429
 430
 431     <li class="md-nav__item">
 432       <a href="../../php/api/form_builder/overview/" class="md-nav__link">
 433         Overview
 434       </a>
 435     </li>
 436
 437
 438
 439
 440
 441
 442
 443     <li class="md-nav__item">
 444       <a href="../../php/api/form_builder/structure/" class="md-nav__link">
 445         Structure
 446       </a>
 447     </li>
 448
 449
 450
 451
 452
 453
 454
 455     <li class="md-nav__item">
 456       <a href="../../php/api/form_builder/form_fields/" class="md-nav__link">
 457         Fields
 458       </a>
 459     </li>
 460
 461
 462
 463
 464
 465
 466
 467     <li class="md-nav__item">
 468       <a href="../../php/api/form_builder/validation_data/" class="md-nav__link">
 469         Validation and Data
 470       </a>
 471     </li>
 472
 473
 474
 475
 476
 477
 478
 479     <li class="md-nav__item">
 480       <a href="../../php/api/form_builder/dependencies/" class="md-nav__link">
 481         Dependencies
 482       </a>
 483     </li>
 484
 485
 486
 487         </ul>
 488       </nav>
 489     </li>
 490
 491
 492
 493
 494
 495
 496
 497     <li class="md-nav__item">
 498       <a href="../../php/api/package_installation_plugins/" class="md-nav__link">
 499         Package Installation Plugins
 500       </a>
 501     </li>
 502
 503
 504
 505
 506
 507
 508
 509     <li class="md-nav__item">
 510       <a href="../../php/api/user_activity_points/" class="md-nav__link">
 511         User Activity Points
 512       </a>
 513     </li>
 514
 515
 516
 517
 518
 519
 520
 521     <li class="md-nav__item">
 522       <a href="../../php/api/user_notifications/" class="md-nav__link">
 523         User Notifications
 524       </a>
 525     </li>
 526
 527
 528
 529
 530
 531
 532
 533     <li class="md-nav__item">
 534       <a href="../../php/api/sitemaps/" class="md-nav__link">
 535         Sitemaps
 536       </a>
 537     </li>
 538
 539
 540
 541         </ul>
 542       </nav>
 543     </li>
 544
 545
 546
 547
 548
 549
 550
 551     <li class="md-nav__item">
 552       <a href="../../php/code-style/" class="md-nav__link">
 553         Code Style
 554       </a>
 555     </li>
 556
 557
 558
 559
 560
 561
 562
 563     <li class="md-nav__item">
 564       <a href="../../php/apps/" class="md-nav__link">
 565         Apps
 566       </a>
 567     </li>
 568
 569
 570
 571
 572
 573
 574
 575     <li class="md-nav__item">
 576       <a href="../../php/gdpr/" class="md-nav__link">
 577         GDPR
 578       </a>
 579     </li>
 580
 581
 582
 583         </ul>
 584       </nav>
 585     </li>
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597     <li class="md-nav__item md-nav__item--nested">
 598
 599
 600         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" >
 601
 602       <label class="md-nav__link" for="__nav_3">
 603         Languages, Templates & CSS
 604         <span class="md-nav__icon md-icon"></span>
 605       </label>
 606       <nav class="md-nav" aria-label="Languages, Templates & CSS" data-md-level="1">
 607         <label class="md-nav__title" for="__nav_3">
 608           <span class="md-nav__icon md-icon"></span>
 609           Languages, Templates & CSS
 610         </label>
 611         <ul class="md-nav__list" data-md-scrollfix>
 612
 613
 614
 615
 616
 617     <li class="md-nav__item">
 618       <a href="../../view/languages/" class="md-nav__link">
 619         Languages
 620       </a>
 621     </li>
 622
 623
 624
 625
 626
 627
 628
 629     <li class="md-nav__item">
 630       <a href="../../view/templates/" class="md-nav__link">
 631         Templates
 632       </a>
 633     </li>
 634
 635
 636
 637
 638
 639
 640
 641     <li class="md-nav__item">
 642       <a href="../../view/template-plugins/" class="md-nav__link">
 643         Template Plugins
 644       </a>
 645     </li>
 646
 647
 648
 649
 650
 651
 652
 653     <li class="md-nav__item">
 654       <a href="../../view/css/" class="md-nav__link">
 655         CSS
 656       </a>
 657     </li>
 658
 659
 660
 661         </ul>
 662       </nav>
 663     </li>
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677     <li class="md-nav__item md-nav__item--active md-nav__item--nested">
 678
 679
 680         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" checked>
 681
 682       <label class="md-nav__link" for="__nav_4">
 683         TypeScript and JavaScript API
 684         <span class="md-nav__icon md-icon"></span>
 685       </label>
 686       <nav class="md-nav" aria-label="TypeScript and JavaScript API" data-md-level="1">
 687         <label class="md-nav__title" for="__nav_4">
 688           <span class="md-nav__icon md-icon"></span>
 689           TypeScript and JavaScript API
 690         </label>
 691         <ul class="md-nav__list" data-md-scrollfix>
 692
 693
 694
 695
 696
 697
 698
 699     <li class="md-nav__item md-nav__item--active">
 700
 701       <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
 702
 703
 704
 705
 706
 707         <label class="md-nav__link md-nav__link--active" for="__toc">
 708           General Usage
 709           <span class="md-nav__icon md-icon"></span>
 710         </label>
 711
 712       <a href="./" class="md-nav__link md-nav__link--active">
 713         General Usage
 714       </a>
 715
 716
 717 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
 718
 719
 720
 721
 722
 723
 724     <label class="md-nav__title" for="__toc">
 725       <span class="md-nav__icon md-icon"></span>
 726       Table of contents
 727     </label>
 728     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 729
 730         <li class="md-nav__item">
 731   <a href="#the-history-of-the-legacy-api" class="md-nav__link">
 732     The History of the Legacy API
 733   </a>
 734
 735 </li>
 736
 737         <li class="md-nav__item">
 738   <a href="#embedding-javascript-inside-templates" class="md-nav__link">
 739     Embedding JavaScript inside Templates
 740   </a>
 741
 742 </li>
 743
 744         <li class="md-nav__item">
 745   <a href="#including-external-javascript-files" class="md-nav__link">
 746     Including External JavaScript Files
 747   </a>
 748
 749     <nav class="md-nav" aria-label="Including External JavaScript Files">
 750       <ul class="md-nav__list">
 751
 752           <li class="md-nav__item">
 753   <a href="#debug-variants-and-cache-buster" class="md-nav__link">
 754     Debug-Variants and Cache-Buster
 755   </a>
 756
 757 </li>
 758
 759           <li class="md-nav__item">
 760   <a href="#the-accelerated-guest-view-tiny-builds" class="md-nav__link">
 761     The Accelerated Guest View ("Tiny Builds")
 762   </a>
 763
 764 </li>
 765
 766           <li class="md-nav__item">
 767   <a href="#the-js-template-plugin" class="md-nav__link">
 768     The {js} Template Plugin
 769   </a>
 770
 771 </li>
 772
 773       </ul>
 774     </nav>
 775
 776 </li>
 777
 778     </ul>
 779
 780 </nav>
 781
 782     </li>
 783
 784
 785
 786
 787
 788
 789
 790     <li class="md-nav__item">
 791       <a href="../typescript/" class="md-nav__link">
 792         TypeScript
 793       </a>
 794     </li>
 795
 796
 797
 798
 799
 800
 801
 802
 803     <li class="md-nav__item md-nav__item--nested">
 804
 805
 806         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4_3" type="checkbox" id="__nav_4_3" >
 807
 808       <label class="md-nav__link" for="__nav_4_3">
 809         New API
 810         <span class="md-nav__icon md-icon"></span>
 811       </label>
 812       <nav class="md-nav" aria-label="New API" data-md-level="2">
 813         <label class="md-nav__title" for="__nav_4_3">
 814           <span class="md-nav__icon md-icon"></span>
 815           New API
 816         </label>
 817         <ul class="md-nav__list" data-md-scrollfix>
 818
 819
 820
 821
 822
 823     <li class="md-nav__item">
 824       <a href="../new-api_writing-a-module/" class="md-nav__link">
 825         Writing a module
 826       </a>
 827     </li>
 828
 829
 830
 831
 832
 833
 834
 835     <li class="md-nav__item">
 836       <a href="../new-api_data-structures/" class="md-nav__link">
 837         Data Structures
 838       </a>
 839     </li>
 840
 841
 842
 843
 844
 845
 846
 847     <li class="md-nav__item">
 848       <a href="../new-api_core/" class="md-nav__link">
 849         Core Functions
 850       </a>
 851     </li>
 852
 853
 854
 855
 856
 857
 858
 859     <li class="md-nav__item">
 860       <a href="../new-api_dom/" class="md-nav__link">
 861         DOM
 862       </a>
 863     </li>
 864
 865
 866
 867
 868
 869
 870
 871     <li class="md-nav__item">
 872       <a href="../new-api_events/" class="md-nav__link">
 873         Event Handling
 874       </a>
 875     </li>
 876
 877
 878
 879
 880
 881
 882
 883     <li class="md-nav__item">
 884       <a href="../new-api_ajax/" class="md-nav__link">
 885         Ajax
 886       </a>
 887     </li>
 888
 889
 890
 891
 892
 893
 894
 895     <li class="md-nav__item">
 896       <a href="../new-api_dialogs/" class="md-nav__link">
 897         Dialogs
 898       </a>
 899     </li>
 900
 901
 902
 903
 904
 905
 906
 907     <li class="md-nav__item">
 908       <a href="../new-api_browser/" class="md-nav__link">
 909         Browser and Screen Sizes
 910       </a>
 911     </li>
 912
 913
 914
 915
 916
 917
 918
 919     <li class="md-nav__item">
 920       <a href="../new-api_ui/" class="md-nav__link">
 921         User Interface
 922       </a>
 923     </li>
 924
 925
 926
 927         </ul>
 928       </nav>
 929     </li>
 930
 931
 932
 933
 934
 935
 936
 937     <li class="md-nav__item">
 938       <a href="../legacy-api/" class="md-nav__link">
 939         Legacy API
 940       </a>
 941     </li>
 942
 943
 944
 945
 946
 947
 948
 949     <li class="md-nav__item">
 950       <a href="../helper-functions/" class="md-nav__link">
 951         Helper Functions
 952       </a>
 953     </li>
 954
 955
 956
 957
 958
 959
 960
 961     <li class="md-nav__item">
 962       <a href="../code-snippets/" class="md-nav__link">
 963         Code Snippets
 964       </a>
 965     </li>
 966
 967
 968
 969         </ul>
 970       </nav>
 971     </li>
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983     <li class="md-nav__item md-nav__item--nested">
 984
 985
 986         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
 987
 988       <label class="md-nav__link" for="__nav_5">
 989         Package Components
 990         <span class="md-nav__icon md-icon"></span>
 991       </label>
 992       <nav class="md-nav" aria-label="Package Components" data-md-level="1">
 993         <label class="md-nav__title" for="__nav_5">
 994           <span class="md-nav__icon md-icon"></span>
 995           Package Components
 996         </label>
 997         <ul class="md-nav__list" data-md-scrollfix>
 998
 999
1000
1001
1002
1003     <li class="md-nav__item">
1004       <a href="../../package/package-xml/" class="md-nav__link">
1005         package.xml
1006       </a>
1007     </li>
1008
1009
1010
1011
1012
1013
1014
1015
1016     <li class="md-nav__item md-nav__item--nested">
1017
1018
1019         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5_2" type="checkbox" id="__nav_5_2" >
1020
1021       <label class="md-nav__link" for="__nav_5_2">
1022         PIPs
1023         <span class="md-nav__icon md-icon"></span>
1024       </label>
1025       <nav class="md-nav" aria-label="PIPs" data-md-level="2">
1026         <label class="md-nav__title" for="__nav_5_2">
1027           <span class="md-nav__icon md-icon"></span>
1028           PIPs
1029         </label>
1030         <ul class="md-nav__list" data-md-scrollfix>
1031
1032
1033
1034
1035
1036     <li class="md-nav__item">
1037       <a href="../../package/pip/" class="md-nav__link">
1038         Overview
1039       </a>
1040     </li>
1041
1042
1043
1044
1045
1046
1047
1048     <li class="md-nav__item">
1049       <a href="../../package/pip/acl-option/" class="md-nav__link">
1050         aclOption
1051       </a>
1052     </li>
1053
1054
1055
1056
1057
1058
1059
1060     <li class="md-nav__item">
1061       <a href="../../package/pip/acp-menu/" class="md-nav__link">
1062         acpMenu
1063       </a>
1064     </li>
1065
1066
1067
1068
1069
1070
1071
1072     <li class="md-nav__item">
1073       <a href="../../package/pip/acp-search-provider/" class="md-nav__link">
1074         acpSearchProvider
1075       </a>
1076     </li>
1077
1078
1079
1080
1081
1082
1083
1084     <li class="md-nav__item">
1085       <a href="../../package/pip/acp-template/" class="md-nav__link">
1086         acpTemplate
1087       </a>
1088     </li>
1089
1090
1091
1092
1093
1094
1095
1096     <li class="md-nav__item">
1097       <a href="../../package/pip/bbcode/" class="md-nav__link">
1098         bbcode
1099       </a>
1100     </li>
1101
1102
1103
1104
1105
1106
1107
1108     <li class="md-nav__item">
1109       <a href="../../package/pip/box/" class="md-nav__link">
1110         box
1111       </a>
1112     </li>
1113
1114
1115
1116
1117
1118
1119
1120     <li class="md-nav__item">
1121       <a href="../../package/pip/clipboard-action/" class="md-nav__link">
1122         clipboardAction
1123       </a>
1124     </li>
1125
1126
1127
1128
1129
1130
1131
1132     <li class="md-nav__item">
1133       <a href="../../package/pip/core-object/" class="md-nav__link">
1134         coreObject
1135       </a>
1136     </li>
1137
1138
1139
1140
1141
1142
1143
1144     <li class="md-nav__item">
1145       <a href="../../package/pip/cronjob/" class="md-nav__link">
1146         cronjob
1147       </a>
1148     </li>
1149
1150
1151
1152
1153
1154
1155
1156     <li class="md-nav__item">
1157       <a href="../../package/pip/database/" class="md-nav__link">
1158         database
1159       </a>
1160     </li>
1161
1162
1163
1164
1165
1166
1167
1168     <li class="md-nav__item">
1169       <a href="../../package/pip/event-listener/" class="md-nav__link">
1170         eventListener
1171       </a>
1172     </li>
1173
1174
1175
1176
1177
1178
1179
1180     <li class="md-nav__item">
1181       <a href="../../package/pip/file/" class="md-nav__link">
1182         file
1183       </a>
1184     </li>
1185
1186
1187
1188
1189
1190
1191
1192     <li class="md-nav__item">
1193       <a href="../../package/pip/language/" class="md-nav__link">
1194         language
1195       </a>
1196     </li>
1197
1198
1199
1200
1201
1202
1203
1204     <li class="md-nav__item">
1205       <a href="../../package/pip/media-provider/" class="md-nav__link">
1206         mediaProvider
1207       </a>
1208     </li>
1209
1210
1211
1212
1213
1214
1215
1216     <li class="md-nav__item">
1217       <a href="../../package/pip/menu/" class="md-nav__link">
1218         menu
1219       </a>
1220     </li>
1221
1222
1223
1224
1225
1226
1227
1228     <li class="md-nav__item">
1229       <a href="../../package/pip/menu-item/" class="md-nav__link">
1230         menuItem
1231       </a>
1232     </li>
1233
1234
1235
1236
1237
1238
1239
1240     <li class="md-nav__item">
1241       <a href="../../package/pip/object-type/" class="md-nav__link">
1242         objectType
1243       </a>
1244     </li>
1245
1246
1247
1248
1249
1250
1251
1252     <li class="md-nav__item">
1253       <a href="../../package/pip/object-type-definition/" class="md-nav__link">
1254         objectTypeDefinition
1255       </a>
1256     </li>
1257
1258
1259
1260
1261
1262
1263
1264     <li class="md-nav__item">
1265       <a href="../../package/pip/option/" class="md-nav__link">
1266         option
1267       </a>
1268     </li>
1269
1270
1271
1272
1273
1274
1275
1276     <li class="md-nav__item">
1277       <a href="../../package/pip/page/" class="md-nav__link">
1278         page
1279       </a>
1280     </li>
1281
1282
1283
1284
1285
1286
1287
1288     <li class="md-nav__item">
1289       <a href="../../package/pip/pip/" class="md-nav__link">
1290         pip
1291       </a>
1292     </li>
1293
1294
1295
1296
1297
1298
1299
1300     <li class="md-nav__item">
1301       <a href="../../package/pip/script/" class="md-nav__link">
1302         script
1303       </a>
1304     </li>
1305
1306
1307
1308
1309
1310
1311
1312     <li class="md-nav__item">
1313       <a href="../../package/pip/smiley/" class="md-nav__link">
1314         smiley
1315       </a>
1316     </li>
1317
1318
1319
1320
1321
1322
1323
1324     <li class="md-nav__item">
1325       <a href="../../package/pip/sql/" class="md-nav__link">
1326         sql
1327       </a>
1328     </li>
1329
1330
1331
1332
1333
1334
1335
1336     <li class="md-nav__item">
1337       <a href="../../package/pip/style/" class="md-nav__link">
1338         style
1339       </a>
1340     </li>
1341
1342
1343
1344
1345
1346
1347
1348     <li class="md-nav__item">
1349       <a href="../../package/pip/template/" class="md-nav__link">
1350         template
1351       </a>
1352     </li>
1353
1354
1355
1356
1357
1358
1359
1360     <li class="md-nav__item">
1361       <a href="../../package/pip/template-listener/" class="md-nav__link">
1362         templateListener
1363       </a>
1364     </li>
1365
1366
1367
1368
1369
1370
1371
1372     <li class="md-nav__item">
1373       <a href="../../package/pip/user-group-option/" class="md-nav__link">
1374         userGroupOption
1375       </a>
1376     </li>
1377
1378
1379
1380
1381
1382
1383
1384     <li class="md-nav__item">
1385       <a href="../../package/pip/user-menu/" class="md-nav__link">
1386         userMenu
1387       </a>
1388     </li>
1389
1390
1391
1392
1393
1394
1395
1396     <li class="md-nav__item">
1397       <a href="../../package/pip/user-notification-event/" class="md-nav__link">
1398         userNotificationEvent
1399       </a>
1400     </li>
1401
1402
1403
1404
1405
1406
1407
1408     <li class="md-nav__item">
1409       <a href="../../package/pip/user-option/" class="md-nav__link">
1410         userOption
1411       </a>
1412     </li>
1413
1414
1415
1416
1417
1418
1419
1420     <li class="md-nav__item">
1421       <a href="../../package/pip/user-profile-menu/" class="md-nav__link">
1422         userProfileMenu
1423       </a>
1424     </li>
1425
1426
1427
1428         </ul>
1429       </nav>
1430     </li>
1431
1432
1433
1434
1435
1436
1437
1438     <li class="md-nav__item">
1439       <a href="../../package/database-php-api/" class="md-nav__link">
1440         Database PHP API
1441       </a>
1442     </li>
1443
1444
1445
1446         </ul>
1447       </nav>
1448     </li>
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460     <li class="md-nav__item md-nav__item--nested">
1461
1462
1463         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" >
1464
1465       <label class="md-nav__link" for="__nav_6">
1466         Migration
1467         <span class="md-nav__icon md-icon"></span>
1468       </label>
1469       <nav class="md-nav" aria-label="Migration" data-md-level="1">
1470         <label class="md-nav__title" for="__nav_6">
1471           <span class="md-nav__icon md-icon"></span>
1472           Migration
1473         </label>
1474         <ul class="md-nav__list" data-md-scrollfix>
1475
1476
1477
1478
1479
1480
1481     <li class="md-nav__item md-nav__item--nested">
1482
1483
1484         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_1" type="checkbox" id="__nav_6_1" >
1485
1486       <label class="md-nav__link" for="__nav_6_1">
1487         Migrating from WSC 5.3
1488         <span class="md-nav__icon md-icon"></span>
1489       </label>
1490       <nav class="md-nav" aria-label="Migrating from WSC 5.3" data-md-level="2">
1491         <label class="md-nav__title" for="__nav_6_1">
1492           <span class="md-nav__icon md-icon"></span>
1493           Migrating from WSC 5.3
1494         </label>
1495         <ul class="md-nav__list" data-md-scrollfix>
1496
1497
1498
1499
1500
1501     <li class="md-nav__item">
1502       <a href="../../migration/wsc53/php/" class="md-nav__link">
1503         PHP API
1504       </a>
1505     </li>
1506
1507
1508
1509
1510
1511
1512
1513     <li class="md-nav__item">
1514       <a href="../../migration/wsc53/session/" class="md-nav__link">
1515         Session Handling and Authentication
1516       </a>
1517     </li>
1518
1519
1520
1521
1522
1523
1524
1525     <li class="md-nav__item">
1526       <a href="../../migration/wsc53/javascript/" class="md-nav__link">
1527         TypeScript and JavaScript
1528       </a>
1529     </li>
1530
1531
1532
1533
1534
1535
1536
1537     <li class="md-nav__item">
1538       <a href="../../migration/wsc53/templates/" class="md-nav__link">
1539         Templates
1540       </a>
1541     </li>
1542
1543
1544
1545
1546
1547
1548
1549     <li class="md-nav__item">
1550       <a href="../../migration/wsc53/libraries/" class="md-nav__link">
1551         Third Party Libraries
1552       </a>
1553     </li>
1554
1555
1556
1557         </ul>
1558       </nav>
1559     </li>
1560
1561
1562
1563
1564
1565
1566
1567
1568     <li class="md-nav__item md-nav__item--nested">
1569
1570
1571         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_2" type="checkbox" id="__nav_6_2" >
1572
1573       <label class="md-nav__link" for="__nav_6_2">
1574         Migrating from WSC 5.2
1575         <span class="md-nav__icon md-icon"></span>
1576       </label>
1577       <nav class="md-nav" aria-label="Migrating from WSC 5.2" data-md-level="2">
1578         <label class="md-nav__title" for="__nav_6_2">
1579           <span class="md-nav__icon md-icon"></span>
1580           Migrating from WSC 5.2
1581         </label>
1582         <ul class="md-nav__list" data-md-scrollfix>
1583
1584
1585
1586
1587
1588     <li class="md-nav__item">
1589       <a href="../../migration/wsc52/php/" class="md-nav__link">
1590         PHP API
1591       </a>
1592     </li>
1593
1594
1595
1596
1597
1598
1599
1600     <li class="md-nav__item">
1601       <a href="../../migration/wsc52/templates/" class="md-nav__link">
1602         Templates and Languages
1603       </a>
1604     </li>
1605
1606
1607
1608
1609
1610
1611
1612     <li class="md-nav__item">
1613       <a href="../../migration/wsc52/libraries/" class="md-nav__link">
1614         Third Party Libraries
1615       </a>
1616     </li>
1617
1618
1619
1620         </ul>
1621       </nav>
1622     </li>
1623
1624
1625
1626
1627
1628
1629
1630
1631     <li class="md-nav__item md-nav__item--nested">
1632
1633
1634         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_3" type="checkbox" id="__nav_6_3" >
1635
1636       <label class="md-nav__link" for="__nav_6_3">
1637         Migrating from WSC 3.1
1638         <span class="md-nav__icon md-icon"></span>
1639       </label>
1640       <nav class="md-nav" aria-label="Migrating from WSC 3.1" data-md-level="2">
1641         <label class="md-nav__title" for="__nav_6_3">
1642           <span class="md-nav__icon md-icon"></span>
1643           Migrating from WSC 3.1
1644         </label>
1645         <ul class="md-nav__list" data-md-scrollfix>
1646
1647
1648
1649
1650
1651     <li class="md-nav__item">
1652       <a href="../../migration/wsc31/php/" class="md-nav__link">
1653         PHP API
1654       </a>
1655     </li>
1656
1657
1658
1659         </ul>
1660       </nav>
1661     </li>
1662
1663
1664
1665
1666
1667
1668
1669
1670     <li class="md-nav__item md-nav__item--nested">
1671
1672
1673         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_4" type="checkbox" id="__nav_6_4" >
1674
1675       <label class="md-nav__link" for="__nav_6_4">
1676         Migrating from WSC 3.0
1677         <span class="md-nav__icon md-icon"></span>
1678       </label>
1679       <nav class="md-nav" aria-label="Migrating from WSC 3.0" data-md-level="2">
1680         <label class="md-nav__title" for="__nav_6_4">
1681           <span class="md-nav__icon md-icon"></span>
1682           Migrating from WSC 3.0
1683         </label>
1684         <ul class="md-nav__list" data-md-scrollfix>
1685
1686
1687
1688
1689
1690     <li class="md-nav__item">
1691       <a href="../../migration/wsc30/php/" class="md-nav__link">
1692         PHP API
1693       </a>
1694     </li>
1695
1696
1697
1698
1699
1700
1701
1702     <li class="md-nav__item">
1703       <a href="../../migration/wsc30/javascript/" class="md-nav__link">
1704         JavaScript API
1705       </a>
1706     </li>
1707
1708
1709
1710
1711
1712
1713
1714     <li class="md-nav__item">
1715       <a href="../../migration/wsc30/templates/" class="md-nav__link">
1716         Templates
1717       </a>
1718     </li>
1719
1720
1721
1722
1723
1724
1725
1726     <li class="md-nav__item">
1727       <a href="../../migration/wsc30/css/" class="md-nav__link">
1728         CSS
1729       </a>
1730     </li>
1731
1732
1733
1734
1735
1736
1737
1738     <li class="md-nav__item">
1739       <a href="../../migration/wsc30/package/" class="md-nav__link">
1740         Package Components
1741       </a>
1742     </li>
1743
1744
1745
1746         </ul>
1747       </nav>
1748     </li>
1749
1750
1751
1752
1753
1754
1755
1756
1757     <li class="md-nav__item md-nav__item--nested">
1758
1759
1760         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_5" type="checkbox" id="__nav_6_5" >
1761
1762       <label class="md-nav__link" for="__nav_6_5">
1763         Migrating from WCF 2.1
1764         <span class="md-nav__icon md-icon"></span>
1765       </label>
1766       <nav class="md-nav" aria-label="Migrating from WCF 2.1" data-md-level="2">
1767         <label class="md-nav__title" for="__nav_6_5">
1768           <span class="md-nav__icon md-icon"></span>
1769           Migrating from WCF 2.1
1770         </label>
1771         <ul class="md-nav__list" data-md-scrollfix>
1772
1773
1774
1775
1776
1777     <li class="md-nav__item">
1778       <a href="../../migration/wcf21/php/" class="md-nav__link">
1779         PHP API
1780       </a>
1781     </li>
1782
1783
1784
1785
1786
1787
1788
1789     <li class="md-nav__item">
1790       <a href="../../migration/wcf21/templates/" class="md-nav__link">
1791         Templates
1792       </a>
1793     </li>
1794
1795
1796
1797
1798
1799
1800
1801     <li class="md-nav__item">
1802       <a href="../../migration/wcf21/css/" class="md-nav__link">
1803         CSS
1804       </a>
1805     </li>
1806
1807
1808
1809
1810
1811
1812
1813     <li class="md-nav__item">
1814       <a href="../../migration/wcf21/package/" class="md-nav__link">
1815         Package Components
1816       </a>
1817     </li>
1818
1819
1820
1821         </ul>
1822       </nav>
1823     </li>
1824
1825
1826
1827         </ul>
1828       </nav>
1829     </li>
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841     <li class="md-nav__item md-nav__item--nested">
1842
1843
1844         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" >
1845
1846       <label class="md-nav__link" for="__nav_7">
1847         Tutorials
1848         <span class="md-nav__icon md-icon"></span>
1849       </label>
1850       <nav class="md-nav" aria-label="Tutorials" data-md-level="1">
1851         <label class="md-nav__title" for="__nav_7">
1852           <span class="md-nav__icon md-icon"></span>
1853           Tutorials
1854         </label>
1855         <ul class="md-nav__list" data-md-scrollfix>
1856
1857
1858
1859
1860
1861
1862     <li class="md-nav__item md-nav__item--nested">
1863
1864
1865         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_1" type="checkbox" id="__nav_7_1" >
1866
1867       <label class="md-nav__link" for="__nav_7_1">
1868         Tutorial Series
1869         <span class="md-nav__icon md-icon"></span>
1870       </label>
1871       <nav class="md-nav" aria-label="Tutorial Series" data-md-level="2">
1872         <label class="md-nav__title" for="__nav_7_1">
1873           <span class="md-nav__icon md-icon"></span>
1874           Tutorial Series
1875         </label>
1876         <ul class="md-nav__list" data-md-scrollfix>
1877
1878
1879
1880
1881
1882     <li class="md-nav__item">
1883       <a href="../../tutorial/series/overview/" class="md-nav__link">
1884         Overview
1885       </a>
1886     </li>
1887
1888
1889
1890
1891
1892
1893
1894     <li class="md-nav__item">
1895       <a href="../../tutorial/series/part_1/" class="md-nav__link">
1896         Part 1
1897       </a>
1898     </li>
1899
1900
1901
1902
1903
1904
1905
1906     <li class="md-nav__item">
1907       <a href="../../tutorial/series/part_2/" class="md-nav__link">
1908         Part 2
1909       </a>
1910     </li>
1911
1912
1913
1914
1915
1916
1917
1918     <li class="md-nav__item">
1919       <a href="../../tutorial/series/part_3/" class="md-nav__link">
1920         Part 3
1921       </a>
1922     </li>
1923
1924
1925
1926
1927
1928
1929
1930     <li class="md-nav__item">
1931       <a href="../../tutorial/series/part_4/" class="md-nav__link">
1932         Part 4
1933       </a>
1934     </li>
1935
1936
1937
1938
1939
1940
1941
1942     <li class="md-nav__item">
1943       <a href="../../tutorial/series/part_5/" class="md-nav__link">
1944         Part 5
1945       </a>
1946     </li>
1947
1948
1949
1950         </ul>
1951       </nav>
1952     </li>
1953
1954
1955
1956         </ul>
1957       </nav>
1958     </li>
1959
1960
1961
1962   </ul>
1963 </nav>
1964                   </div>
1965                 </div>
1966               </div>
1967
1968
1969
1970               <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
1971                 <div class="md-sidebar__scrollwrap">
1972                   <div class="md-sidebar__inner">
1973
1974 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1975
1976
1977
1978
1979
1980
1981     <label class="md-nav__title" for="__toc">
1982       <span class="md-nav__icon md-icon"></span>
1983       Table of contents
1984     </label>
1985     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1986
1987         <li class="md-nav__item">
1988   <a href="#the-history-of-the-legacy-api" class="md-nav__link">
1989     The History of the Legacy API
1990   </a>
1991
1992 </li>
1993
1994         <li class="md-nav__item">
1995   <a href="#embedding-javascript-inside-templates" class="md-nav__link">
1996     Embedding JavaScript inside Templates
1997   </a>
1998
1999 </li>
2000
2001         <li class="md-nav__item">
2002   <a href="#including-external-javascript-files" class="md-nav__link">
2003     Including External JavaScript Files
2004   </a>
2005
2006     <nav class="md-nav" aria-label="Including External JavaScript Files">
2007       <ul class="md-nav__list">
2008
2009           <li class="md-nav__item">
2010   <a href="#debug-variants-and-cache-buster" class="md-nav__link">
2011     Debug-Variants and Cache-Buster
2012   </a>
2013
2014 </li>
2015
2016           <li class="md-nav__item">
2017   <a href="#the-accelerated-guest-view-tiny-builds" class="md-nav__link">
2018     The Accelerated Guest View ("Tiny Builds")
2019   </a>
2020
2021 </li>
2022
2023           <li class="md-nav__item">
2024   <a href="#the-js-template-plugin" class="md-nav__link">
2025     The {js} Template Plugin
2026   </a>
2027
2028 </li>
2029
2030       </ul>
2031     </nav>
2032
2033 </li>
2034
2035     </ul>
2036
2037 </nav>
2038                   </div>
2039                 </div>
2040               </div>
2041
2042
2043           <div class="md-content" data-md-component="content">
2044             <article class="md-content__inner md-typeset">
2045
2046
2047                   <a href="https://github.com/WoltLab/docs.woltlab.com/edit/5.4/docs/javascript/general-usage.md" title="Edit this page" class="md-content__button md-icon">
2048                     <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>
2049                   </a>
2050
2051
2052                 <h1 id="general-javascript-usage">General JavaScript Usage<a class="headerlink" href="#general-javascript-usage" title="Permanent link">#</a></h1>
2053 <div class="admonition info">
2054 <p class="admonition-title">WoltLab Suite 5.4 introduced support for TypeScript, migrating all existing modules to TypeScript. The JavaScript section of the documentation is not yet updated to account for the changes, possibly explaining concepts that cannot be applied as-is when writing TypeScript. You can learn about basic TypeScript use in WoltLab Suite, such as consuming WoltLab Suite’s types in own packages, within in <a href="../typescript/">the TypeScript section</a>.</p>
2055 </div>
2056 <h2 id="the-history-of-the-legacy-api">The History of the Legacy API<a class="headerlink" href="#the-history-of-the-legacy-api" title="Permanent link">#</a></h2>
2057 <p>The WoltLab Suite 3.0 <a href="../new-api_writing-a-module/">introduced a new API</a> based on AMD-Modules
2058 with ES5-JavaScript that was designed with high performance and visible dependencies
2059 in mind. This was a fundamental change in comparison to <a href="../legacy-api/">the legacy API</a>
2060 that was build many years before while jQuery was still a thing and we had to deal
2061 with ancient browsers such as Internet Explorer 9 that felt short in both CSS and
2062 JavaScript capabilities.</p>
2063 <p>Fast forward a few years, the old API is still around and most important, it is
2064 actively being used by some components that have not been rewritten yet. This
2065 has been done to preserve the backwards-compatibility and to avoid the
2066 significant amount of work that it requires to rewrite a component. The components
2067 invoked on page initialization have all been rewritten to use the modern API, but
2068 some deferred objects that are invoked later during the page runtime may still
2069 use the old API.</p>
2070 <p>However, the legacy API is deprecated and you should not rely on it for new
2071 components at all. It slowly but steadily gets replaced up until a point where its
2072 last bits are finally removed from the code base.</p>
2073 <h2 id="embedding-javascript-inside-templates">Embedding JavaScript inside Templates<a class="headerlink" href="#embedding-javascript-inside-templates" title="Permanent link">#</a></h2>
2074 <p>The <code>&lt;script&gt;</code>-tags are extracted and moved during template processing, eventually
2075 placing them at the very end of the body element while preserving their order of
2076 appearance.</p>
2077 <p>This behavior is controlled through the <code>data-relocate="true"</code> attribute on the <code>&lt;script&gt;</code>
2078 which is mandatory for almost all scripts, mostly because their dependencies (such
2079 as jQuery) are moved to the bottom anyway.</p>
2080 <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 1</span>
2081 <span class="normal"> 2</span>
2082 <span class="normal"> 3</span>
2083 <span class="normal"> 4</span>
2084 <span class="normal"> 5</span>
2085 <span class="normal"> 6</span>
2086 <span class="normal"> 7</span>
2087 <span class="normal"> 8</span>
2088 <span class="normal"> 9</span>
2089 <span class="normal">10</span>
2090 <span class="normal">11</span>
2091 <span class="normal">12</span>
2092 <span class="normal">13</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><code><span class="p">&lt;</span><span class="nt">script</span> <span class="na">data-relocate</span><span class="o">=</span><span class="s">&quot;true&quot;</span><span class="p">&gt;</span>
2093   <span class="nx">$</span><span class="p">(</span><span class="kd">function</span><span class="p">()</span> <span class="p">{</span>
2094     <span class="c1">// Code that uses jQuery (Legacy API)</span>
2095   <span class="p">});</span>
2096 <span class="p">&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
2097
2098 <span class="c">&lt;!-- or --&gt;</span>
2099
2100 <span class="p">&lt;</span><span class="nt">script</span> <span class="na">data-relocate</span><span class="o">=</span><span class="s">&quot;true&quot;</span><span class="p">&gt;</span>
2101   <span class="nx">require</span><span class="p">([</span><span class="s2">&quot;Some&quot;</span><span class="p">,</span> <span class="s2">&quot;Dependencies&quot;</span><span class="p">],</span> <span class="kd">function</span><span class="p">(</span><span class="nx">Some</span><span class="p">,</span> <span class="nx">Dependencies</span><span class="p">)</span> <span class="p">{</span>
2102     <span class="c1">// Modern API</span>
2103   <span class="p">});</span>
2104 <span class="p">&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
2105 </code></pre></div>
2106 </td></tr></table>
2107 <h2 id="including-external-javascript-files">Including External JavaScript Files<a class="headerlink" href="#including-external-javascript-files" title="Permanent link">#</a></h2>
2108 <p>The AMD-Modules used in the new API are automatically recognized and lazy-loaded
2109 on demand, so unless you have a rather large and pre-compiled code-base, there
2110 is nothing else to worry about.</p>
2111 <h3 id="debug-variants-and-cache-buster">Debug-Variants and Cache-Buster<a class="headerlink" href="#debug-variants-and-cache-buster" title="Permanent link">#</a></h3>
2112 <p>Your JavaScript files may change over time and you would want the users' browsers
2113 to always load and use the latest version of your files. This can be achieved by
2114 appending the special <code>LAST_UPDATE_TIME</code> constant to your file path. It contains
2115 the unix timestamp of the last time any package was installed, updated or removed
2116 and thus avoid outdated caches by relying on a unique value, without invalidating
2117 the cache more often that it needs to be.</p>
2118 <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><code><span class="p">&lt;</span><span class="nt">script</span> <span class="na">data-relocate</span><span class="o">=</span><span class="s">&quot;true&quot;</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;{@$__wcf-&gt;getPath(&#39;app&#39;)}js/App.js?t={@LAST_UPDATE_TIME}&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
2119 </code></pre></div>
2120 </td></tr></table>
2121 <p>For small scripts you can simply serve the full, non-minified version to the user
2122 at all times, the differences in size and execution speed are insignificant and
2123 are very unlikely to offer any benefits. They might even yield a worse performance,
2124 because you'll have to include them statically in the template, even if the code
2125 is never called.</p>
2126 <p>However, if you're including a minified build in your app or plugin, you should
2127 include a switch to load the uncompressed version in the debug mode, while serving
2128 the minified and optimized file to the average visitor. You should use the
2129 <code>ENABLE_DEBUG_MODE</code> constant to decide which version should be loaded.</p>
2130 <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><code><span class="p">&lt;</span><span class="nt">script</span> <span class="na">data-relocate</span><span class="o">=</span><span class="s">&quot;true&quot;</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;{@$__wcf-&gt;getPath(&#39;app&#39;)}js/App{if !ENABLE_DEBUG_MODE}.min{/if}.js?t={@LAST_UPDATE_TIME}&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
2131 </code></pre></div>
2132 </td></tr></table>
2133 <h3 id="the-accelerated-guest-view-tiny-builds">The Accelerated Guest View ("Tiny Builds")<a class="headerlink" href="#the-accelerated-guest-view-tiny-builds" title="Permanent link">#</a></h3>
2134 <div class="admonition info">
2135 <p class="admonition-title">You can learn more on the <a href="../../migration/wsc30/javascript/">Accelerated Guest View</a> in the migration docs.</p>
2136 </div>
2137 <p>The "Accelerated Guest View" was introduced in WoltLab Suite 3.1 and aims to
2138 decrease page size and to improve responsiveness by enabling a read-only mode
2139 for visitors. If you are providing a separate compiled build for this mode, you'll
2140 need to include yet another switch to serve the right version to the visitor.</p>
2141 <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><code><span class="p">&lt;</span><span class="nt">script</span> <span class="na">data-relocate</span><span class="o">=</span><span class="s">&quot;true&quot;</span> <span class="na">src</span><span class="o">=</span><span class="s">&quot;{@$__wcf-&gt;getPath(&#39;app&#39;)}js/App{if !ENABLE_DEBUG_MODE}{if VISITOR_USE_TINY_BUILD}.tiny{/if}.min{/if}.js?t={@LAST_UPDATE_TIME}&quot;</span><span class="p">&gt;&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
2142 </code></pre></div>
2143 </td></tr></table>
2144 <h3 id="the-js-template-plugin">The <code>{js}</code> Template Plugin<a class="headerlink" href="#the-js-template-plugin" title="Permanent link">#</a></h3>
2145 <p>The <code>{js}</code> template plugin exists solely to provide a much easier and less error-prone
2146 method to include external JavaScript files.</p>
2147 <table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1</span></pre></div></td><td class="code"><div class="highlight"><pre><span></span><code>{js application=&#39;app&#39; file=&#39;App&#39; hasTiny=true}
2148 </code></pre></div>
2149 </td></tr></table>
2150 <p>The <code>hasTiny</code> attribute is optional, you can set it to <code>false</code> or just omit it
2151 entirely if you do not provide a tiny build for your file.</p>
2152
2153
2154
2155
2156 <hr>
2157 <div class="md-source-date">
2158   <small>
2159
2160       Last update: 2021-04-13
2161
2162   </small>
2163 </div>
2164
2165
2166
2167
2168
2169
2170
2171
2172             </article>
2173           </div>
2174         </div>
2175
2176       </main>
2177
2178
2179 <footer class="md-footer">
2180
2181     <nav class="md-footer__inner md-grid" aria-label="Footer">
2182
2183         <a href="../../view/css/" class="md-footer__link md-footer__link--prev" rel="prev">
2184           <div class="md-footer__button md-icon">
2185             <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>
2186           </div>
2187           <div class="md-footer__title">
2188             <div class="md-ellipsis">
2189               <span class="md-footer__direction">
2190                 Previous
2191               </span>
2192               CSS
2193             </div>
2194           </div>
2195         </a>
2196
2197
2198         <a href="../typescript/" class="md-footer__link md-footer__link--next" rel="next">
2199           <div class="md-footer__title">
2200             <div class="md-ellipsis">
2201               <span class="md-footer__direction">
2202                 Next
2203               </span>
2204               TypeScript
2205             </div>
2206           </div>
2207           <div class="md-footer__button md-icon">
2208             <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>
2209           </div>
2210         </a>
2211
2212     </nav>
2213
2214   <div class="md-footer-meta md-typeset">
2215     <div class="md-footer-meta__inner md-grid">
2216       <div class="md-footer-copyright">
2217
2218           <div class="md-footer-copyright__highlight">
2219             Copyright © 2020 WoltLab GmbH
2220           </div>
2221
2222         Made with
2223         <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
2224           Material for MkDocs
2225         </a>
2226
2227       </div>
2228       <div class="md-footer-copyright">
2229         <a href="https://www.woltlab.com/legal-notice/">Legal Notice</a>
2230         <a href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
2231 </div>
2232     </div>
2233   </div>
2234 </footer>
2235
2236     </div>
2237     <div class="md-dialog" data-md-component="dialog">
2238       <div class="md-dialog__inner md-typeset"></div>
2239     </div>
2240     <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>
2241
2242
2243       <script src="../../assets/javascripts/bundle.4ea5477f.min.js"></script>
2244
2245
2246   </body>
2247 </html>