[GitHub/WoltLab/woltlab.github.io.git] / 5.3 / getting-started_quick-start.html

<!DOCTYPE html>
<head>
    <meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content=" ">
<title>Creating a simple package | WoltLab Suite 5.3 Documentation</title>

<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/syntax.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,300,600">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/font-awesome.min.css">
<!--<link rel="stylesheet" type="text/css" href="css/bootstrap.min.css">-->
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/modern-business.css">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/lavish-bootstrap.css">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/customstyles.css">
<link rel="stylesheet" href="https://docs.woltlab.com/5.3/css/theme-blue.css?v=3">

<script src="https://docs.woltlab.com/5.3/js/jquery.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/jquery.cookie.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/jquery.navgoco.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/bootstrap.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/anchor.min.js"></script>
<script src="https://docs.woltlab.com/5.3/js/toc.js"></script>
<script src="https://docs.woltlab.com/5.3/js/customscripts.js"></script>

<link rel="shortcut icon" href="https://docs.woltlab.com/5.3/images/favicon.ico">

<link rel="alternate" type="application/rss+xml" title="woltlab.github.io" href="https://docs.woltlab.com/5.3feed.xml">

    <script>
        $(document).ready(function() {
            // Initialize navgoco with default options
            $("#mysidebar").navgoco({
                caretHtml: '',
                accordion: true,
                openClass: 'active', // open
                save: false, // leave false or nav highlighting doesn't work right
                cookie: {
                    name: 'navgoco',
                    expires: false,
                    path: '/'
                },
                slide: {
                    duration: 400,
                    easing: 'swing'
                }
            });

            $("#collapseAll").click(function(e) {
                e.preventDefault();
                $("#mysidebar").navgoco('toggle', false);
            });

            $("#expandAll").click(function(e) {
                e.preventDefault();
                $("#mysidebar").navgoco('toggle', true);
            });

        });

    </script>
    <script>
        $(function () {
            $('[data-toggle="tooltip"]').tooltip()
        })
    </script>
    

</head>
<body>
  <!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top">
    <div class="container topnavlinks">
        <div class="navbar-header">
            <button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
                <span class="sr-only">Toggle navigation</span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
                <span class="icon-bar"></span>
            </button>
            <a class="fa fa-home fa-lg navbar-brand" href="index.html">&nbsp;<span class="projectTitle"> WoltLab Suite 5.3 Documentation</span></a>
        </div>
        <div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
            <ul class="nav navbar-nav navbar-right">
                <!-- entries without drop-downs appear here -->
                
                
                <li><a href="https://www.woltlab.com" target="_blank">woltlab.com</a></li>
                
                
                <li><a href="https://github.com/WoltLab/WCF/" target="_blank">Code on github.com</a></li>
                
                
                <!-- entries with drop-downs appear here -->
                <!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
                
                
                <!--comment out this block if you want to hide search-->
                <li>
                    <!--start search-->
                    <div id="search-demo-container">
                        <input type="text" id="search-input" placeholder="search...">
                        <ul id="results-container"></ul>
                    </div>
                    <script src="https://docs.woltlab.com/5.3/js/jekyll-search.js" type="text/javascript"></script>
                    <script type="text/javascript">
                            SimpleJekyllSearch.init({
                                searchInput: document.getElementById('search-input'),
                                resultsContainer: document.getElementById('results-container'),
                                dataSource: 'https://docs.woltlab.com/5.3/search.json',
                                searchResultTemplate: '<li><a href="{url}" title="Creating a simple package">{title}</a></li>',
                    noResultsText: 'No results found.',
                            limit: 10,
                            fuzzy: true,
                    })
                    </script>
                    <!--end search-->
                </li>
            </ul>
        </div>
        </div>
        <!-- /.container -->
</nav>


  <div class="container">
    <div class="col-lg-12">&nbsp;</div>

    <div class="row">
      <div class="col-md-3">
        

