Raccourcis : Contenu - rubriques - sous rubriques
EN FR

Une application, "installWizard", est fournie avec Jelix. Elle permet de créer un assistant, pour installer une application Jelix aisément, avec un navigateur. Il pourrait être très utile pour distribuer une application publique. Comme par exemple, un forum...

Un assistant contient quelques pages. Une liste de pages à exécuter, leur paramètres, et l'ordre dans lequel les exécuter, est indiqué dans un fichier ini.

InstallWizard contient quelque pages prêtes à l'emploi, mais bien sûr vous pouvez créer vos propres pages. Vous pouvez aussi redéfinir des templates des pages existantes, et redéfinir les fichiers contenant les locales (qui ne sont pas exactement les mêmes fichiers locales de jelix).

Notez que "InstallWizard" n'est pas une application Jelix.

Configuration d'un assistant

En premier lieu, copier ces fichiers:

  • Le lanceur, à appeler depuis le navigateur: lib/installwizard/install.php.dist en www/install.php
  • Le fichier de configuration: lib/installwizard/wizard.ini.php.dist en install/wizard.ini.php

Le wizard est en théorie utilisable pour les applis non Jelix, et dans ce cas, vous n'avez rien à changer dans le install.php. Pour installer une application jelix par contre, il faut dé-commenter certaines lignes.

Configuration globale

Dans la configuration, vous devez définir ces propriétés globales:

  • pagesPath : devrait contenir la liste des répertoires où installWizard trouvera les pages. Le chemin doit être relatif au fichier ini. Par défaut, c'est "../../lib/installwizard/pages/,pages/", donc le répertoire pages/ dans installwizard, et le répertoire pages/ dans votre application (donc install/pages/, si vous fournissez vos propres pages d'assistant).
  • tempPath : le chemin vers le répertoire où sont stockés les fichiers temporaires.
  • customPath : le chemin où les fichiers personnalisés sont stockées, relatifs au fichier du fichier ini.
  • supportedLang : la liste des code langue (sans le code pays), supporté par votre assistant. Bien sûr, vous devriez fournir tous les fichiers des locales pour les langues indiquées. InstallWizard devinera la langue de l'utilisateur et utilisera l'une d'elles.
  • start : le nom de la première page à afficher.
  • onalreadydone = le nom de la page à afficher quand l'application est déjà installée. Par défaut, c'est la même page que la dernière page de l'assistant.
  • appname : le nom de votre assistant, pour votre application. Il sera utilisé dans les templates.

Vous devez aussi créer des sections ini, une par page que vous voulez afficher.

Liste des pages

Chaque page de l'assistant est déclarée dans une section. Le nom de la section est le nom de la page suivie par .step.

