Installations-Wizard für dein Modul

Benötigt dein Modul einige Einstellungen, die direkt nach der Installation ausgeführt werden müssen, hast du die Möglichkeit, über die Installationswizard API, dem Benutzer einen Schritt-für-Schritt Einstellungsassistenten zur Verfügung zu stellen.

Die Installationswizard API besteht hierfür aus zwei Teilbereichen, einen Wizard und einzelne Steps. Zuerst musst du hierfür einen Installationswizard registrieren welcher die einzelnen Schritte mitliefert.

Installations-Wizard `QUI\InstallationWizard\AbstractInstallationWizard`

Dein eigener Installations-Wizard muss eine Klasse in deinem Modul sein, welche wiederum das QUI\InstallationWizard\InstallationWizardInterface implementiert.

Am einfachsten ist es, wenn du direkt von QUI\InstallationWizard\AbstractInstallationWizard. Da diese Klasse alle grundlegenden Methoden schon implementiert.

Ein Beispiel eines Wizards:

<?php

namespace QUI\InstallationWizard;

use QUI;

/**
 * Class QuiqqerProvider
 */
class QuiqqerProvider extends AbstractInstallationWizard
{
    /**
     * @param null $Locale
     * @return string
     */
    public function getTitle($Locale = null): string
    {
        if ($Locale === null) {
            $Locale = QUI::getLocale();
        }
        
        // deine locale
        return $Locale->get('quiqqer/quiqqer', 'set.up.title');
    }

    /**
     * @param null $Locale
     * @return string
     */
    public function getDescription($Locale = null): string
    {
        if ($Locale === null) {
            $Locale = QUI::getLocale();
        }

        // deine locale
        return $Locale->get('quiqqer/quiqqer', 'set.up.description');
    }

    /**
     * @return int
     */
    public function getPriority(): int
    {
        return 1;
    }

    /**
     * @return QuiqqerSteps\Welcome[]
     */
    public function getSteps(): array
    {
        // deine steps
        return [
        ];
    }

    /**
     * @param array $data
     */
    public function execute(array $data = []): void
    {
        // deine locale
    }
}

Registrierung des Wizards

Damit dein Wizard vom System erkannt wird, musst du diesen in der package.xml als Provider registrieren.

<quiqqer>
    <package>
        <provider>
            <installationWizard src="\Dein\Namespace\DeinWizard"/>
        </provider>
    </package>
</quiqqer>

Steps

Damit dein Wizard natürlich über deine einzelnen Einrichtungsschritte verfügt, musst du für jeden Step eine eigene Klasse erstellen. Deine Step-Klasse muss von QUI\InstallationWizard\AbstractInstallationWizardStep erben, dadurch wird diese automatisch zu einem QUI Control und kann somit als HTML und JavaScript Control verwendet werden.

Beispiel eines Steps:

<?php

namespace QUI\InstallationWizard\QuiqqerSteps;

use QUI;

/**
 * Class Welcome
 */
class Welcome extends QUI\InstallationWizard\AbstractInstallationWizardStep
{
    /**
     * @param null $Locale
     * @return string
     */
    public function getTitle($Locale = null): string
    {
        if ($Locale === null) {
            $Locale = QUI::getLocale();
        }

        return $Locale->get('quiqqer/quiqqer', 'quiqqer.setup.welcome.title');
    }

    /**
     * @param null $Locale
     * @return string
     */
    public function getDescription($Locale = null): string
    {
        if ($Locale === null) {
            $Locale = QUI::getLocale();
        }

        return $Locale->get('quiqqer/quiqqer', 'quiqqer.setup.welcome.description');
    }

    /**
     * @return string
     */
    public function create(): string
    {
        return '<b>html</b>';
    }
}

Step mit JavaScript Control

<?php

namespace QUI\InstallationWizard\QuiqqerSteps;

use QUI;

/**
 * Class Welcome
 */
class Country extends QUI\InstallationWizard\AbstractInstallationWizardStep
{
    /**
     * @param array $attributes
     */
    public function __construct($attributes = [])
    {
        parent::__construct($attributes);
        $this->setJavaScriptControl('controls/installation/Country');
    }

    /**
     * @param null $Locale
     * @return string
     */
    public function getTitle($Locale = null): string
    {
        if ($Locale === null) {
            $Locale = QUI::getLocale();
        }

        return $Locale->get('quiqqer/quiqqer', 'quiqqer.setup.country.title');
    }

    /**
     * @param null $Locale
     * @return string
     */
    public function getDescription($Locale = null): string
    {
        if ($Locale === null) {
            $Locale = QUI::getLocale();
        }

        return $Locale->get('quiqqer/quiqqer', 'quiqqer.setup.country.description');
    }

    /**
     * @return string
     */
    public function create(): string
    {
        try {
            $Engine = QUI::getTemplateManager()->getEngine();
        } catch (QUI\Exception $Exception) {
            return '';
        }

        $Engine->assign([
            'urlImageDir' => URL_OPT_DIR.'quiqqer/quiqqer/bin/images/installation/'
        ]);

        return $Engine->fetch(dirname(__FILE__).'/Country.html');
    }
}

JavaScript Control Handling

Wenn dein Installations-Step einige Daten prüfen und der Benutzer nicht automatisch weiter machen sollen, hast du über JavaScript die Möglichkeit erst nach bestimmten Ereignissen das Weitermachen zu erlauben.

Hierzu musst du deinem Step Control ein JavaScript Control zuweisen, damit dieses ausgeführt wird (siehe oben). Über dein JavaScript Control hast du dann die Möglichkeit auf das Handling des Wizards einzugehen.

Beispiel eines JavaScript Step Controls


/**
 * @module controls/installation/Cron
 * @author www.pcsg.de (Henning Leutz)
 */
define('controls/installation/Cron', [

    'qui/QUI',
    'qui/controls/Control',
    'Ajax',
    'Locale',

    'css!controls/installation/Cron.css'

], function (QUI, QUIControl, QUIAjax, QUILocale) {
    "use strict";

    let MY_FLAG = null;

    return new Class({

        Extends: QUIControl,
        Type   : 'controls/installation/Cron',

        Binds: [
            '$onImport',
        ],

        initialize: function (options) {
            this.parent(options);

            this.addEvents({
                onImport: this.$onImport
            });
        },

        $onImport: function () {
            // execute if control is 
        },

        next: function () {
            if (MY_FLAG === true) {
                // return true = nutzer kann weiter machen
                return true;
            }

            // return false = nutzer kann nicht weiter machen
            return false;
        }
    });
});

setup wizard