<ul id="mysidebar" class="nav">
    <li class="sidebarTitle">WoltLab Suite 5.3</li>

    
            <li>
                <a href="#">Getting Started</a>
                <ul>
                    
                        
                                <li data-identifier="index"><a href="index.html">Introduction</a></li>
                            
                        
                                <li class="active" data-identifier="getting-started_quick-start"><a href="getting-started_quick-start.html">Quick Start</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">PHP API</a>
                <ul>
                    
                        
                                <li data-identifier="php_pages"><a href="php_pages.html">Pages</a></li>
                            
                        
                                <li data-identifier="php_database-objects"><a href="php_database-objects.html">Database Objects</a></li>
                            
                        
                                <li data-identifier="php_database-access"><a href="php_database-access.html">Database Access</a></li>
                            
                        
                                <li data-identifier="php_exceptions"><a href="php_exceptions.html">Exceptions</a></li>
                            
                        
                            <li class="subfolders">
                                <a href="#">API</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="php_api_caches"><a href="php_api_caches.html">Caches</a></li>
                                        
                                    
                                            <li data-identifier="php_api_comments"><a href="php_api_comments.html">Comments</a></li>
                                        
                                    
                                            <li data-identifier="php_api_cronjobs"><a href="php_api_cronjobs.html">Cronjobs</a></li>
                                        
                                    
                                            <li data-identifier="php_api_events"><a href="php_api_events.html">Events</a></li>
                                        
                                    
                                            <li data-identifier="php_api_form_builder"><a href="php_api_form_builder.html">Form Builder</a></li>
                                        
                                    
                                            <li data-identifier="php_api_package_installation_plugins"><a href="php_api_package_installation_plugins.html">Package Installation Plugins</a></li>
                                        
                                    
                                            <li data-identifier="php_api_user_activity_points"><a href="php_api_user_activity_points.html">User Activity Points</a></li>
                                        
                                    
                                            <li data-identifier="php_api_user_notifications"><a href="php_api_user_notifications.html">User Notifications</a></li>
                                        
                                    
                                            <li data-identifier="php_api_sitemaps"><a href="php_api_sitemaps.html">Sitemaps</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                    
                                <li data-identifier="php_code-style"><a href="php_code-style.html">Code Style</a></li>
                            
                        
                                <li data-identifier="php_apps"><a href="php_apps.html">Apps</a></li>
                            
                        
                                <li data-identifier="php_gdpr"><a href="php_gdpr.html">GDPR</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">Languages, Templates & CSS</a>
                <ul>
                    
                        
                                <li data-identifier="view_languages"><a href="view_languages.html">Languages</a></li>
                            
                        
                                <li data-identifier="view_templates"><a href="view_templates.html">Templates</a></li>
                            
                        
                                <li data-identifier="view_css"><a href="view_css.html">CSS</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">JavaScript API</a>
                <ul>
                    
                        
                                <li data-identifier="javascript_general-usage"><a href="javascript_general-usage.html">General Usage</a></li>
                            
                        
                            <li class="subfolders">
                                <a href="#">New API</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="javascript_new-api_writing-a-module"><a href="javascript_new-api_writing-a-module.html">Writing a module</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_data-structures"><a href="javascript_new-api_data-structures.html">Data Structures</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_core"><a href="javascript_new-api_core.html">Core Functions</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_dom"><a href="javascript_new-api_dom.html">DOM</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_events"><a href="javascript_new-api_events.html">Event Handling</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_ajax"><a href="javascript_new-api_ajax.html">Ajax</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_dialogs"><a href="javascript_new-api_dialogs.html">Dialogs</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_browser"><a href="javascript_new-api_browser.html">Browser and Screen Sizes</a></li>
                                        
                                    
                                            <li data-identifier="javascript_new-api_ui"><a href="javascript_new-api_ui.html">User Interface</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                    
                                <li data-identifier="javascript_legacy-api"><a href="javascript_legacy-api.html">Legacy API</a></li>
                            
                        
                                <li data-identifier="javascript_helper-functions"><a href="javascript_helper-functions.html">Helper Functions</a></li>
                            
                        
                                <li data-identifier="javascript_code-snippets"><a href="javascript_code-snippets.html">Code Snippets</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">Package Components</a>
                <ul>
                    
                        
                                <li data-identifier="package_package-xml"><a href="package_package-xml.html">package.xml</a></li>
                            
                        
                                <li data-identifier="package_pip"><a href="package_pip.html">PIPs</a></li>
                            
                        
                </ul>
            </li>
        
            <li>
                <a href="#">Migration</a>
                <ul>
                    
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WSC 5.2</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wsc-52_php"><a href="migration_wsc-52_php.html">PHP API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-52_templates"><a href="migration_wsc-52_templates.html">Templates and Languages</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-52_libraries"><a href="migration_wsc-52_libraries.html">Third Party Libraries</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WSC 3.1</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wsc-31_php"><a href="migration_wsc-31_php.html">PHP API</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WSC 3.0</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wsc-30_php"><a href="migration_wsc-30_php.html">PHP API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_javascript"><a href="migration_wsc-30_javascript.html">JavaScript API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_templates"><a href="migration_wsc-30_templates.html">Templates</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_css"><a href="migration_wsc-30_css.html">CSS</a></li>
                                        
                                    
                                            <li data-identifier="migration_wsc-30_package"><a href="migration_wsc-30_package.html">Package Components</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                            <li class="subfolders">
                                <a href="#">Migrating from WCF 2.1</a>
                                <ul>
                                    
                                        
                                            <li data-identifier="migration_wcf-21_php"><a href="migration_wcf-21_php.html">PHP API</a></li>
                                        
                                    
                                            <li data-identifier="migration_wcf-21_templates"><a href="migration_wcf-21_templates.html">Templates</a></li>
                                        
                                    
                                            <li data-identifier="migration_wcf-21_css"><a href="migration_wcf-21_css.html">CSS</a></li>
                                        
                                    
                                            <li data-identifier="migration_wcf-21_package"><a href="migration_wcf-21_package.html">Package Components</a></li>
                                        
                                    
                                </ul>
                            </li>
                        
                    
                </ul>
            </li>
        
            <li>
                <a href="#">Tutorials</a>
                <ul>
                    
                        
                                <li data-identifier="tutorial_tutorial-series"><a href="tutorial_tutorial-series.html">Tutorial Series</a></li>
                            
                        
                </ul>
            </li>
        
    
