Version actuelle
0.8.2
 

Développement

Retourner à l'index

Introduction

Hyla étant un logiciel libre, vous avez bien sûr accès au code source, il vous est ainsi possible de modifier Hyla librement et ensuite de redistribuer vos modifications, et cela, dans le cadre défini par la license fourni avec Hyla (fichier COPYING à la racine de Hyla).

L'arborescence

Ci-dessous, un tableau montrant l'arborescence des fichiers de Hyla.

Nom Description
/ La racine
/conf Dossier comportant tous les fichiers de configuration.
/doc La documentation classée par langue
/img Les images (mimetypes, perso)
/l10n Dans ce dossier se trouve les fichiers de traduction classés par langue.
/src La racine de ce dossier contient les fichiers sources divers, notamment, ceux qui génère les pages grâce aux modèles (template).
/src/db Ici, est placé, la classe d'abstraction de la base de données SQL.
/src/inc Dans ce dossier sont logés les classes et fonctions.
/src/lib Toutes les librairies externes à Hyla sont placées ici.
/src/plugin Dossier racine des plugins
/src/plugin/auth Les plugins d'authentification
/src/plugin/obj Les plugins des objets (fichiers et dossiers)
/sys Le dossier système
/sys/anon Les fichiers anonymes envoyés par Hyla sont placés ici.
/sys/cache Le dossier de cache.
/tpl Racine des dossiers comportant les modèles (template).

Remarque : Les dossiers /sys, /sys/cache et /sys/anon doivent être rendu inaccessible (par exemple, avec Apache, en mettant un fichier .htaccess contenant "deny from all")

Les modèles

Un modèle est un ensemble de fichiers, de gabarits qui servent pour la réprésentation visuelle de Hyla, un fichier modèle (.tpl) ne comporte pas de code source, ainsi, il est très simple à éditer pour quelqu'un chargé uniquement de l'apparence d'un site.

Dans Hyla, les modèles sont "rangés" dans le dossier /tpl situé à la racine de Hyla, chaque dossier contenu dans ce dernier est un modèle différent, ainsi, vous pourrez trouver un dossier nommé default ou encore rss.

Structure d'un modèle

Si nous ouvrons le dossier /tpl/default, voici les fichiers et dossiers que nous découvrons :

Revenons sur le fichier info.xml qui à une grande importance, il permet de définir le nom du modèle, l'auteur, le dossier image et de déclarer les feuilles de style, voici le contenu d'un tel fichier : 

<?xml version="1.0" encoding="UTF-8"?>

<template>
	<name>Default</name>
	<description>Thème par défaut en xhtml</description>
	<author>hugo</author>
	<version>1</version>
	<header>Content-Type: text/html; charset=UTF-8</header>
	<img-src>/tpl/default/img</img-src>
	<php-function>./tpl/default/function.php</php-function>
	<stylesheets>
		<stylesheet>
			<type>text/css</type>
			<media>screen,projection</media>
			<title>Standard</title>
			<href>default.css</href>
		</stylesheet>
[...]

Revenons dans le tableau ci-dessous sur le contenu de ce fichier :

Chemin XPath Description
/template/name Le nom du modèle
/template/description La description du modèle
/template/author L'auteur de ce modèle
/template/version La version du modèle
/template/header L'entête spécifiant le type de contenu à envoyer au navigateur
/template/img-src Le dossier oû sont rangées les images
/template/php-function Le fichier source contenant les fonctions php
/template/stylesheets/stylesheet/type Le type
/template/stylesheets/stylesheet/media Le média concerné par la feuille de style
/template/stylesheets/stylesheet/title Le titre de la feuille de style
/template/stylesheets/stylesheet/href Le nom de la feuille de style

Créer un nouveau modèle

La création d'un nouveau modèle est relativement simple, nous allons prendre un exemple concret : la création d'un nouveau modèle identique à default mais qui aurait la barre des actions en haut au lieu d'en bas.

  1. Création d'un nouveau dossier dans /tpl/, nous allons l'appeler /tpl/test/
  2. Nous allons copier tous les fichiers js et la feuille de style default.css du dossier /tpl/default/ dans /tpl/test/ afin de reprendre tous les codes javascript et d'avoir la feuille de style par défaut.
  3. Maintenant, copions le fichier info.xml du dossier /tpl/default/ dans /tpl/test/ puis éditons-le afin qu'il ressemble à ceci : 
    <?xml version="1.0" encoding="UTF-8"?>

<template>
	<name>test</name>
	<description>Modèle avec la barre d'action en haut</description>
	<author>VotreNom</author>
	<version>1</version>
	<header>Content-Type: text/html; charset=UTF-8</header>
	<img-src>/tpl/default/img</img-src>
	<php-function>./tpl/default/function.php</php-function>
	<stylesheets>
		<stylesheet>
			<type>text/css</type>
			<media>screen,projection</media>
			<title>Standard</title>
			<href>default.css</href>
		</stylesheet>
	</stylesheets>
