docs/getting-started.md

   1 # Creating a simple package
   2
   3 ## Setup and Requirements
   4
   5 This guide will help you to create a simple package that provides a simple test
   6 page. It is nothing too fancy, but you can use it as the foundation for your
   7 next project.
   8
   9 There are some requirements you should met before starting:
  10
  11 - Text editor with syntax highlighting for PHP, [Notepad++](https://notepad-plus-plus.org/) is a solid pick
  12  - `*.php` and `*.tpl` should be encoded with ANSI/ASCII
  13  - `*.xml` are always encoded with UTF-8, but omit the BOM (byte-order-mark)
  14  - Use tabs instead of spaces to indent lines
  15  - It is recommended to set the tab width to `8` spaces, this is used in the entire software and will ease reading the source files
  16 - An active installation of WoltLab Suite 3
  17 - An application to create `*.tar` archives, e.g. [7-Zip](http://www.7-zip.org/) on Windows
  18
  19 ## The package.xml File
  20
  21 We want to create a simple page that will display the sentence "Hello World" embedded
  22 into the application frame. Create an empty directory in the workspace of your choice
  23 to start with.
  24
  25 Create a new file called `package.xml` and insert the code below:
  26
  27 ```xml
  28 <?xml version="1.0" encoding="UTF-8"?>
  29 <package xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/2019/package.xsd" name="com.example.test">
  30         <packageinformation>
  31                 <!-- com.example.test -->
  32                 <packagename>Simple Package</packagename>
  33                 <packagedescription>A simple package to demonstrate the package system of WoltLab Suite Core</packagedescription>
  34                 <version>1.0.0</version>
  35                 <date>2019-04-28</date>
  36         </packageinformation>
  37         <authorinformation>
  38                 <author>Your Name</author>
  39                 <authorurl>http://www.example.com</authorurl>
  40         </authorinformation>
  41         <excludedpackages>
  42                 <excludedpackage version="6.0.0 Alpha 1">com.woltlab.wcf</excludedpackage>
  43         </excludedpackages>
  44         <instructions type="install">
  45                 <instruction type="file" />
  46                 <instruction type="template" />
  47                 <instruction type="page" />
  48         </instructions>
  49 </package>
  50 ```
  51
  52 There is an [entire chapter](package/package-xml.md) on the package system that explains what the code above
  53 does and how you can adjust it to fit your needs. For now we'll keep it as it is.
  54
  55 ## The PHP Class
  56
  57 The next step is to create the PHP class which will serve our page:
  58
  59 1. Create the directory `files` in the same directory where `package.xml` is located
  60 2. Open `files` and create the directory `lib`
  61 3. Open `lib` and create the directory `page`
  62 4. Within the directory `page`, please create the file `TestPage.class.php`
  63
  64 Copy and paste the following code into the `TestPage.class.php`:
  65
  66 ```php
  67 <?php
  68 namespace wcf\page;
  69 use wcf\system\WCF;
  70
  71 /**
  72  * A simple test page for demonstration purposes.
  73  *
  74  * @author      YOUR NAME
  75  * @license     GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
  76  */
  77 class TestPage extends AbstractPage {
  78         /**
  79          * @var string
  80          */
  81         protected $greet = '';
  82
  83         /**
  84          * @inheritDoc
  85          */
  86         public function readParameters() {
  87                 parent::readParameters();
  88
  89                 if (isset($_GET['greet'])) $this->greet = $_GET['greet'];
  90         }
  91
  92         /**
  93          * @inheritDoc
  94          */
  95         public function readData() {
  96                 parent::readData();
  97
  98                 if (empty($this->greet)) {
  99                         $this->greet = 'World';
 100                 }
 101         }
 102
 103         /**
 104          * @inheritDoc
 105          */
 106         public function assignVariables() {
 107                 parent::assignVariables();
 108
 109                 WCF::getTPL()->assign([
 110                         'greet' => $this->greet
 111                 ]);
 112         }
 113 }
 114
 115 ```
 116
 117 The class inherits from [wcf\page\AbstractPage](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/page/AbstractPage.class.php), the default implementation of pages without form controls. It
 118 defines quite a few methods that will be automatically invoked in a specific order, for example `readParameters()` before `readData()` and finally `assignVariables()` to pass arbitrary values to the template.
 119
 120 The property `$greet` is defined as `World`, but can optionally be populated through a GET variable (`index.php?test/&greet=You` would output `Hello You!`). This extra code illustrates the separation of data
 121 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
 122 start reading user input at random places, including the risk to only escape the input of variable `$_GET['foo']` 4 out of 5 times.
 123
 124 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
 125 namespace and class name, you can [read more about it later](#template-guessing).
 126
 127 Last but not least, you must not include the closing PHP tag `?>` at the end, it can cause PHP to break on whitespaces and is not required at all.
 128
 129 ## The Template
 130
 131 Navigate back to the root directory of your package until you see both the `files` directory and the `package.xml`. Now create a directory called `templates`, open it and create the file `test.tpl`.
 132
 133 ```smarty
 134 {include file='header'}
 135
 136 <div class="section">
 137         Hello {$greet}!
 138 </div>
 139
 140 {include file='footer'}
 141 ```
 142
 143 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 `Hello World!` in the application frame, just as any other
 144 page would render. The included templates `header` and `footer` are responsible for the majority of the overall page functionality, but offer a whole lot of customization abilities to influence their behavior and appearance.
 145
 146 ## The Page Definition
 147
 148 The package now contains the PHP class and the matching template, but it is still missing the page definition. Please create the file `page.xml` in your project's root directory, thus on the same level as the `package.xml`.
 149
 150 ```xml
 151 <?xml version="1.0" encoding="UTF-8"?>
 152 <data xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/2019/page.xsd">
 153         <import>
 154                 <page identifier="com.example.test.Test">
 155                         <controller>wcf\page\TestPage</controller>
 156                         <name language="en">Test Page</name>
 157                         <pageType>system</pageType>
 158                 </page>
 159         </import>
 160 </data>
 161 ```
 162
 163 You can provide a lot more data for a page, including logical nesting and dedicated handler classes for display in menus.
 164
 165 ## Building the Package
 166
 167 If you have followed the above guidelines carefully, your package directory should now look like this:
 168
 169 ```
 170 ├── files
 171 │   └── lib
 172 │       ├── page
 173 │       │   ├── TestPage.class.php
 174 ├── package.xml
 175 ├── page.xml
 176 ├── templates
 177 │   └── test.tpl
 178 ```
 179
 180 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 `files.tar` and add the contents of the `files/*` directory, but not the directory `files/` itself. Repeat the same process for the `templates` directory, but this time with the file name `templates.tar`. Place both files in the root of your project.
 181
 182 Last but not least, create the package archive `com.example.test.tar` and add all the files listed below.
 183
 184 - `files.tar`
 185 - `package.xml`
 186 - `page.xml`
 187 - `templates.tar`
 188
 189 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.
 190
 191 ## Installation
 192
 193 Open the Administration Control Panel and navigate to `Configuration > Packages > Install Package`, click on `Upload Package` and select the file `com.example.test.tar` from your disk. Follow the on-screen instructions until it has been successfully installed.
 194
 195 Open a new browser tab and navigate to your newly created page. If WoltLab Suite is installed at `https://example.com/wsc/`, then the URL should read `https://example.com/wsc/index.php?test/`.
 196
 197 Congratulations, you have just created your first package!
 198
 199 ## Developer Tools
 200
 201 !!! warning "This feature is available with WoltLab Suite 3.1 or newer only."
 202
 203 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.
 204
 205 ### Registering a Project
 206
 207 Projects require the absolute path to the package directory, that is, the directory where it can find the `package.xml`. 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!
 208
 209 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 `package.xml`.
 210
 211 ### Synchronizing
 212
 213 The install instructions in the `package.xml` 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 `wcf\system\devtools\pip\IIdempotentPackageInstallationPlugin` 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.
 214
 215 Some built-in PIPs, such as `sql` or `script`, 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.
 216
 217 ## Appendix
 218
 219 ### Template Guessing
 220
 221 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 `wcf\page\TestPage` that is then split into four distinct parts:
 222
 223 1. `wcf`, the internal abbreviation of WoltLab Suite Core (previously known as WoltLab Community Framework)
 224 2. `\page\` (ignored)
 225 3. `Test`, the actual name that is used for both the template and the URL
 226 4. `Page` (page type, ignored)
 227
 228 The fragments `1.` and `3.` from above are used to construct the path to the template: `<installDirOfWSC>/templates/test.tpl` (the first letter of `Test` is being converted to lower-case).