</ul>

<script>
(function() {
    var sidebar = $('#mysidebar');
    var item = sidebar.find('.active');
    if (item.length === 0) {
        var parent = '';
        if (parent) {
            sidebar.find('li[data-identifier="' + parent + '"]').addClass('active');
        }
    }

    sidebar.find(".active").parents('li').toggleClass("active");
})();
</script>

      </div>

      <div class="col-md-9">
        <div class="post-header">
   <h1 class="post-title-main">Creating a simple package</h1>
</div>


<div class="post-content">

   
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
  // Handler for .ready() called.

$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });

/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
  var target = $(this.getAttribute('href'))
    , scroll_target = target.offset().top

  $(window).scrollTop(scroll_target - 10);
  return false
})
  
});
</script>

<div id="toc"></div>

    
  <h2 id="setup-and-requirements">Setup and Requirements</h2>

<p>This guide will help you to create a simple package that provides a simple test
page. It is nothing too fancy, but you can use it as the foundation for your
next project.</p>

<p>There are some requirements you should met before starting:</p>

<ul>
  <li>Text editor with syntax highlighting for PHP, <a href="https://notepad-plus-plus.org/">Notepad++</a> is a solid pick</li>
  <li><code class="language-plaintext highlighter-rouge">*.php</code> and <code class="language-plaintext highlighter-rouge">*.tpl</code> should be encoded with ANSI/ASCII</li>
  <li><code class="language-plaintext highlighter-rouge">*.xml</code> are always encoded with UTF-8, but omit the BOM (byte-order-mark)</li>
  <li>Use tabs instead of spaces to indent lines</li>
  <li>It is recommended to set the tab width to <code class="language-plaintext highlighter-rouge">8</code> spaces, this is used in the entire software and will ease reading the source files</li>
  <li>An active installation of WoltLab Suite 3</li>
  <li>An application to create <code class="language-plaintext highlighter-rouge">*.tar</code> archives, e.g. <a href="http://www.7-zip.org/">7-Zip</a> on Windows</li>