</template>
    Vous remarquerez que j'ai supprimé les déclarations des feuilles de style qui ne nous intéressaient pas pour garder uniquement default.css.
  4. Voilà, notre modèle est prêt, il n'y a plus qu'à passé au principal, c'est à dire, copier le fichier /tpl/default/index.tpl dans /tpl/test/, ouvrez maintenant ce fichier (/tpl/test/index.tpl) et modifiez le code html de cette manière : 
        [...]
    <div id="main">
        {CONTENT}
    </div>
    
    {TOOLBAR}
    
    <div class="copyright">
    [...]
    afin que cela ressemble à ceci : 
        [...]
    {TOOLBAR}
    
    <div id="main">
        {CONTENT}
    </div>
    
    <div class="copyright" style="clear:both">
    [...]
  5. Maintenant, allez dans l'administration, vous remarquerez que Hyla à pris en compte le nouveau modèle, spécifiez que vous désirez utiliser ce nouveau modèle et c'est tout !

Dans cette exemple, nous n'avons copié que le fichier index.tpl et aucun autre dans notre nouveau dossier de modèle (tpl/test/), Hyla va aller chercher les autres fichiers modèles dans le dossier default si ils ne sont pas présent dans le modèle courant...

Les plugins

Sur Hyla, un plugin est une classe qui est instanciée à la volée.
Dans Hyla, il existe 3 types de plugins et les futures versions permettront toujours plus de modularité grâce au plugin :

Les plugins d'objets

Pour Hyla, un objet est un fichier, un dossier ou encore un fichier au sein d'une archive (zip, tar.gz...), un plugin d'objet est donc suceptible de lire des dossiers ou encore des fichiers...

Pour illustrer le fonctionnement des plugins d'objets, voici, ci-dessous, le contenu du dossier d'un plugin très simple, le plugin Text qui permet d'afficher le contenu d'un fichier txt :

Fichier Description
/src/plugin/obj/text/index.php Le plugin en lui même
/src/plugin/obj/text/info.xml Fichier de description contenant les informations sur le plugin.
/src/plugin/obj/text/text.tpl Le fichier modèle

Ci dessous, le contenu du fichier info.xml 

<?xml version="1.0" encoding="UTF-8"?>

<plugin target="file" enabled="true">
	<name>Text</name>
	<extension>txt</extension>
	<description>Affichage du contenu du fichier</description>
	<author>hugo</author>
	<version>1</version>
</plugin>

Vous percevez dans la balise plugin, l'attribut target qui permet de spécifier à quel type de fichiers, par le biais de l'extension, s'adresse le plugin, en l'occurence, ici, les fichiers dont l'extension est txt, c et h.

Voici, le contenu du fichier /src/plugin/obj/text/index.php suivi des explications : 

<?php

class plugin_obj_text extends plugin_obj {
    
    function plugin_obj_text($cobj) {
        parent::plugin_obj($cobj);
    
        $this->tpl->set_root($this->plugin_dir.'text');
        $this->tpl->set_file('text', 'text.tpl');
    }
    
    function aff() {
    
        $content = file::getContent($this->real_file);
        $content = htmlentities($content, ENT_QUOTES);
    
        $this->tpl->set_var('CONTENT', $content);
    
        return $this->tpl->parse('OutPut', 'text');
    }
}

?>

Comme mentionné plus haut, un plugin est bel et bien une classe qui est nommée d'une manière défini, en l'occurence : "plugin_obj_" + le nom du plugin.

La première ligne dans le constructeur ( parent::plugin_obj($cobj) ) est obligatoire, elle permet d'initialiser des valeurs, ensuite, sur les lignes suivantes, nous trouvons l'initialisation du modèle (template) et la déclaration du fichier test.tpl.

Vous aurez remarqué la méthode nommée aff() qui est appelée automatiquement par Hyla lors du chargement d'un fichier text, une fois l'objet créé, cette fonction peut prendre un paramètre (paramètre envoyé au plugin) et doit renvoyer le contenu généré par le plugin.
Au sein de cette fonction, vous remarquerez l'utilisation de la variable membre $this->real_file qui permet de renvoyer le chemin vers l'objet courant, si l'objet courant est un fichier contenu dans une archive, cette variable vous renverra alors, entièrement automatiquement, le chemin vers le fichier extrait dans le cache.

Remarque : A aucun moment, un plugin ne doit afficher le contenu de la variable $this->real_file car le visiteur n'a pas à savoir dans quel dossier se fait la lecture des objets...

Hello World !

