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