</ul>

<h2 id="the-packagexml-file">The package.xml File</h2>

<p>We want to create a simple page that will display the sentence “Hello World” embedded
into the application frame. Create an empty directory in the workspace of your choice
to start with.</p>

<p>Create a new file called <code class="language-plaintext highlighter-rouge">package.xml</code> and insert the code below:</p>

<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>
<span class="nt">&lt;package</span> <span class="na">xmlns=</span><span class="s">"http://www.woltlab.com"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> <span class="na">xsi:schemaLocation=</span><span class="s">"http://www.woltlab.com http://www.woltlab.com/XSD/2019/package.xsd"</span> <span class="na">name=</span><span class="s">"com.example.test"</span><span class="nt">&gt;</span>
	<span class="nt">&lt;packageinformation&gt;</span>
		<span class="c">&lt;!-- com.example.test --&gt;</span>
		<span class="nt">&lt;packagename&gt;</span>Simple Package<span class="nt">&lt;/packagename&gt;</span>
		<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>
		<span class="nt">&lt;version&gt;</span>1.0.0<span class="nt">&lt;/version&gt;</span>
		<span class="nt">&lt;date&gt;</span>2019-04-28<span class="nt">&lt;/date&gt;</span>
	<span class="nt">&lt;/packageinformation&gt;</span>
	<span class="nt">&lt;authorinformation&gt;</span>
		<span class="nt">&lt;author&gt;</span>Your Name<span class="nt">&lt;/author&gt;</span>
		<span class="nt">&lt;authorurl&gt;</span>http://www.example.com<span class="nt">&lt;/authorurl&gt;</span>
	<span class="nt">&lt;/authorinformation&gt;</span>
	<span class="nt">&lt;excludedpackages&gt;</span>
		<span class="nt">&lt;excludedpackage</span> <span class="na">version=</span><span class="s">"6.0.0 Alpha 1"</span><span class="nt">&gt;</span>com.woltlab.wcf<span class="nt">&lt;/excludedpackage&gt;</span>
	<span class="nt">&lt;/excludedpackages&gt;</span>
	<span class="nt">&lt;instructions</span> <span class="na">type=</span><span class="s">"install"</span><span class="nt">&gt;</span>
		<span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"file"</span> <span class="nt">/&gt;</span>
		<span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"template"</span> <span class="nt">/&gt;</span>
		<span class="nt">&lt;instruction</span> <span class="na">type=</span><span class="s">"page"</span> <span class="nt">/&gt;</span>
	<span class="nt">&lt;/instructions&gt;</span>
<span class="nt">&lt;/package&gt;</span>
</code></pre></div></div>

<p>There is an <a href="package_package-xml.html">entire chapter</a> on the package system that explains what the code above
does and how you can adjust it to fit your needs. For now we’ll keep it as it is.</p>

<h2 id="the-php-class">The PHP Class</h2>

<p>The next step is to create the PHP class which will serve our page:</p>

<ol>
  <li>Create the directory <code class="language-plaintext highlighter-rouge">files</code> in the same directory where <code class="language-plaintext highlighter-rouge">package.xml</code> is located</li>
  <li>Open <code class="language-plaintext highlighter-rouge">files</code> and create the directory <code class="language-plaintext highlighter-rouge">lib</code></li>
  <li>Open <code class="language-plaintext highlighter-rouge">lib</code> and create the directory <code class="language-plaintext highlighter-rouge">page</code></li>
  <li>Within the directory <code class="language-plaintext highlighter-rouge">page</code>, please create the file <code class="language-plaintext highlighter-rouge">TestPage.class.php</code></li>