Nous allons réaliser un plugin qui affiche "Hello World" à la rencontre d'un fichier portant l'extension ".coucou".

Tout d'abord, créons un nouveau dossier que l'on nommera "hello" dans /src/plugin/obj, puis, créons à l'intérieur de ce dernier un fichier info.xml qui contiendra ceci : 

<?xml version="1.0" encoding="UTF-8"?>

<plugin target="file" enabled="true">
	<name>Hello</name>
	<extension>coucou</extension>
	<description>Hello World pour fichier .coucou</description>
	<author>votre nom</author>
	<version>1</version>
	<minversion>0.8.1</minversion>
</plugin>

Ce fichier créé, il nous reste à créer le plugin proprement dit, pour cela, créons un fichier index.php dans le dossier que nous avons créé plus haut et éditons le afin qu'il ressemble à cela : 

<?php

class plugin_obj_hello extends plugin_obj {

    function plugin_obj_hello($cobj) {
        parent::plugin_obj($cobj);
    }
    
    function aff() {
        return 'Hello World !';
    }
}

?>

Voilà, c'est tout, maintenant, à l'ouverture d'un fichier comportant une extension .coucou, Hyla affichera Hello World, totalement inutile, totalement indispensable...

Les plugins d'authentification

Ces derniers permettent d'authentifier un utilisateur ayant saisi son login et son mot de passe en interrogeant une base de données SQL ou encore un serveur LDAP, le choix du type d'authentification se fait par le biais du fichier de configuration /conf/hyla.ini : 

[...]

; La méthode d'authentification
; - default : méthode standard
; - ldap : Authentification grâce à un annuaire LDAP (bêta)
plugin_default_auth = default

[...]

Les plugins d'authentification se situe dans l'arborescence suivante : /src/plugin/auth, examinons le fonctionnement du plugin d'authentification « default » en éditant le fichier /src/plugin/auth/default/index.php : 

<?php
	
class plugin_auth_default {

    /*  Initialisations
        */
    function plugin_auth_default() {
        parent::plugin_auth();
    }
    
    /*  Phase d'authentification
        @param	$name		Le nom de l'utilisateur
        @param	$password	Le mot de passe associé
        */
    function auth($name, $password) {
        $usr = new users();
        return $usr->auth($name, $password);		
    }
}

?>

Comme vous le voyez, un plugin d'authentification est en fait une classe qui est nommé d'une manière défini ( "plugin_auth_" + le nom du plugin )

La classe doit impérativement contenir une méthode nommée auth qui accepte comme paramètre le nom et le mot de passe que l'utilisateur à saisi dans Hyla, cette dernière doit retourner null en cas d'erreur ou une structure de type tUser correctement renseignée en cas de succès : 

class tUser {
        var $id;		// Id
        var $name;		// Nom
        var $type;		// Type
}

Les plugins d'url

Ces derniers permettent de gérer les url, ainsi, il vous est possible de faire en sorte qu'Hyla génère des urls identique à celle que vous utilisez sur votre site.
Le choix du type d'url se fait, comme pour le plugin d'authentification, par le biais du fichier de configuration /conf/hyla.ini : 

[...]

; Url plugin
; - default : méthode standard
; - pathinfo : Génère des url de type path info
plugin_default_url = pathinfo

[...]

Les plugins d'url se situe dans l'arborescence suivante : /src/plugin/url

Voici le squelette d'un plugin d'url : 

<?php
	
class plugin_url_default extends plugin_url {

    /*  Constructor
        */
    function plugin_url_default() {
        parent::plugin_url();
    }

    /*  Scan url
        @param  array   $url    Array ($_REQUEST or other)
        @return tUrl object
        */
    function scan($url) {

        $ret = new tUrl;

        [...]
        
        return $ret;
    }

    /*  Get an url
        @param  mixed   $object Object
        @param  array   $aff    Page
        @param  array   $act    Action
        @param  string  @pact   Plugin action
        @param  string  @paff   Plugin aff
        @return Url
        */
    function get($object, $aff = null, $act = null, $pact = null, $paff = null) {
                
        [...]

        return $url;
    }
}

?>

Le constructeur doit appelé le constructeur parent afin d'initialiser des variables.
Vous aurez remarquez la présence de 2 méthodes obligatoires scan et get, la première permet de scanner l'url courante et elle doit renvoyer une structure (classe) de type tUrl (voir ci-dessous) et la seconde permet de générer des urls.

Voici le contenu de la structure tUrl : 

class tUrl {
    var $obj;       // Current object

    var $act;       // Current action
    var $aff;       // Current view

    var $pact;      // Plugin action
    var $paff;      // Plugin view
}
Remonter

Valid XHTML 1.0 Transitional Logo de soutien au projet Opquast Point d'interrogation À propos...