WSC 3.0 — Package Installation Plugins

  • With WCF 2.2, we will make it more convenient for developers to use package installation plugins.



    Default Package Installation Plugin Filenames


    When writing the instructions to install or update packages, most of the time, you entered the same information twice: naming the package installation plugin and giving a filename with essentially the same name:


    XML: package.xml
    <instructions type="install">
    <instruction type="acpMenu">acpMenu.xml</instruction>
    <instruction type="userGroupOption">userGroupOption.xml</instruction>
    <instruction type="template">templates.tar</instruction>
    <instruction type="file">files.tar</instruction>
    <instruction type="language">language/*.xml</instruction>
    <instruction type="sql">install.sql</instruction>
    </instructions>


    Now with 2.2, the code with the same result is just


    XML: package.xml
    <instructions type="install">
    <instruction type="acpMenu" />
    <instruction type="userGroupOption" />
    <instruction type="template" />
    <instruction type="file" />
    <instruction type="language" />
    <instruction type="sql" />
    </instructions>


    Package installation plugins can now define a default filename which will be used in case the package author did not specify one themselves. By default, the following rules apply:


    For a XML-based package installation plugin called wcf\system\package\plugin\FooBarPackageInstallationPlugin, the default filename is fooBar.xml. Essentially, the PackageInstallationPlugin is removed from the unqualified class name and the first letter is in lower case now.


    Please note that some XML-based package installation plugins overwrite this default implementation, like wcf\system\package\plugin\ACPMenuPackageInstallationPlugin returning acpMenu.xml instead of aCPMenu.xml and wcf\system\package\plugin\LanguagePackageInstallationPlugin returning language/*xml.


    For file-based package installation plugins like to install ACP templates, files and templates, s.tar is appended to the lower case PIP name.


    The default filename for the sql package installation plugin is install.sql.


    In general, the default filenames match the naming convention WoltLab and most developers already use and regardless of these default values, you still can (and in some cases have to) use different filenames.



    Cronjob Package Installation Plugin


    Cronjobs can now be installed with <options>…</options> given. This element behaves like the option elements for page menu items or for user group options: At least one option has to be "set", otherwise the cronjob will not be executed.


    Furthermore, cronjobs now support a name attribute which will be used to identify cronjobs to update or uninstall them. In order to add a name to an existing cronjob, you need to uninstall the existing cronjob first and then install it again with the name given.



    Event Listener Package Installation Plugin


    The event listener package installation plugin got the same updates as the cronjob package installation plugin. Furthermore, you can now also specify permissions required for the active user so that the event listener is only executed if the active user has at least one of the given permissions.


    Very often, especially when adding new input fields on a form, you need to listen to different events of the same class using the same event listener class. Prior to WCF 2.2, you needed to create an event listener for each event separately, now you can concatenate multiple event names by commas:


    XML: eventListener.xml
    <eventlistener name="myEventListener">
    <eventclassname>wcf\form\RegisterForm</eventclassname>
    <eventname>assignVariables,readFormParameters,saved</eventname>
    <listenerclassname>wcf\system\event\listener\MyRegisterFormListener</listenerclassname>
    <environment>user</environment>
    </eventlistener>


    This event listener now listens to the assignVariables, readFormParameters and the saved event.



    Template Listener Package Installation Plugin


    Like event listeners, template listeners now also support <options>…</options> and <permissions>…</permissions>. Please note that due to the way template listeners internally work, specifying these elements will create an if condition around the template listener code when the template listener code is inserted into the template. If a permission user.foo.canBar should be required, the code inserted into the template will essentially look like this:


    Code
    {if $__wcf->session->getPermission('user.foo.canBar')}
    // template listener code
    {/if}
  • Hello,


    a way to install different files for diferent frameworks would be great. Until now you need to create different packages for Each Framework (e.g. plugin V1.0.0 vor WCF 2.0 and plugin V1.1.0 for WCF2.1).


    It would be easier if you can write the instructions like that.


    XML
    <instructions type="install" framework="2.1">
    <instruction type="acpMenu">acpMenu.xml</instruction>
    <instruction type="userGroupOption">userGroupOption.xml</instruction>
    <instruction type="template">templates.tar</instruction>
    <instruction type="file">files.tar</instruction>
    <instruction type="language">language/*.xml</instruction>
    <instruction type="sql">install.sql</instruction>
    </instructions>
    XML
    <instructions type="install" framework="2.2">
    <instruction type="acpMenu">acpMenu.xml</instruction>
    <instruction type="userGroupOption">userGroupOption.xml</instruction>
    <instruction type="template">templates_2.tar</instruction>
    <instruction type="file">files_2.tar</instruction>
    <instruction type="language">language/*.xml</instruction>
    <instruction type="sql">install_2.sql</instruction>
    </instructions>


    It`s sometimes complicated to decribe the different between version 1.0.0 and 1.1.0. And in addition not all developers use this logic.

  • Another nice feature would be the possiblity to set an directory name for XML-PIPs. Some developers use to store them in a folder like xml/ to keep the root directory clean.

    XML
    <instructions type="install" xmlDir="xml">
    <instruction type="acpMenu" />
    <instruction type="userGroupOption" />
    <instruction type="template" />
    <instruction type="file" />
    <instruction type="language" />
    <instruction type="sql" />
    </instructions>
  • @MysteryCode: This are my known combinations of directories and files:


    Files

    option.xml
    package.xml
    templatelistener.xml
    templateListener.xml
    eventlistener.xml
    eventListener.xml
    install.sql
    update.sql


    Directories

    \acptemplates
    \files
    \files_wcf
    \templates
    \language
    \languages
    \optionals
    \requirements
    \required
    \xml

  • a way to install different files for diferent frameworks would be great. Until now you need to create different packages for Each Framework (e.g. plugin V1.0.0 vor WCF 2.0 and plugin V1.1.0 for WCF2.1).

    I can understand the motivation behind this, but this is never going to happen for various reasons. First of all this creates some great opportunities for incorrect mixing of files, second it will overcomplicate the package structure/contents and last it entirely ignored all other possible settings defined through the package.xml (excludedpackages, requirements, etc.).

    Another nice feature would be the possiblity to set an directory name for XML-PIPs. Some developers use to store them in a folder like xml/ to keep the root directory clean.

    You can still specify custom filepaths, the short-hand syntax is just a convenient way to deploy files using the recommended archive structure (and yes, I clearly understood what you actually asked for).

    Alexander Ebert
    Senior Developer WoltLab® GmbH