</ol>

<p>Copy and paste the following code into the <code class="language-plaintext highlighter-rouge">TestPage.class.php</code>:</p>

<div class="language-php highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?php</span>
<span class="kn">namespace</span> <span class="nn">wcf\page</span><span class="p">;</span>
<span class="kn">use</span> <span class="nn">wcf\system\WCF</span><span class="p">;</span>

<span class="cd">/**
 * A simple test page for demonstration purposes.
 *
 * @author	YOUR NAME
 * @license	GNU Lesser General Public License &lt;http://opensource.org/licenses/lgpl-license.php&gt;
 */</span>
<span class="kd">class</span> <span class="nc">TestPage</span> <span class="k">extends</span> <span class="nx">AbstractPage</span> <span class="p">{</span>
	<span class="cd">/**
	 * @var string
	 */</span>
	<span class="k">protected</span> <span class="nv">$greet</span> <span class="o">=</span> <span class="s1">''</span><span class="p">;</span>

	<span class="cd">/**
	 * @inheritDoc
	 */</span>
	<span class="k">public</span> <span class="k">function</span> <span class="nf">readParameters</span><span class="p">()</span> <span class="p">{</span>
		<span class="k">parent</span><span class="o">::</span><span class="na">readParameters</span><span class="p">();</span>

		<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">'greet'</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">'greet'</span><span class="p">];</span>
	<span class="p">}</span>

	<span class="cd">/**
	 * @inheritDoc
	 */</span>
	<span class="k">public</span> <span class="k">function</span> <span class="nf">readData</span><span class="p">()</span> <span class="p">{</span>
		<span class="k">parent</span><span class="o">::</span><span class="na">readData</span><span class="p">();</span>

		<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>
			<span class="nv">$this</span><span class="o">-&gt;</span><span class="na">greet</span> <span class="o">=</span> <span class="s1">'World'</span><span class="p">;</span>
		<span class="p">}</span>
	<span class="p">}</span>

	<span class="cd">/**
	 * @inheritDoc
	 */</span>
	<span class="k">public</span> <span class="k">function</span> <span class="nf">assignVariables</span><span class="p">()</span> <span class="p">{</span>
		<span class="k">parent</span><span class="o">::</span><span class="na">assignVariables</span><span class="p">();</span>

		<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>
			<span class="s1">'greet'</span> <span class="o">=&gt;</span> <span class="nv">$this</span><span class="o">-&gt;</span><span class="na">greet</span>
		<span class="p">]);</span>
	<span class="p">}</span>
<span class="p">}</span>

</code></pre></div></div>

<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
defines quite a few methods that will be automatically invoked in a specific order, for example <code class="language-plaintext highlighter-rouge">readParameters()</code> before <code class="language-plaintext highlighter-rouge">readData()</code> and finally <code class="language-plaintext highlighter-rouge">assignVariables()</code> to pass arbitrary values to the template.</p>

<p>The property <code class="language-plaintext highlighter-rouge">$greet</code> is defined as <code class="language-plaintext highlighter-rouge">World</code>, but can optionally be populated through a GET variable (<code class="language-plaintext highlighter-rouge">index.php?test/&amp;greet=You</code> would output <code class="language-plaintext highlighter-rouge">Hello You!</code>). This extra code illustrates the separation of data
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
start reading user input at random places, including the risk to only escape the input of variable <code class="language-plaintext highlighter-rouge">$_GET['foo']</code> 4 out of 5 times.</p>

<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
namespace and class name, you can <a href="#appendixTemplateGuessing">read more about it later</a>.</p>

<p>Last but not least, you must not include the closing PHP tag <code class="language-plaintext highlighter-rouge">?&gt;</code> at the end, it can cause PHP to break on whitespaces and is not required at all.</p>

<h2 id="the-template">The Template</h2>

