5.4/getting-started/index.html

   1
   2 <!doctype html>
   3 <html lang="en" class="no-js">
   4   <head>
   5
   6       <meta charset="utf-8">
   7       <meta name="viewport" content="width=device-width,initial-scale=1">
   8
   9
  10
  11
  12       <link rel="shortcut icon" href="../assets/default.favicon.ico">
  13       <meta name="generator" content="mkdocs-1.1.2, mkdocs-material-7.0.5">
  14
  15
  16
  17         <title>Getting Started - WoltLab Suite Documentation</title>
  18
  19
  20
  21       <link rel="stylesheet" href="../assets/stylesheets/main.77f3fd56.min.css">
  22
  23
  24         <link rel="stylesheet" href="../assets/stylesheets/palette.7fa14f5b.min.css">
  25
  26
  27
  28           <meta name="theme-color" content="#009485">
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38       <link rel="stylesheet" href="../stylesheets/extra.css">
  39
  40
  41
  42
  43
  44   </head>
  45
  46
  47
  48
  49
  50
  51
  52     <body dir="ltr" data-md-color-scheme="" data-md-color-primary="teal" data-md-color-accent="">
  53
  54
  55
  56     <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
  57     <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
  58     <label class="md-overlay" for="__drawer"></label>
  59     <div data-md-component="skip">
  60
  61
  62         <a href="#creating-a-simple-package" class="md-skip">
  63           Skip to content
  64         </a>
  65
  66     </div>
  67     <div data-md-component="announce">
  68
  69         <aside class="md-announce">
  70           <div class="md-announce__inner md-grid md-typeset">
  71
  72     <a href="https://www.woltlab.com">Back to <strong>woltlab.com</strong></a>
  73
  74           </div>
  75         </aside>
  76
  77     </div>
  78
  79
  80
  81 <header class="md-header" data-md-component="header">
  82   <nav class="md-header__inner md-grid" aria-label="Header">
  83     <a href=".." title="WoltLab Suite Documentation" class="md-header__button md-logo" aria-label="WoltLab Suite Documentation">
  84
  85   <img src="../assets/logo.png" alt="logo">
  86
  87     </a>
  88     <label class="md-header__button md-icon" for="__drawer">
  89       <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
  90     </label>
  91     <div class="md-header__title" data-md-component="header-title">
  92       <div class="md-header__ellipsis">
  93         <div class="md-header__topic">
  94           <span class="md-ellipsis">
  95             WoltLab Suite Documentation
  96           </span>
  97         </div>
  98         <div class="md-header__topic" data-md-component="header-topic">
  99           <span class="md-ellipsis">
 100
 101               Getting Started
 102
 103           </span>
 104         </div>
 105       </div>
 106     </div>
 107     <div class="md-header__options">
 108
 109     </div>
 110
 111
 112       <div class="md-header__source">
 113
 114 <a href="https://github.com/WoltLab/docs.woltlab.com/" title="Go to repository" class="md-source" data-md-component="source">
 115   <div class="md-source__icon md-icon">
 116
 117     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05L244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
 118   </div>
 119   <div class="md-source__repository">
 120     GitHub
 121   </div>
 122 </a>
 123       </div>
 124
 125   </nav>
 126 </header>
 127
 128     <div class="md-container" data-md-component="container">
 129
 130
 131
 132
 133       <main class="md-main" data-md-component="main">
 134         <div class="md-main__inner md-grid">
 135
 136
 137
 138               <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
 139                 <div class="md-sidebar__scrollwrap">
 140                   <div class="md-sidebar__inner">
 141
 142
 143
 144
 145
 146 <nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
 147   <label class="md-nav__title" for="__drawer">
 148     <a href=".." title="WoltLab Suite Documentation" class="md-nav__button md-logo" aria-label="WoltLab Suite Documentation">
 149
 150   <img src="../assets/logo.png" alt="logo">
 151
 152     </a>
 153     WoltLab Suite Documentation
 154   </label>
 155
 156     <div class="md-nav__source">
 157
 158 <a href="https://github.com/WoltLab/docs.woltlab.com/" title="Go to repository" class="md-source" data-md-component="source">
 159   <div class="md-source__icon md-icon">
 160
 161     <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path d="M439.55 236.05L244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
 162   </div>
 163   <div class="md-source__repository">
 164     GitHub
 165   </div>
 166 </a>
 167     </div>
 168
 169   <ul class="md-nav__list" data-md-scrollfix>
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180     <li class="md-nav__item md-nav__item--active">
 181
 182       <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
 183
 184
 185
 186
 187         <label class="md-nav__link md-nav__link--active" for="__toc">
 188           Getting Started
 189           <span class="md-nav__icon md-icon"></span>
 190         </label>
 191
 192       <a href="./" class="md-nav__link md-nav__link--active">
 193         Getting Started
 194       </a>
 195
 196
 197 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
 198
 199
 200
 201
 202
 203     <label class="md-nav__title" for="__toc">
 204       <span class="md-nav__icon md-icon"></span>
 205       Table of contents
 206     </label>
 207     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 208
 209         <li class="md-nav__item">
 210   <a href="#setup-and-requirements" class="md-nav__link">
 211     Setup and Requirements
 212   </a>
 213
 214 </li>
 215
 216         <li class="md-nav__item">
 217   <a href="#the-packagexml-file" class="md-nav__link">
 218     The package.xml File
 219   </a>
 220
 221 </li>
 222
 223         <li class="md-nav__item">
 224   <a href="#the-php-class" class="md-nav__link">
 225     The PHP Class
 226   </a>
 227
 228 </li>
 229
 230         <li class="md-nav__item">
 231   <a href="#the-template" class="md-nav__link">
 232     The Template
 233   </a>
 234
 235 </li>
 236
 237         <li class="md-nav__item">
 238   <a href="#the-page-definition" class="md-nav__link">
 239     The Page Definition
 240   </a>
 241
 242 </li>
 243
 244         <li class="md-nav__item">
 245   <a href="#building-the-package" class="md-nav__link">
 246     Building the Package
 247   </a>
 248
 249 </li>
 250
 251         <li class="md-nav__item">
 252   <a href="#installation" class="md-nav__link">
 253     Installation
 254   </a>
 255
 256 </li>
 257
 258         <li class="md-nav__item">
 259   <a href="#developer-tools" class="md-nav__link">
 260     Developer Tools
 261   </a>
 262
 263     <nav class="md-nav" aria-label="Developer Tools">
 264       <ul class="md-nav__list">
 265
 266           <li class="md-nav__item">
 267   <a href="#registering-a-project" class="md-nav__link">
 268     Registering a Project
 269   </a>
 270
 271 </li>
 272
 273           <li class="md-nav__item">
 274   <a href="#synchronizing" class="md-nav__link">
 275     Synchronizing
 276   </a>
 277
 278 </li>
 279
 280       </ul>
 281     </nav>
 282
 283 </li>
 284
 285         <li class="md-nav__item">
 286   <a href="#appendix" class="md-nav__link">
 287     Appendix
 288   </a>
 289
 290     <nav class="md-nav" aria-label="Appendix">
 291       <ul class="md-nav__list">
 292
 293           <li class="md-nav__item">
 294   <a href="#template-guessing" class="md-nav__link">
 295     Template Guessing
 296   </a>
 297
 298 </li>
 299
 300       </ul>
 301     </nav>
 302
 303 </li>
 304
 305     </ul>
 306
 307 </nav>
 308
 309     </li>
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321     <li class="md-nav__item md-nav__item--nested">
 322
 323
 324         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" >
 325
 326       <label class="md-nav__link" for="__nav_2">
 327         PHP API
 328         <span class="md-nav__icon md-icon"></span>
 329       </label>
 330       <nav class="md-nav" aria-label="PHP API" data-md-level="1">
 331         <label class="md-nav__title" for="__nav_2">
 332           <span class="md-nav__icon md-icon"></span>
 333           PHP API
 334         </label>
 335         <ul class="md-nav__list" data-md-scrollfix>
 336
 337
 338
 339
 340
 341     <li class="md-nav__item">
 342       <a href="../php/pages/" class="md-nav__link">
 343         Pages
 344       </a>
 345     </li>
 346
 347
 348
 349
 350
 351
 352
 353     <li class="md-nav__item">
 354       <a href="../php/database-objects/" class="md-nav__link">
 355         Database Objects
 356       </a>
 357     </li>
 358
 359
 360
 361
 362
 363
 364
 365     <li class="md-nav__item">
 366       <a href="../php/database-access/" class="md-nav__link">
 367         Database Access
 368       </a>
 369     </li>
 370
 371
 372
 373
 374
 375
 376
 377     <li class="md-nav__item">
 378       <a href="../php/exceptions/" class="md-nav__link">
 379         Exceptions
 380       </a>
 381     </li>
 382
 383
 384
 385
 386
 387
 388
 389
 390     <li class="md-nav__item md-nav__item--nested">
 391
 392
 393         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5" type="checkbox" id="__nav_2_5" >
 394
 395       <label class="md-nav__link" for="__nav_2_5">
 396         API
 397         <span class="md-nav__icon md-icon"></span>
 398       </label>
 399       <nav class="md-nav" aria-label="API" data-md-level="2">
 400         <label class="md-nav__title" for="__nav_2_5">
 401           <span class="md-nav__icon md-icon"></span>
 402           API
 403         </label>
 404         <ul class="md-nav__list" data-md-scrollfix>
 405
 406
 407
 408
 409
 410     <li class="md-nav__item">
 411       <a href="../php/api/caches/" class="md-nav__link">
 412         Caches
 413       </a>
 414     </li>
 415
 416
 417
 418
 419
 420
 421
 422     <li class="md-nav__item">
 423       <a href="../php/api/comments/" class="md-nav__link">
 424         Comments
 425       </a>
 426     </li>
 427
 428
 429
 430
 431
 432
 433
 434     <li class="md-nav__item">
 435       <a href="../php/api/cronjobs/" class="md-nav__link">
 436         Cronjobs
 437       </a>
 438     </li>
 439
 440
 441
 442
 443
 444
 445
 446     <li class="md-nav__item">
 447       <a href="../php/api/events/" class="md-nav__link">
 448         Events
 449       </a>
 450     </li>
 451
 452
 453
 454
 455
 456
 457
 458
 459     <li class="md-nav__item md-nav__item--nested">
 460
 461
 462         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5_5" type="checkbox" id="__nav_2_5_5" >
 463
 464       <label class="md-nav__link" for="__nav_2_5_5">
 465         Form Builder
 466         <span class="md-nav__icon md-icon"></span>
 467       </label>
 468       <nav class="md-nav" aria-label="Form Builder" data-md-level="3">
 469         <label class="md-nav__title" for="__nav_2_5_5">
 470           <span class="md-nav__icon md-icon"></span>
 471           Form Builder
 472         </label>
 473         <ul class="md-nav__list" data-md-scrollfix>
 474
 475
 476
 477
 478
 479     <li class="md-nav__item">
 480       <a href="../php/api/form_builder/overview/" class="md-nav__link">
 481         Overview
 482       </a>
 483     </li>
 484
 485
 486
 487
 488
 489
 490
 491     <li class="md-nav__item">
 492       <a href="../php/api/form_builder/structure/" class="md-nav__link">
 493         Structure
 494       </a>
 495     </li>
 496
 497
 498
 499
 500
 501
 502
 503     <li class="md-nav__item">
 504       <a href="../php/api/form_builder/form_fields/" class="md-nav__link">
 505         Fields
 506       </a>
 507     </li>
 508
 509
 510
 511
 512
 513
 514
 515     <li class="md-nav__item">
 516       <a href="../php/api/form_builder/validation_data/" class="md-nav__link">
 517         Validation and Data
 518       </a>
 519     </li>
 520
 521
 522
 523
 524
 525
 526
 527     <li class="md-nav__item">
 528       <a href="../php/api/form_builder/dependencies/" class="md-nav__link">
 529         Dependencies
 530       </a>
 531     </li>
 532
 533
 534
 535         </ul>
 536       </nav>
 537     </li>
 538
 539
 540
 541
 542
 543
 544
 545     <li class="md-nav__item">
 546       <a href="../php/api/package_installation_plugins/" class="md-nav__link">
 547         Package Installation Plugins
 548       </a>
 549     </li>
 550
 551
 552
 553
 554
 555
 556
 557     <li class="md-nav__item">
 558       <a href="../php/api/user_activity_points/" class="md-nav__link">
 559         User Activity Points
 560       </a>
 561     </li>
 562
 563
 564
 565
 566
 567
 568
 569     <li class="md-nav__item">
 570       <a href="../php/api/user_notifications/" class="md-nav__link">
 571         User Notifications
 572       </a>
 573     </li>
 574
 575
 576
 577
 578
 579
 580
 581     <li class="md-nav__item">
 582       <a href="../php/api/sitemaps/" class="md-nav__link">
 583         Sitemaps
 584       </a>
 585     </li>
 586
 587
 588
 589         </ul>
 590       </nav>
 591     </li>
 592
 593
 594
 595
 596
 597
 598
 599     <li class="md-nav__item">
 600       <a href="../php/code-style/" class="md-nav__link">
 601         Code Style
 602       </a>
 603     </li>
 604
 605
 606
 607
 608
 609
 610
 611     <li class="md-nav__item">
 612       <a href="../php/apps/" class="md-nav__link">
 613         Apps
 614       </a>
 615     </li>
 616
 617
 618
 619
 620
 621
 622
 623     <li class="md-nav__item">
 624       <a href="../php/gdpr/" class="md-nav__link">
 625         GDPR
 626       </a>
 627     </li>
 628
 629
 630
 631         </ul>
 632       </nav>
 633     </li>
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645     <li class="md-nav__item md-nav__item--nested">
 646
 647
 648         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" >
 649
 650       <label class="md-nav__link" for="__nav_3">
 651         Languages, Templates & CSS
 652         <span class="md-nav__icon md-icon"></span>
 653       </label>
 654       <nav class="md-nav" aria-label="Languages, Templates & CSS" data-md-level="1">
 655         <label class="md-nav__title" for="__nav_3">
 656           <span class="md-nav__icon md-icon"></span>
 657           Languages, Templates & CSS
 658         </label>
 659         <ul class="md-nav__list" data-md-scrollfix>
 660
 661
 662
 663
 664
 665     <li class="md-nav__item">
 666       <a href="../view/languages/" class="md-nav__link">
 667         Languages
 668       </a>
 669     </li>
 670
 671
 672
 673
 674
 675
 676
 677     <li class="md-nav__item">
 678       <a href="../view/templates/" class="md-nav__link">
 679         Templates
 680       </a>
 681     </li>
 682
 683
 684
 685
 686
 687
 688
 689     <li class="md-nav__item">
 690       <a href="../view/css/" class="md-nav__link">
 691         CSS
 692       </a>
 693     </li>
 694
 695
 696
 697         </ul>
 698       </nav>
 699     </li>
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711     <li class="md-nav__item md-nav__item--nested">
 712
 713
 714         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" >
 715
 716       <label class="md-nav__link" for="__nav_4">
 717         JavaScript API
 718         <span class="md-nav__icon md-icon"></span>
 719       </label>
 720       <nav class="md-nav" aria-label="JavaScript API" data-md-level="1">
 721         <label class="md-nav__title" for="__nav_4">
 722           <span class="md-nav__icon md-icon"></span>
 723           JavaScript API
 724         </label>
 725         <ul class="md-nav__list" data-md-scrollfix>
 726
 727
 728
 729
 730
 731     <li class="md-nav__item">
 732       <a href="../javascript/general-usage/" class="md-nav__link">
 733         General Usage
 734       </a>
 735     </li>
 736
 737
 738
 739
 740
 741
 742
 743
 744     <li class="md-nav__item md-nav__item--nested">
 745
 746
 747         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4_2" type="checkbox" id="__nav_4_2" >
 748
 749       <label class="md-nav__link" for="__nav_4_2">
 750         New API
 751         <span class="md-nav__icon md-icon"></span>
 752       </label>
 753       <nav class="md-nav" aria-label="New API" data-md-level="2">
 754         <label class="md-nav__title" for="__nav_4_2">
 755           <span class="md-nav__icon md-icon"></span>
 756           New API
 757         </label>
 758         <ul class="md-nav__list" data-md-scrollfix>
 759
 760
 761
 762
 763
 764     <li class="md-nav__item">
 765       <a href="../javascript/new-api_writing-a-module/" class="md-nav__link">
 766         Writing a module
 767       </a>
 768     </li>
 769
 770
 771
 772
 773
 774
 775
 776     <li class="md-nav__item">
 777       <a href="../javascript/new-api_data-structures/" class="md-nav__link">
 778         Data Structures
 779       </a>
 780     </li>
 781
 782
 783
 784
 785
 786
 787
 788     <li class="md-nav__item">
 789       <a href="../javascript/new-api_core/" class="md-nav__link">
 790         Core Functions
 791       </a>
 792     </li>
 793
 794
 795
 796
 797
 798
 799
 800     <li class="md-nav__item">
 801       <a href="../javascript/new-api_dom/" class="md-nav__link">
 802         DOM
 803       </a>
 804     </li>
 805
 806
 807
 808
 809
 810
 811
 812     <li class="md-nav__item">
 813       <a href="../javascript/new-api_events/" class="md-nav__link">
 814         Event Handling
 815       </a>
 816     </li>
 817
 818
 819
 820
 821
 822
 823
 824     <li class="md-nav__item">
 825       <a href="../javascript/new-api_ajax/" class="md-nav__link">
 826         Ajax
 827       </a>
 828     </li>
 829
 830
 831
 832
 833
 834
 835
 836     <li class="md-nav__item">
 837       <a href="../javascript/new-api_dialogs/" class="md-nav__link">
 838         Dialogs
 839       </a>
 840     </li>
 841
 842
 843
 844
 845
 846
 847
 848     <li class="md-nav__item">
 849       <a href="../javascript/new-api_browser/" class="md-nav__link">
 850         Browser and Screen Sizes
 851       </a>
 852     </li>
 853
 854
 855
 856
 857
 858
 859
 860     <li class="md-nav__item">
 861       <a href="../javascript/new-api_ui/" class="md-nav__link">
 862         User Interface
 863       </a>
 864     </li>
 865
 866
 867
 868         </ul>
 869       </nav>
 870     </li>
 871
 872
 873
 874
 875
 876
 877
 878     <li class="md-nav__item">
 879       <a href="../javascript/legacy-api/" class="md-nav__link">
 880         Legacy API
 881       </a>
 882     </li>
 883
 884
 885
 886
 887
 888
 889
 890     <li class="md-nav__item">
 891       <a href="../javascript/helper-functions/" class="md-nav__link">
 892         Helper Functions
 893       </a>
 894     </li>
 895
 896
 897
 898
 899
 900
 901
 902     <li class="md-nav__item">
 903       <a href="../javascript/code-snippets/" class="md-nav__link">
 904         Code Snippets
 905       </a>
 906     </li>
 907
 908
 909
 910         </ul>
 911       </nav>
 912     </li>
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924     <li class="md-nav__item md-nav__item--nested">
 925
 926
 927         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
 928
 929       <label class="md-nav__link" for="__nav_5">
 930         Package Components
 931         <span class="md-nav__icon md-icon"></span>
 932       </label>
 933       <nav class="md-nav" aria-label="Package Components" data-md-level="1">
 934         <label class="md-nav__title" for="__nav_5">
 935           <span class="md-nav__icon md-icon"></span>
 936           Package Components
 937         </label>
 938         <ul class="md-nav__list" data-md-scrollfix>
 939
 940
 941
 942
 943
 944     <li class="md-nav__item">
 945       <a href="../package/package-xml/" class="md-nav__link">
 946         package.xml
 947       </a>
 948     </li>
 949
 950
 951
 952
 953
 954
 955
 956
 957     <li class="md-nav__item md-nav__item--nested">
 958
 959
 960         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5_2" type="checkbox" id="__nav_5_2" >
 961
 962       <label class="md-nav__link" for="__nav_5_2">
 963         PIPs
 964         <span class="md-nav__icon md-icon"></span>
 965       </label>
 966       <nav class="md-nav" aria-label="PIPs" data-md-level="2">
 967         <label class="md-nav__title" for="__nav_5_2">
 968           <span class="md-nav__icon md-icon"></span>
 969           PIPs
 970         </label>
 971         <ul class="md-nav__list" data-md-scrollfix>
 972
 973
 974
 975
 976
 977     <li class="md-nav__item">
 978       <a href="../package/pip/" class="md-nav__link">
 979         Overview
 980       </a>
 981     </li>
 982
 983
 984
 985
 986
 987
 988
 989     <li class="md-nav__item">
 990       <a href="../package/pip/acl-option/" class="md-nav__link">
 991         aclOption
 992       </a>
 993     </li>
 994
 995
 996
 997
 998
 999