Dans chaque section, vous devez indiquer au moins une propriété: next (excepté pour la dernière page de l'assistant). next doit contenir le nom de la page à afficher quand l'utilisateur clique sur le bouton "suivant". S'il n'est pas donné, l'assistant arrêtera sur la page actuelle.

next peut aussi contenir un tableau de page. Certaines page peuvent offrir la possibilité d'afficher une page spécifique ou une autre, dépendant de l'action de l'utilisateur. La page retourne un code numérique, et elle devrait correspondre à une page. Par défault, elle retourne toujours 0.


[apage.step]
next[0] = foo
next[1] = bar
next[2] = bla

Si le code de résultat est 0, alors l'assistant affichera la page "foo", si c'est égale à 1, il affichera la page "bar" etc.

Autres propriétés communes à paramétrer :

  • noprevious=on: indique que, quand la page est affichée, il n'y a pas de bouton "précédant", ce qui signifie que l'utilisateur ne peut pas revenir en arrière (parce que cela n'aurait pas de sens par exemple).
  • messageHeader et messageFooter: la clé locale de quelque texte pour ajouter en haut ou en bas de la page. Utile pour ajouter du contenu sans modifier le code source d'une page existante.

Vous avez certainement d'autres propriétés à ajouter, en fonction de la page. Vous devriez vous référer à la documentation de la page pour les connaître.

Exemple d'assistant basique

Voici un exemple d'assistant basique pour installer une application Jelix :


pagesPath = "../../lib/installwizard/pages/,pages/"
customPath = "custom/"
tempPath = "../temp/"

start = welcome
supportedLang = en

appname= My super application

[welcome.step]
next=checkjelix

[installapp.step]
next=end

[checkjelix.step]
next=dbprofile
databases=mysql,pgsql

[dbprofile.step]
next=installapp
availabledDrivers = mysql,pgsql

[end.step]
noprevious = on

Dans cet exemple, l'assistant affiche d'abord la page "welcome" (parceque start=welcome). Ensuite il affiche "checkjelix", "dbprofile", "installapp" et enfin la page "end". Toutes ces pages sont déjà fournies dans installWizard.

Qu'est-ce qu'une page d'assistant ?

Chaque page de l'assistante sont mises en oeuvre ou décrites en plusieurs fichiers:

  • une classe, dans laquelle l'affichage et le processus d'un formulaire optionel sont mis en oeuvre
  • un template, utilisé pour afficher la page
  • un fichier locale, dans lequel est stocké, en PHP, une chaine traduite. Ceci devrait être dans un fichier locale pour chaque langue. Il devrait avoir au moins un fichier locale pour la langue anglaise.

fichiers

Les fichiers de page sont stockées dans le même répertoire, et une page est identifiée par son nom. Par exemple, si le nom de la page est "welcome":

  • le répertoire pour la page est nommé welcome/.
  • welcome/welcome.page.php est le fichier qui met en oeuvre la classe de la page.
  • welcomeWizPage devrait être le nom de la classe.
  • welcome/welcome.tpl est le template
  • welcome/welcome.en.php est le fichier de locale pour l'anglais, welcome.fr.php pour le français etc.

La Classe

La class devra héritée de installWizardPage et implémentée deux méthodes: show() et process().

La méthode show() dans la classe devra préparer le template. Elle reçoit un objet jTpl comme argument. Elle devra affecter les valeurs si nécessaire. Par exemple, si le template contient des éléments d'un formulaire, la méthode show() pourra initialiser ses valeurs, ou afficher les erreur quand la soumission du formulaire échoue. Il devra retourner true si l'assistant peut continuer après cette page.

La méthode process() est appelée quand un utilisateur appuye sur le bouton "suivant" (qui est en fait un bouton submit), et avant de rediriger à la page suivante. Dans la méthode process(), vous pourrez retourner les valueur du formulaire (avec $_POST). Il doit retourner false si l'assistant doit réafficher la page, ou un entier (typiquement 0), qui est en fait l'index de la page "suivante" indiquée dans le fichier ini.

Templates

Un fichier template doit contenir seulement un fragment de HTML, lequel sera inséré dans un template principal fourni par installWizard. Donc vous ne devriez pas inclure les éléments <head>, <body>, par exemple. Vous ne devez pas utiliser l'élément <form>, puisque votre fragment sera inclus dans l'élément <form> existant du template principal. Cependant, vous pouvez utiliser n'importe quel élément comme <input>, <textarea> etc.. Leur contenu, après la soumission, sera disponible, comme d'habitude, dans $_POST.

jTpl est utilisé pour les templates, donc vous pouvez utiliser la syntaxe jTpl.

Quelques variables de template sont prédéfinies dans le template:

  • les paramètres correspondant à la section dans la configuration
  • $appname, le nom de l'application défini dans la configuration

Localisation

Les fichiers correspondant à une langue, sont des fichiers PHP, qui devraient définir un tableau dans une variable nommée $locales.

Les clés des tableaux sont des chaines à traduire, et la valeurs les chaines traduites.


$locales = array(

'subtitle'=>'My subtitle',
);

Vous pouvez l'appeler dans votre template en utilisant la clé de la chaine traduite:


<h1>{@subtitle@}</h1>

A l'intérieur de la classe, vous avez le contenu de $locales dans une propriété locales:


 function show() {
    //..

    $subtitle = $this->locales['subtitle'];

    //...
 }

Le template principal

Il y a un template, wiz_layout.tpl, qui contient toute la page HTML de l'assistant (excepté bien sûr, le contenu spécifique généré par toutes les pages). C'est ici qu'il y a l'entête et de pied de chaque page de l'assistant.

Vous pouvez la redéfinir si vous voulez un design différent, un contenu différent. Voir ci dessous.

Pages existantes

Quelques pages sont fournies avec installWizard.

welcome

Elle affiche une page simple, avec un message de bienvenue. Vous pouvez la changer en redéfinissant le template ou les fichiers de locales.

checkjelix

Cette page vérifie si la configuration du serveur et l'installation de Jelix est ok pour installer l'application. Les paramètres de configuration sont:

  • verbose=on, affiche plus de détails.
  • databases=mysql,pgsql: liste des type de base de données. La page vérifiera si l'API de la base de données demandée, est disponible.

dbprofile

Cette page permet de configurer le fichier profiles.ini.php. Il affiche un formulaire où vous pouvez définir le nom du serveur de base de données, le nom de la base de données, le nom de connexion à cette page et le mot de passe de celui ci. Vous pouvez fournir un profiles.ini.php.dist dans le répertoire var/config/ de l'application: la page prendra celle-ci comme "un template" pour générer le fichier profiles.ini.php. C'est l'opportunité pour vous d'indiquer tout les profils à créer.

Paramètres de configuration:

  • ignoreProfiles: liste des profils à ignorer dans le fichier donné profiles.ini.php.dist
  • availabledDrivers: liste des types de base de données que votre application supporte. (mysql, pgsql, sqlite...)

confmail

Cette page permet de configurer le mailer. Il modifie donc le fichier mainconfig.ini.php de votre application.

Aucun paramètres de configuration.

installapp

il installe un application jelix. Il appelle les modules installers etc..

Paramètre de configuration :

  • level, avec une de ces valeurs: error, notice, warning. Il indique l'importance du message affiché.

end

Cette page affiche un simple message pour dire que l'installation est finie. Vous devriez l'utiliser pour la dernière page de votre assistant.

Redéfinir les templates et locales

Vous pourriez vouloir changer le design or le contenu HTML de page déjà fourni par installWizard.

Pour cela, vous devrez créer un répertoire où sont stockées vos propres versions des templates de pages. Déclarer le répertoire dans customPath dans la section option du fichier ini. Pour une application Jelix, ce chemin est typiquement install/wizard/custom, donc vous indiquerez customPath= "custom/".

Copier les fichiers originaux dans ce répertoire, et modifier les comme voulu. Vous pouvez faire de même avec les fichiers des locales.

De la même manière vous pouvez ajouter des nouveaux fichiers locales pour de nouvelles langues.

Vous pouvez aussi copier le template wiz_layout.tpl dans celui ci, lequel est le template principale. Vous pouvez alors modifier cette copie. Même chose pour les locales pour le template principal (wiz_layout.en.php).