<p>Navigate back to the root directory of your package until you see both the <code class="language-plaintext highlighter-rouge">files</code> directory and the <code class="language-plaintext highlighter-rouge">package.xml</code>. Now create a directory called <code class="language-plaintext highlighter-rouge">templates</code>, open it and create the file <code class="language-plaintext highlighter-rouge">test.tpl</code>.</p>

<div class="language-smarty highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">{</span><span class="nb">include</span> <span class="na">file</span><span class="o">=</span><span class="s1">'header'</span><span class="k">}</span>

<span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"section"</span><span class="nt">&gt;</span>
	Hello <span class="k">{</span><span class="nv">$greet</span><span class="k">}</span>!
<span class="nt">&lt;/div&gt;</span>

<span class="k">{</span><span class="nb">include</span> <span class="na">file</span><span class="o">=</span><span class="s1">'footer'</span><span class="k">}</span>
</code></pre></div></div>

<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 class="language-plaintext highlighter-rouge">Hello World!</code> in the application frame, just as any other
page would render. The included templates <code class="language-plaintext highlighter-rouge">header</code> and <code class="language-plaintext highlighter-rouge">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>

<h2 id="the-page-definition">The Page Definition</h2>

<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 class="language-plaintext highlighter-rouge">page.xml</code> in your project’s root directory, thus on the same level as the <code class="language-plaintext highlighter-rouge">package.xml</code>.</p>

<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>
<span class="nt">&lt;data</span> <span class="na">xmlns=</span><span class="s">"http://www.woltlab.com"</span> <span class="na">xmlns:xsi=</span><span class="s">"http://www.w3.org/2001/XMLSchema-instance"</span> <span class="na">xsi:schemaLocation=</span><span class="s">"http://www.woltlab.com http://www.woltlab.com/XSD/2019/page.xsd"</span><span class="nt">&gt;</span>
	<span class="nt">&lt;import&gt;</span>
		<span class="nt">&lt;page</span> <span class="na">identifier=</span><span class="s">"com.example.test.Test"</span><span class="nt">&gt;</span>
			<span class="nt">&lt;controller&gt;</span>wcf\page\TestPage<span class="nt">&lt;/controller&gt;</span>
			<span class="nt">&lt;name</span> <span class="na">language=</span><span class="s">"en"</span><span class="nt">&gt;</span>Test Page<span class="nt">&lt;/name&gt;</span>
			<span class="nt">&lt;pageType&gt;</span>system<span class="nt">&lt;/pageType&gt;</span>
		<span class="nt">&lt;/page&gt;</span>
	<span class="nt">&lt;/import&gt;</span>
<span class="nt">&lt;/data&gt;</span>
</code></pre></div></div>

<p>You can provide a lot more data for a page, including logical nesting and dedicated handler classes for display in menus.</p>

<h2 id="building-the-package">Building the Package</h2>

<p>If you have followed the above guidelines carefully, your package directory should now look like this:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>├── files
│   └── lib
│       ├── page
│       │   ├── TestPage.class.php
├── package.xml
├── page.xml
├── templates
│   └── test.tpl
</code></pre></div></div>

