Développement

Retourner à l'index

• Introduction
• L'arborescence
• Les modèles
  • Structure d'un modèle
  • Créer un nouveau modèle
• Les plugins
  • Les plugins d'objets
    • Hello World !
  • Les plugins d'authentification
  • Les plugins d'url

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 licence fourni avec Hyla (fichier COPYING à la racine de Hyla).

L'arborescence

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

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 repré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 :

• img/ Dossier contenant les images du modèles
• *.css Les différentes feuilles de styles
• *.js Les scripts javascript
• *.tpl Les fichiers modèles
• function.php Ce fichier source est le seul contenant à la fois du code php et du html, il en est ainsi pour des raisons de performances.
• info.xml Fichier permettant d'informer sur le contenu du modèle

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 :

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 cet 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ésents 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 qui permettent de lire les dossiers, de créer des galeries photos...etc...
• Les plugins d'authentification qui permettent d'authentifier un utilisateur qui saisit sont mot de passe.
• Les plugins d'url qui permettent de générer et de scanner les urls

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

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'occurrence : "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ée 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 identiques à 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 situent 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 appeler le constructeur parent afin d'initialiser des variables.
Vous aurez remarqué 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
}
    

• $obj : Objet courant
• $act : L'action courante
• $aff : L'affichage courant sous forme de tableau (ex: array('obj', 'download'))
• $pact : Paramètre d'action pour le plugin courant
• $paff : Paramètre d'affichage pour le plugin courant