1000
1001     <li class="md-nav__item">
1002       <a href="../package/pip/acp-menu/" class="md-nav__link">
1003         acpMenu
1004       </a>
1005     </li>
1006
1007
1008
1009
1010
1011
1012
1013     <li class="md-nav__item">
1014       <a href="../package/pip/acp-search-provider/" class="md-nav__link">
1015         acpSearchProvider
1016       </a>
1017     </li>
1018
1019
1020
1021
1022
1023
1024
1025     <li class="md-nav__item">
1026       <a href="../package/pip/acp-template/" class="md-nav__link">
1027         acpTemplate
1028       </a>
1029     </li>
1030
1031
1032
1033
1034
1035
1036
1037     <li class="md-nav__item">
1038       <a href="../package/pip/bbcode/" class="md-nav__link">
1039         bbcode
1040       </a>
1041     </li>
1042
1043
1044
1045
1046
1047
1048
1049     <li class="md-nav__item">
1050       <a href="../package/pip/box/" class="md-nav__link">
1051         box
1052       </a>
1053     </li>
1054
1055
1056
1057
1058
1059
1060
1061     <li class="md-nav__item">
1062       <a href="../package/pip/clipboard-action/" class="md-nav__link">
1063         clipboardAction
1064       </a>
1065     </li>
1066
1067
1068
1069
1070
1071
1072
1073     <li class="md-nav__item">
1074       <a href="../package/pip/core-object/" class="md-nav__link">
1075         coreObject
1076       </a>
1077     </li>
1078
1079
1080
1081
1082
1083
1084
1085     <li class="md-nav__item">
1086       <a href="../package/pip/cronjob/" class="md-nav__link">
1087         cronjob
1088       </a>
1089     </li>
1090
1091
1092
1093
1094
1095
1096
1097     <li class="md-nav__item">
1098       <a href="../package/pip/event-listener/" class="md-nav__link">
1099         eventListener
1100       </a>
1101     </li>
1102
1103
1104
1105
1106
1107
1108
1109     <li class="md-nav__item">
1110       <a href="../package/pip/file/" class="md-nav__link">
1111         file
1112       </a>
1113     </li>
1114
1115
1116
1117
1118
1119
1120
1121     <li class="md-nav__item">
1122       <a href="../package/pip/language/" class="md-nav__link">
1123         language
1124       </a>
1125     </li>
1126
1127
1128
1129
1130
1131
1132
1133     <li class="md-nav__item">
1134       <a href="../package/pip/media-provider/" class="md-nav__link">
1135         mediaProvider
1136       </a>
1137     </li>
1138
1139
1140
1141
1142
1143
1144
1145     <li class="md-nav__item">
1146       <a href="../package/pip/menu/" class="md-nav__link">
1147         menu
1148       </a>
1149     </li>
1150
1151
1152
1153
1154
1155
1156
1157     <li class="md-nav__item">
1158       <a href="../package/pip/menu-item/" class="md-nav__link">
1159         menuItem
1160       </a>
1161     </li>
1162
1163
1164
1165
1166
1167
1168
1169     <li class="md-nav__item">
1170       <a href="../package/pip/object-type/" class="md-nav__link">
1171         objectType
1172       </a>
1173     </li>
1174
1175
1176
1177
1178
1179
1180
1181     <li class="md-nav__item">
1182       <a href="../package/pip/object-type-definition/" class="md-nav__link">
1183         objectTypeDefinition
1184       </a>
1185     </li>
1186
1187
1188
1189
1190
1191
1192
1193     <li class="md-nav__item">
1194       <a href="../package/pip/option/" class="md-nav__link">
1195         option
1196       </a>
1197     </li>
1198
1199
1200
1201
1202
1203
1204
1205     <li class="md-nav__item">
1206       <a href="../package/pip/page/" class="md-nav__link">
1207         page
1208       </a>
1209     </li>
1210
1211
1212
1213
1214
1215
1216
1217     <li class="md-nav__item">
1218       <a href="../package/pip/pip/" class="md-nav__link">
1219         pip
1220       </a>
1221     </li>
1222
1223
1224
1225
1226
1227
1228
1229     <li class="md-nav__item">
1230       <a href="../package/pip/script/" class="md-nav__link">
1231         script
1232       </a>
1233     </li>
1234
1235
1236
1237
1238
1239
1240
1241     <li class="md-nav__item">
1242       <a href="../package/pip/smiley/" class="md-nav__link">
1243         smiley
1244       </a>
1245     </li>
1246
1247
1248
1249
1250
1251
1252
1253     <li class="md-nav__item">
1254       <a href="../package/pip/sql/" class="md-nav__link">
1255         sql
1256       </a>
1257     </li>
1258
1259
1260
1261
1262
1263
1264
1265     <li class="md-nav__item">
1266       <a href="../package/pip/style/" class="md-nav__link">
1267         style
1268       </a>
1269     </li>
1270
1271
1272
1273
1274
1275
1276
1277     <li class="md-nav__item">
1278       <a href="../package/pip/template/" class="md-nav__link">
1279         template
1280       </a>
1281     </li>
1282
1283
1284
1285
1286
1287
1288
1289     <li class="md-nav__item">
1290       <a href="../package/pip/template-listener/" class="md-nav__link">
1291         templateListener
1292       </a>
1293     </li>
1294
1295
1296
1297
1298
1299
1300
1301     <li class="md-nav__item">
1302       <a href="../package/pip/user-group-option/" class="md-nav__link">
1303         userGroupOption
1304       </a>
1305     </li>
1306
1307
1308
1309
1310
1311
1312
1313     <li class="md-nav__item">
1314       <a href="../package/pip/user-menu/" class="md-nav__link">
1315         userMenu
1316       </a>
1317     </li>
1318
1319
1320
1321
1322
1323
1324
1325     <li class="md-nav__item">
1326       <a href="../package/pip/user-notification-event/" class="md-nav__link">
1327         userNotificationEvent
1328       </a>
1329     </li>
1330
1331
1332
1333
1334
1335
1336
1337     <li class="md-nav__item">
1338       <a href="../package/pip/user-option/" class="md-nav__link">
1339         userOption
1340       </a>
1341     </li>
1342
1343
1344
1345
1346
1347
1348
1349     <li class="md-nav__item">
1350       <a href="../package/pip/user-profile-menu/" class="md-nav__link">
1351         userProfileMenu
1352       </a>
1353     </li>
1354
1355
1356
1357         </ul>
1358       </nav>
1359     </li>
1360
1361
1362
1363
1364
1365
1366
1367     <li class="md-nav__item">
1368       <a href="../package/database-php-api/" class="md-nav__link">
1369         Database PHP API
1370       </a>
1371     </li>
1372
1373
1374
1375         </ul>
1376       </nav>
1377     </li>
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389     <li class="md-nav__item md-nav__item--nested">
1390
1391
1392         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" >
1393
1394       <label class="md-nav__link" for="__nav_6">
1395         Migration
1396         <span class="md-nav__icon md-icon"></span>
1397       </label>
1398       <nav class="md-nav" aria-label="Migration" data-md-level="1">
1399         <label class="md-nav__title" for="__nav_6">
1400           <span class="md-nav__icon md-icon"></span>
1401           Migration
1402         </label>
1403         <ul class="md-nav__list" data-md-scrollfix>
1404
1405
1406
1407
1408
1409
1410     <li class="md-nav__item md-nav__item--nested">
1411
1412
1413         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_1" type="checkbox" id="__nav_6_1" >
1414
1415       <label class="md-nav__link" for="__nav_6_1">
1416         Migrating from WSC 5.3
1417         <span class="md-nav__icon md-icon"></span>
1418       </label>
1419       <nav class="md-nav" aria-label="Migrating from WSC 5.3" data-md-level="2">
1420         <label class="md-nav__title" for="__nav_6_1">
1421           <span class="md-nav__icon md-icon"></span>
1422           Migrating from WSC 5.3
1423         </label>
1424         <ul class="md-nav__list" data-md-scrollfix>
1425
1426
1427
1428
1429
1430     <li class="md-nav__item">
1431       <a href="../migration/wsc53/php/" class="md-nav__link">
1432         PHP API
1433       </a>
1434     </li>
1435
1436
1437
1438
1439
1440
1441
1442     <li class="md-nav__item">
1443       <a href="../migration/wsc53/session/" class="md-nav__link">
1444         Session Handling and Authentication
1445       </a>
1446     </li>
1447
1448
1449
1450
1451
1452
1453
1454     <li class="md-nav__item">
1455       <a href="../migration/wsc53/javascript/" class="md-nav__link">
1456         JavaScript
1457       </a>
1458     </li>
1459
1460
1461
1462
1463
1464
1465
1466     <li class="md-nav__item">
1467       <a href="../migration/wsc53/templates/" class="md-nav__link">
1468         Templates
1469       </a>
1470     </li>
1471
1472
1473
1474
1475
1476
1477
1478     <li class="md-nav__item">
1479       <a href="../migration/wsc53/libraries/" class="md-nav__link">
1480         Third Party Libraries
1481       </a>
1482     </li>
1483
1484
1485
1486         </ul>
1487       </nav>
1488     </li>
1489
1490
1491
1492
1493
1494
1495
1496
1497     <li class="md-nav__item md-nav__item--nested">
1498
1499
1500         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_2" type="checkbox" id="__nav_6_2" >
1501
1502       <label class="md-nav__link" for="__nav_6_2">
1503         Migrating from WSC 5.2
1504         <span class="md-nav__icon md-icon"></span>
1505       </label>
1506       <nav class="md-nav" aria-label="Migrating from WSC 5.2" data-md-level="2">
1507         <label class="md-nav__title" for="__nav_6_2">
1508           <span class="md-nav__icon md-icon"></span>
1509           Migrating from WSC 5.2
1510         </label>
1511         <ul class="md-nav__list" data-md-scrollfix>
1512
1513
1514
1515
1516
1517     <li class="md-nav__item">
1518       <a href="../migration/wsc52/php/" class="md-nav__link">
1519         PHP API
1520       </a>
1521     </li>
1522
1523
1524
1525
1526
1527
1528
1529     <li class="md-nav__item">
1530       <a href="../migration/wsc52/templates/" class="md-nav__link">
1531         Templates and Languages
1532       </a>
1533     </li>
1534
1535
1536
1537
1538
1539
1540
1541     <li class="md-nav__item">
1542       <a href="../migration/wsc52/libraries/" class="md-nav__link">
1543         Third Party Libraries
1544       </a>
1545     </li>
1546
1547
1548
1549         </ul>
1550       </nav>
1551     </li>
1552
1553
1554
1555
1556
1557
1558
1559
1560     <li class="md-nav__item md-nav__item--nested">
1561
1562
1563         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_3" type="checkbox" id="__nav_6_3" >
1564
1565       <label class="md-nav__link" for="__nav_6_3">
1566         Migrating from WSC 3.1
1567         <span class="md-nav__icon md-icon"></span>
1568       </label>
1569       <nav class="md-nav" aria-label="Migrating from WSC 3.1" data-md-level="2">
1570         <label class="md-nav__title" for="__nav_6_3">
1571           <span class="md-nav__icon md-icon"></span>
1572           Migrating from WSC 3.1
1573         </label>
1574         <ul class="md-nav__list" data-md-scrollfix>
1575
1576
1577
1578
1579
1580     <li class="md-nav__item">
1581       <a href="../migration/wsc31/php/" class="md-nav__link">
1582         PHP API
1583       </a>
1584     </li>
1585
1586
1587
1588         </ul>
1589       </nav>
1590     </li>
1591
1592
1593
1594
1595
1596
1597
1598
1599     <li class="md-nav__item md-nav__item--nested">
1600
1601
1602         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_4" type="checkbox" id="__nav_6_4" >
1603
1604       <label class="md-nav__link" for="__nav_6_4">
1605         Migrating from WSC 3.0
1606         <span class="md-nav__icon md-icon"></span>
1607       </label>
1608       <nav class="md-nav" aria-label="Migrating from WSC 3.0" data-md-level="2">
1609         <label class="md-nav__title" for="__nav_6_4">
1610           <span class="md-nav__icon md-icon"></span>
1611           Migrating from WSC 3.0
1612         </label>
1613         <ul class="md-nav__list" data-md-scrollfix>
1614
1615
1616
1617
1618
1619     <li class="md-nav__item">
1620       <a href="../migration/wsc30/php/" class="md-nav__link">
1621         PHP API
1622       </a>
1623     </li>
1624
1625
1626
1627
1628
1629
1630
1631     <li class="md-nav__item">
1632       <a href="../migration/wsc30/javascript/" class="md-nav__link">
1633         JavaScript API
1634       </a>
1635     </li>
1636
1637
1638
1639
1640
1641
1642
1643     <li class="md-nav__item">
1644       <a href="../migration/wsc30/templates/" class="md-nav__link">
1645         Templates
1646       </a>
1647     </li>
1648
1649
1650
1651
1652
1653
1654
1655     <li class="md-nav__item">
1656       <a href="../migration/wsc30/css/" class="md-nav__link">
1657         CSS
1658       </a>
1659     </li>
1660
1661
1662
1663
1664
1665
1666
1667     <li class="md-nav__item">
1668       <a href="../migration/wsc30/package/" class="md-nav__link">
1669         Package Components
1670       </a>
1671     </li>
1672
1673
1674
1675         </ul>
1676       </nav>
1677     </li>
1678
1679
1680
1681
1682
1683
1684
1685
1686     <li class="md-nav__item md-nav__item--nested">
1687
1688
1689         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_5" type="checkbox" id="__nav_6_5" >
1690
1691       <label class="md-nav__link" for="__nav_6_5">
1692         Migrating from WCF 2.1
1693         <span class="md-nav__icon md-icon"></span>
1694       </label>
1695       <nav class="md-nav" aria-label="Migrating from WCF 2.1" data-md-level="2">
1696         <label class="md-nav__title" for="__nav_6_5">
1697           <span class="md-nav__icon md-icon"></span>
1698           Migrating from WCF 2.1
1699         </label>
1700         <ul class="md-nav__list" data-md-scrollfix>
1701
1702
1703
1704
1705
1706     <li class="md-nav__item">
1707       <a href="../migration/wcf21/php/" class="md-nav__link">
1708         PHP API
1709       </a>
1710     </li>
1711
1712
1713
1714
1715
1716
1717
1718     <li class="md-nav__item">
1719       <a href="../migration/wcf21/templates/" class="md-nav__link">
1720         Templates
1721       </a>
1722     </li>
1723
1724
1725
1726
1727
1728
1729
1730     <li class="md-nav__item">
1731       <a href="../migration/wcf21/css/" class="md-nav__link">
1732         CSS
1733       </a>
1734     </li>
1735
1736
1737
1738
1739
1740
1741
1742     <li class="md-nav__item">
1743       <a href="../migration/wcf21/package/" class="md-nav__link">
1744         Package Components
1745       </a>
1746     </li>
1747
1748
1749
1750         </ul>
1751       </nav>
1752     </li>
1753
1754
1755
1756         </ul>
1757       </nav>
1758     </li>
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770     <li class="md-nav__item md-nav__item--nested">
1771
1772
1773         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" >
1774
1775       <label class="md-nav__link" for="__nav_7">
1776         Tutorials
1777         <span class="md-nav__icon md-icon"></span>
1778       </label>
1779       <nav class="md-nav" aria-label="Tutorials" data-md-level="1">
1780         <label class="md-nav__title" for="__nav_7">
1781           <span class="md-nav__icon md-icon"></span>
1782           Tutorials
1783         </label>
1784         <ul class="md-nav__list" data-md-scrollfix>
1785
1786
1787
1788
1789
1790
1791     <li class="md-nav__item md-nav__item--nested">
1792
1793
1794         <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_1" type="checkbox" id="__nav_7_1" >
1795
1796       <label class="md-nav__link" for="__nav_7_1">
1797         Tutorial Series
1798         <span class="md-nav__icon md-icon"></span>
1799       </label>
1800       <nav class="md-nav" aria-label="Tutorial Series" data-md-level="2">
1801         <label class="md-nav__title" for="__nav_7_1">
1802           <span class="md-nav__icon md-icon"></span>
1803           Tutorial Series
1804         </label>
1805         <ul class="md-nav__list" data-md-scrollfix>
1806
1807
1808
1809
1810
1811     <li class="md-nav__item">
1812       <a href="../tutorial/series/overview/" class="md-nav__link">
1813         Overview
1814       </a>
1815     </li>
1816
1817
1818
1819
1820
1821
1822
1823     <li class="md-nav__item">
1824       <a href="../tutorial/series/part_1/" class="md-nav__link">
1825         Part 1
1826       </a>
1827     </li>
1828
1829
1830
1831
1832
1833
1834
1835     <li class="md-nav__item">
1836       <a href="../tutorial/series/part_2/" class="md-nav__link">
1837         Part 2
1838       </a>
1839     </li>
1840
1841
1842
1843
1844
1845
1846
1847     <li class="md-nav__item">
1848       <a href="../tutorial/series/part_3/" class="md-nav__link">
1849         Part 3
1850       </a>
1851     </li>
1852
1853
1854
1855         </ul>
1856       </nav>
1857     </li>
1858
1859
1860
1861         </ul>
1862       </nav>
1863     </li>
1864
1865
1866
1867   </ul>
1868 </nav>
1869                   </div>
1870                 </div>
1871               </div>
1872
1873
1874
1875               <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
1876                 <div class="md-sidebar__scrollwrap">
1877                   <div class="md-sidebar__inner">
1878
1879 <nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1880
1881
1882
1883
1884
1885     <label class="md-nav__title" for="__toc">
1886       <span class="md-nav__icon md-icon"></span>
1887       Table of contents
1888     </label>
1889     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1890
1891         <li class="md-nav__item">
1892   <a href="#setup-and-requirements" class="md-nav__link">
1893     Setup and Requirements
1894   </a>
1895
1896 </li>
1897
1898         <li class="md-nav__item">
1899   <a href="#the-packagexml-file" class="md-nav__link">
1900     The package.xml File
1901   </a>
1902
1903 </li>
1904
1905         <li class="md-nav__item">
1906   <a href="#the-php-class" class="md-nav__link">
1907     The PHP Class
1908   </a>
1909
1910 </li>
1911
1912         <li class="md-nav__item">
1913   <a href="#the-template" class="md-nav__link">
1914     The Template
1915   </a>
1916
1917 </li>
1918
1919         <li class="md-nav__item">
1920   <a href="#the-page-definition" class="md-nav__link">
1921     The Page Definition
1922   </a>
1923
1924 </li>
1925
1926         <li class="md-nav__item">
1927   <a href="#building-the-package" class="md-nav__link">
1928     Building the Package
1929   </a>
1930
1931 </li>
1932
1933         <li class="md-nav__item">
1934   <a href="#installation" class="md-nav__link">
1935     Installation
1936   </a>
1937
1938 </li>
1939
1940         <li class="md-nav__item">
1941   <a href="#developer-tools" class="md-nav__link">
1942     Developer Tools
1943   </a>
1944
1945     <nav class="md-nav" aria-label="Developer Tools">
1946       <ul class="md-nav__list">
1947
1948           <li class="md-nav__item">
1949   <a href="#registering-a-project" class="md-nav__link">
1950     Registering a Project
1951   </a>
1952
1953 </li>
1954
1955           <li class="md-nav__item">
1956   <a href="#synchronizing" class="md-nav__link">
1957     Synchronizing
1958   </a>
1959
1960 </li>
1961
1962       </ul>
1963     </nav>
1964
1965 </li>
1966
1967         <li class="md-nav__item">
1968   <a href="#appendix" class="md-nav__link">
1969     Appendix
1970   </a>
1971
1972     <nav class="md-nav" aria-label="Appendix">
1973       <ul class="md-nav__list">
1974
1975           <li class="md-nav__item">
1976   <a href="#template-guessing" class="md-nav__link">
1977     Template Guessing
1978   </a>
1979
1980 </li>
1981
1982       </ul>
1983     </nav>
1984
1985 </li>
1986
1987     </ul>
1988
1989 </nav>
1990                   </div>
1991                 </div>
1992               </div>
1993
1994
1995           <div class="md-content" data-md-component="content">
1996             <article class="md-content__inner md-typeset">
1997
1998
1999                   <a href="https://github.com/WoltLab/docs.woltlab.com/edit/5.4/docs/getting-started.md" title="Edit this page" class="md-content__button md-icon">
2000                     <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>
2001                   </a>
2002
2003
2004                 <h1 id="creating-a-simple-package">Creating a simple package<a class="headerlink" href="#creating-a-simple-package" title="Permanent link">#</a></h1>
2005 <h2 id="setup-and-requirements">Setup and Requirements<a class="headerlink" href="#setup-and-requirements" title="Permanent link">#</a></h2>
2006 <p>This guide will help you to create a simple package that provides a simple test
2007 page. It is nothing too fancy, but you can use it as the foundation for your
2008 next project.</p>
2009 <p>There are some requirements you should met before starting:</p>
2010 <ul>
2011 <li>Text editor with syntax highlighting for PHP, <a href="https://notepad-plus-plus.org/">Notepad++</a> is a solid pick</li>
2012 <li><code>*.php</code> and <code>*.tpl</code> should be encoded with ANSI/ASCII</li>
2013 <li><code>*.xml</code> are always encoded with UTF-8, but omit the BOM (byte-order-mark)</li>
2014 <li>Use tabs instead of spaces to indent lines</li>
2015 <li>It is recommended to set the tab width to <code>8</code> spaces, this is used in the entire software and will ease reading the source files</li>
2016 <li>An active installation of WoltLab Suite 3</li>
2017 <li>An application to create <code>*.tar</code> archives, e.g. <a href="http://www.7-zip.org/">7-Zip</a> on Windows</li>
2018 </ul>
2019 <h2 id="the-packagexml-file">The package.xml File<a class="headerlink" href="#the-packagexml-file" title="Permanent link">#</a></h2>
2020 <p>We want to create a simple page that will display the sentence "Hello World" embedded
2021 into the application frame. Create an empty directory in the workspace of your choice
2022 to start with.</p>
2023 <p>Create a new file called <code>package.xml</code> and insert the code below:</p>
2024 <div class="highlight"><pre><span></span><code><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
2025 <span class="nt">&lt;package</span> <span class="na">xmlns=</span><span class="s">&quot;http://www.woltlab.com&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://www.woltlab.com http://www.woltlab.com/XSD/2019/package.xsd&quot;</span> <span class="na">name=</span><span class="s">&quot;com.example.test&quot;</span><span class="nt">&gt;</span>
2026     <span class="nt">&lt;packageinformation&gt;</span>
2027         <span class="c">&lt;!-- com.example.test --&gt;</span>
2028         <span class="nt">&lt;packagename&gt;</span>Simple Package<span class="nt">&lt;/packagename&gt;</span>
2029         <span class="nt">&lt;packagedescription&gt;</span>A simple package to demonstrate the package system of WoltLab Suite Core<span class="nt">&lt;/packagedescription&gt;</span>
2030         <span class="nt">&lt;version&gt;</span>1.0.0<span class="nt">&lt;/version&gt;</span>
2031         <span class="nt">&lt;date&gt;</span>2019-04-28<span class="nt">&lt;/date&gt;</span>
2032     <span class="nt">&lt;/packageinformation&gt;</span>
2033     <span class="nt">&lt;authorinformation&gt;</span>
2034         <span class="nt">&lt;author&gt;</span>Your Name<span class="nt">&lt;/author&gt;</span>
2035         <span class="nt">&lt;authorurl&gt;</span>http://www.example.com<span class="nt">&lt;/authorurl&gt;</span>
2036     <span class="nt">&lt;/authorinformation&gt;</span>
2037     <span class="nt">&lt;excludedpackages&gt;</span>
2038         <span class="nt">&lt;excludedpackage</span> <span class="na">version=</span><span class="s">&quot;6.0.0 Alpha 1&quot;</span><span class="nt">&gt;</span>com.woltlab.wcf<span class="nt">&lt;/excludedpackage&gt;</span>
2039     <span class="nt">&lt;/excludedpackages&gt;</span>
2040     <span class="nt">&lt;instructions</span> <span class="na">type=</span><span class="s">&quot;install&quot;</span><span class="nt">&gt;</span>
2041         <span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">&quot;file&quot;</span> <span class="nt">/&gt;</span>
2042         <span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">&quot;template&quot;</span> <span class="nt">/&gt;</span>
2043         <span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">&quot;page&quot;</span> <span class="nt">/&gt;</span>
2044     <span class="nt">&lt;/instructions&gt;</span>
2045 <span class="nt">&lt;/package&gt;</span>
2046 </code></pre></div>
2047 <p>There is an <a href="../package/package-xml/">entire chapter</a> on the package system that explains what the code above
2048 does and how you can adjust it to fit your needs. For now we'll keep it as it is.</p>
2049 <h2 id="the-php-class">The PHP Class<a class="headerlink" href="#the-php-class" title="Permanent link">#</a></h2>
2050 <p>The next step is to create the PHP class which will serve our page:</p>
2051 <ol>
2052 <li>Create the directory <code>files</code> in the same directory where <code>package.xml</code> is located</li>
2053 <li>Open <code>files</code> and create the directory <code>lib</code></li>
2054 <li>Open <code>lib</code> and create the directory <code>page</code></li>
2055 <li>Within the directory <code>page</code>, please create the file <code>TestPage.class.php</code></li>
2056 </ol>
2057 <p>Copy and paste the following code into the <code>TestPage.class.php</code>:</p>
2058 <div class="highlight"><pre><span></span><code><span class="o">&lt;?</span><span class="nx">php</span>
2059 <span class="k">namespace</span> <span class="nx">wcf\page</span><span class="p">;</span>
2060 <span class="k">use</span> <span class="nx">wcf\system\WCF</span><span class="p">;</span>
2061
2062 <span class="sd">/**</span>
2063 <span class="sd"> * A simple test page for demonstration purposes.</span>
2064 <span class="sd"> *</span>
2065 <span class="sd"> * @author  YOUR NAME</span>
2066 <span class="sd"> * @license GNU Lesser General Public License &lt;http://opensource.org/licenses/lgpl-license.php&gt;</span>
2067 <span class="sd"> */</span>
2068 <span class="k">class</span> <span class="nc">TestPage</span> <span class="k">extends</span> <span class="nx">AbstractPage</span> <span class="p">{</span>
2069     <span class="sd">/**</span>
2070 <span class="sd">     * @var string</span>
2071 <span class="sd">     */</span>
2072     <span class="k">protected</span> <span class="nv">$greet</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span><span class="p">;</span>
2073
2074     <span class="sd">/**</span>
2075 <span class="sd">     * @inheritDoc</span>
2076 <span class="sd">     */</span>
2077     <span class="k">public</span> <span class="k">function</span> <span class="nf">readParameters</span><span class="p">()</span> <span class="p">{</span>
2078         <span class="k">parent</span><span class="o">::</span><span class="na">readParameters</span><span class="p">();</span>
2079
2080         <span class="k">if</span> <span class="p">(</span><span class="nb">isset</span><span class="p">(</span><span class="nv">$_GET</span><span class="p">[</span><span class="s1">&#39;greet&#39;</span><span class="p">]))</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">greet</span> <span class="o">=</span> <span class="nv">$_GET</span><span class="p">[</span><span class="s1">&#39;greet&#39;</span><span class="p">];</span>
2081     <span class="p">}</span>
2082
2083     <span class="sd">/**</span>
2084 <span class="sd">     * @inheritDoc</span>
2085 <span class="sd">     */</span>
2086     <span class="k">public</span> <span class="k">function</span> <span class="nf">readData</span><span class="p">()</span> <span class="p">{</span>
2087         <span class="k">parent</span><span class="o">::</span><span class="na">readData</span><span class="p">();</span>
2088
2089         <span class="k">if</span> <span class="p">(</span><span class="k">empty</span><span class="p">(</span><span class="nv">$this</span><span class="o">-&gt;</span><span class="na">greet</span><span class="p">))</span> <span class="p">{</span>
2090             <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">greet</span> <span class="o">=</span> <span class="s1">&#39;World&#39;</span><span class="p">;</span>
2091         <span class="p">}</span>
2092     <span class="p">}</span>
2093
2094     <span class="sd">/**</span>
2095 <span class="sd">     * @inheritDoc</span>
2096 <span class="sd">     */</span>
2097     <span class="k">public</span> <span class="k">function</span> <span class="nf">assignVariables</span><span class="p">()</span> <span class="p">{</span>
2098         <span class="k">parent</span><span class="o">::</span><span class="na">assignVariables</span><span class="p">();</span>
2099
2100         <span class="nx">WCF</span><span class="o">::</span><span class="na">getTPL</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">assign</span><span class="p">([</span>
2101             <span class="s1">&#39;greet&#39;</span> <span class="o">=&gt;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">greet</span>
2102         <span class="p">]);</span>
2103     <span class="p">}</span>
2104 <span class="p">}</span>
2105 </code></pre></div>
2106 <p>The class inherits from <a href="https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/page/AbstractPage.class.php">wcf\page\AbstractPage</a>, the default implementation of pages without form controls. It
2107 defines quite a few methods that will be automatically invoked in a specific order, for example <code>readParameters()</code> before <code>readData()</code> and finally <code>assignVariables()</code> to pass arbitrary values to the template.</p>
2108 <p>The property <code>$greet</code> is defined as <code>World</code>, but can optionally be populated through a GET variable (<code>index.php?test/&amp;greet=You</code> would output <code>Hello You!</code>). This extra code illustrates the separation of data
2109 processing that takes place within all sort of pages, where all user-supplied data is read from within a single method. It helps organizing the code, but most of all it enforces a clean class logic that does not
2110 start reading user input at random places, including the risk to only escape the input of variable <code>$_GET['foo']</code> 4 out of 5 times.</p>
2111 <p>Reading and processing the data is only half the story, now we need a template to display the actual content for our page. You don't need to specify it yourself, it will be automatically guessed based on your
2112 namespace and class name, you can <a href="#template-guessing">read more about it later</a>.</p>
2113 <p>Last but not least, you must not include the closing PHP tag <code>?&gt;</code> at the end, it can cause PHP to break on whitespaces and is not required at all.</p>
2114 <h2 id="the-template">The Template<a class="headerlink" href="#the-template" title="Permanent link">#</a></h2>
2115 <p>Navigate back to the root directory of your package until you see both the <code>files</code> directory and the <code>package.xml</code>. Now create a directory called <code>templates</code>, open it and create the file <code>test.tpl</code>.</p>
2116 <div class="highlight"><pre><span></span><code><span class="cp">{</span><span class="nf">include</span> <span class="na">file</span><span class="o">=</span><span class="s1">&#39;header&#39;</span><span class="cp">}</span><span class="x"></span>
2117
2118 <span class="x">&lt;div class=&quot;section&quot;&gt;</span>
2119 <span class="x">    Hello </span><span class="cp">{</span><span class="nv">$greet</span><span class="cp">}</span><span class="x">!</span>
2120 <span class="x">&lt;/div&gt;</span>
2121
2122 <span class="cp">{</span><span class="nf">include</span> <span class="na">file</span><span class="o">=</span><span class="s1">&#39;footer&#39;</span><span class="cp">}</span><span class="x"></span>
2123 </code></pre></div>
2124 <p>Templates are a mixture of HTML and Smarty-like template scripting to overcome the static nature of raw HTML. The above code will display the phrase <code>Hello World!</code> in the application frame, just as any other
2125 page would render. The included templates <code>header</code> and <code>footer</code> are responsible for the majority of the overall page functionality, but offer a whole lot of customization abilities to influence their behavior and appearance.</p>
2126 <h2 id="the-page-definition">The Page Definition<a class="headerlink" href="#the-page-definition" title="Permanent link">#</a></h2>
2127 <p>The package now contains the PHP class and the matching template, but it is still missing the page definition. Please create the file <code>page.xml</code> in your project's root directory, thus on the same level as the <code>package.xml</code>.</p>
2128 <div class="highlight"><pre><span></span><code><span class="cp">&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;</span>
2129 <span class="nt">&lt;data</span> <span class="na">xmlns=</span><span class="s">&quot;http://www.woltlab.com&quot;</span> <span class="na">xmlns:xsi=</span><span class="s">&quot;http://www.w3.org/2001/XMLSchema-instance&quot;</span> <span class="na">xsi:schemaLocation=</span><span class="s">&quot;http://www.woltlab.com http://www.woltlab.com/XSD/2019/page.xsd&quot;</span><span class="nt">&gt;</span>
2130     <span class="nt">&lt;import&gt;</span>
2131         <span class="nt">&lt;page</span> <span class="na">identifier=</span><span class="s">&quot;com.example.test.Test&quot;</span><span class="nt">&gt;</span>
2132             <span class="nt">&lt;controller&gt;</span>wcf\page\TestPage<span class="nt">&lt;/controller&gt;</span>
2133             <span class="nt">&lt;name</span> <span class="na">language=</span><span class="s">&quot;en&quot;</span><span class="nt">&gt;</span>Test Page<span class="nt">&lt;/name&gt;</span>
2134             <span class="nt">&lt;pageType&gt;</span>system<span class="nt">&lt;/pageType&gt;</span>
2135         <span class="nt">&lt;/page&gt;</span>
2136     <span class="nt">&lt;/import&gt;</span>
2137 <span class="nt">&lt;/data&gt;</span>
2138 </code></pre></div>
2139 <p>You can provide a lot more data for a page, including logical nesting and dedicated handler classes for display in menus.</p>
2140 <h2 id="building-the-package">Building the Package<a class="headerlink" href="#building-the-package" title="Permanent link">#</a></h2>
2141 <p>If you have followed the above guidelines carefully, your package directory should now look like this:</p>
2142 <div class="highlight"><pre><span></span><code>├── files
2143 │   └── lib
2144 │       ├── page
2145 │       │   ├── TestPage.class.php
2146 ├── package.xml
2147 ├── page.xml
2148 ├── templates
2149 │   └── test.tpl
2150 </code></pre></div>
2151 <p>Both files and templates are archive-based package components, that deploy their payload using tar archives rather than adding the raw files to the package file. Please create the archive <code>files.tar</code> and add the contents of the <code>files/*</code> directory, but not the directory <code>files/</code> itself. Repeat the same process for the <code>templates</code> directory, but this time with the file name <code>templates.tar</code>. Place both files in the root of your project.</p>
2152 <p>Last but not least, create the package archive <code>com.example.test.tar</code> and add all the files listed below.</p>
2153 <ul>
2154 <li><code>files.tar</code></li>
2155 <li><code>package.xml</code></li>
2156 <li><code>page.xml</code></li>
2157 <li><code>templates.tar</code></li>
2158 </ul>
2159 <p>The archive's filename can be anything you want, all though it is the general convention to use the package name itself for easier recognition.</p>
2160 <h2 id="installation">Installation<a class="headerlink" href="#installation" title="Permanent link">#</a></h2>
2161 <p>Open the Administration Control Panel and navigate to <code>Configuration &gt; Packages &gt; Install Package</code>, click on <code>Upload Package</code> and select the file <code>com.example.test.tar</code> from your disk. Follow the on-screen instructions until it has been successfully installed.</p>
2162 <p>Open a new browser tab and navigate to your newly created page. If WoltLab Suite is installed at <code>https://example.com/wsc/</code>, then the URL should read <code>https://example.com/wsc/index.php?test/</code>.</p>
2163 <p>Congratulations, you have just created your first package!</p>
2164 <h2 id="developer-tools">Developer Tools<a class="headerlink" href="#developer-tools" title="Permanent link">#</a></h2>
2165 <div class="admonition warning">
2166 <p class="admonition-title">This feature is available with WoltLab Suite 3.1 or newer only.</p>
2167 </div>
2168 <p>The developer tools provide an interface to synchronize the data of an installed package with a bare repository on the local disk. You can re-import most PIPs at any time and have the changes applied without crafting a manual update. This process simulates a regular package update with a single PIP only, and resets the cache after the import has been completed.</p>
2169 <h3 id="registering-a-project">Registering a Project<a class="headerlink" href="#registering-a-project" title="Permanent link">#</a></h3>
2170 <p>Projects require the absolute path to the package directory, that is, the directory where it can find the <code>package.xml</code>. It is not required to install an package to register it as a project, but you have to install it in order to work with it. It does not install the package by itself!</p>
2171 <p>There is a special button on the project list that allows for a mass-import of projects based on a search path. Each direct child directory of the provided path will be tested and projects created this way will use the identifier extracted from the <code>package.xml</code>.</p>
2172 <h3 id="synchronizing">Synchronizing<a class="headerlink" href="#synchronizing" title="Permanent link">#</a></h3>
2173 <p>The install instructions in the <code>package.xml</code> are ignored when offering the PIP imports, the detection works entirely based on the default filename for each PIP. On top of that, only PIPs that implement the interface <code>wcf\system\devtools\pip\IIdempotentPackageInstallationPlugin</code> are valid for import, as it indicates that importing the PIP multiple times will have no side-effects and that the result is deterministic regardless of the number of times it has been imported.</p>
2174 <p>Some built-in PIPs, such as <code>sql</code> or <code>script</code>, do not qualify for this step and remain unavailable at all times. However, you can still craft and perform an actual package update to have these PIPs executed.</p>
2175 <h2 id="appendix">Appendix<a class="headerlink" href="#appendix" title="Permanent link">#</a></h2>
2176 <h3 id="template-guessing">Template Guessing<a class="headerlink" href="#template-guessing" title="Permanent link">#</a></h3>
2177 <p>The class name including the namespace is used to automatically determine the path to the template and its name. The example above used the page class name <code>wcf\page\TestPage</code> that is then split into four distinct parts:</p>
2178 <ol>
2179 <li><code>wcf</code>, the internal abbreviation of WoltLab Suite Core (previously known as WoltLab Community Framework)</li>
2180 <li><code>\page\</code> (ignored)</li>
2181 <li><code>Test</code>, the actual name that is used for both the template and the URL</li>
2182 <li><code>Page</code> (page type, ignored)</li>
2183 </ol>
2184 <p>The fragments <code>1.</code> and <code>3.</code> from above are used to construct the path to the template: <code>&lt;installDirOfWSC&gt;/templates/test.tpl</code> (the first letter of <code>Test</code> is being converted to lower-case).</p>
2185
2186
2187
2188
2189 <hr>
2190 <div class="md-source-date">
2191   <small>
2192
2193       Last update: 2021-01-08
2194
2195   </small>
2196 </div>
2197
2198
2199
2200
2201
2202
2203
2204
2205             </article>
2206           </div>
2207         </div>
2208       </main>
2209
2210
2211 <footer class="md-footer">
2212
2213     <nav class="md-footer__inner md-grid" aria-label="Footer">
2214
2215
2216         <a href="../php/pages/" class="md-footer__link md-footer__link--next" rel="next">
2217           <div class="md-footer__title">
2218             <div class="md-ellipsis">
2219               <span class="md-footer__direction">
2220                 Next
2221               </span>
2222               Pages
2223             </div>
2224           </div>
2225           <div class="md-footer__button md-icon">
2226             <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>
2227           </div>
2228         </a>
2229
2230     </nav>
2231
2232   <div class="md-footer-meta md-typeset">
2233     <div class="md-footer-meta__inner md-grid">
2234       <div class="md-footer-copyright">
2235
2236           <div class="md-footer-copyright__highlight">
2237             Copyright © 2020 WoltLab GmbH
2238           </div>
2239
2240         Made with
2241         <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
2242           Material for MkDocs
2243         </a>
2244
2245       </div>
2246       <div class="md-footer-copyright">
2247         <a href="https://www.woltlab.com/legal-notice/">Legal Notice</a>
2248         <a href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
2249 </div>
2250     </div>
2251   </div>
2252 </footer>
2253
2254     </div>
2255     <div class="md-dialog" data-md-component="dialog">
2256       <div class="md-dialog__inner md-typeset"></div>
2257     </div>
2258     <script id="__config" type="application/json">{"base": "..", "features": [], "translations": {"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing"}, "search": "../assets/javascripts/workers/search.fb4a9340.min.js", "version": {"provider": "mike"}}</script>
2259
2260
2261       <script src="../assets/javascripts/bundle.5cf3e710.min.js"></script>
2262
2263
2264   </body>
2265 </html>