<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 class="language-plaintext highlighter-rouge">files.tar</code> and add the contents of the <code class="language-plaintext highlighter-rouge">files/*</code> directory, but not the directory <code class="language-plaintext highlighter-rouge">files/</code> itself. Repeat the same process for the <code class="language-plaintext highlighter-rouge">templates</code> directory, but this time with the file name <code class="language-plaintext highlighter-rouge">templates.tar</code>. Place both files in the root of your project.</p>

<p>Last but not least, create the package archive <code class="language-plaintext highlighter-rouge">com.example.test.tar</code> and add all the files listed below.</p>

<ul>
  <li><code class="language-plaintext highlighter-rouge">files.tar</code></li>
  <li><code class="language-plaintext highlighter-rouge">package.xml</code></li>
  <li><code class="language-plaintext highlighter-rouge">page.xml</code></li>
  <li><code class="language-plaintext highlighter-rouge">templates.tar</code></li>
</ul>

<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>

<h2 id="installation">Installation</h2>

<p>Open the Administration Control Panel and navigate to <code class="language-plaintext highlighter-rouge">Configuration &gt; Packages &gt; Install Package</code>, click on <code class="language-plaintext highlighter-rouge">Upload Package</code> and select the file <code class="language-plaintext highlighter-rouge">com.example.test.tar</code> from your disk. Follow the on-screen instructions until it has been successfully installed.</p>

<p>Open a new browser tab and navigate to your newly created page. If WoltLab Suite is installed at <code class="language-plaintext highlighter-rouge">https://example.com/wsc/</code>, then the URL should read <code class="language-plaintext highlighter-rouge">https://example.com/wsc/index.php?test/</code>.</p>

<p>Congratulations, you have just created your first package!</p>

<h2 id="developer-tools">Developer Tools</h2>

<div class="bs-callout bs-callout-warning">This feature is available with WoltLab Suite 3.1 or newer only.</div>

<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>

<h3 id="registering-a-project">Registering a Project</h3>

<p>Projects require the absolute path to the package directory, that is, the directory where it can find the <code class="language-plaintext highlighter-rouge">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>

<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 class="language-plaintext highlighter-rouge">package.xml</code>.</p>

<h3 id="synchronizing">Synchronizing</h3>

<p>The install instructions in the <code class="language-plaintext highlighter-rouge">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 class="language-plaintext highlighter-rouge">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>

<p>Some built-in PIPs, such as <code class="language-plaintext highlighter-rouge">sql</code> or <code class="language-plaintext highlighter-rouge">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>

<h2 id="appendix">Appendix</h2>

<h3 id="appendixTemplateGuessing">Template Guessing</h3>

<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 class="language-plaintext highlighter-rouge">wcf\page\TestPage</code> that is then split into four distinct parts:</p>

<ol>
  <li><code class="language-plaintext highlighter-rouge">wcf</code>, the internal abbreviation of WoltLab Suite Core (previously known as WoltLab Community Framework)</li>
  <li><code class="language-plaintext highlighter-rouge">\page\</code> (ignored)</li>
  <li><code class="language-plaintext highlighter-rouge">Test</code>, the actual name that is used for both the template and the URL</li>
  <li><code class="language-plaintext highlighter-rouge">Page</code> (page type, ignored)</li>
</ol>

<p>The fragments <code class="language-plaintext highlighter-rouge">1.</code> and <code class="language-plaintext highlighter-rouge">3.</code> from above are used to construct the path to the template: <code class="language-plaintext highlighter-rouge">&lt;installDirOfWSC&gt;/templates/test.tpl</code> (the first letter of <code class="language-plaintext highlighter-rouge">Test</code> is being converted to lower-case).</p>


    <div class="tags">
        
    </div>

    
</div>

      </div>
    </div>
  </div>

  <div class="footerBox">
    <div class="container">
      <div class="footerBoxLeft">
        
        <a target="_blank" href="https://github.com/woltlab/woltlab.github.io/blob/master/pages/getting-started/getting-started_quick-start.md" class="btn btn-default githubEditButton no_icon" role="button"><i class="fa fa-github fa-lg"></i> Edit on GitHub</a>
        <p>Site last generated: Mar 5, 2021</p>
      </div>
      <div class="footerBoxRight">
        <a class="no_icon" href="https://www.woltlab.com"><img src="https://docs.woltlab.com/5.3/images/woltlab-black.png" srcset="https://docs.woltlab.com/5.3/images/woltlab-black@2x.png 2x" height="40" width="204" alt=""></a>
      </div>
    </div>
  </div>

  <div class="pageFooter">
    <div class="container">
      &copy; 2001 ‐ 2021 <a class="no_icon" href="https://www.woltlab.com">WoltLab GmbH</a>. All rights reserved. | <a class="no_icon" href="https://www.woltlab.com/legal-notice/">Legal Notice</a> | <a class="no_icon" href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
    </div>
  </div>
</body>

</html>