MALA template

Un système de templates appliqué aux bases de données.

Auteur David Duret <contact>
Version 1.0
Copyright 2002 David Duret 

I. Pour bien commencer
     1. Aperçu
          Qu'est-ce que MALA ?
          Fonctionnalités
     2. Installation
          Prérequis
          Installation des fichiers
II. MALA pour les créateurs de templates
     1. Les balises
     2. Les variables
          Syntaxe
          Les variables prédéfinies
III. MALA pour les programmeurs
     1. Les propriétés
     2. Les méthodes
IV. Annexes

I. Pour bien commencer

1. Aperçu

Qu'est-ce que MALA ?

MALA est une classe simplifiant la séparation du code de la présentation de vos données (HTML, XML, mail, feuille de styles, ...). Les avantages d'un tel système sont multiples: le développeur et le graphiste travaillent chacun de leur côté sans avoir besoins de connaissances de l'autre, la création d'un site est plus simple et plus rapide ainsi que sa mise à jour, ...

Disponible en PHP et en ASP, la spécificité de MALA par rapport à d'autres systèmes de ce genre est son support en native des bases de données (MySQL, PostgreSQL, MS Access, MS SQL Server, ...). Une simple requête suffit à accéder aux données à afficher.

Fonctionnalités

  • sources de données multiples: base de données, fichier de type CSV, tableau de données
  • gestion du multipage pour l'affichage des données
  • assignation de variables internes au template
  • application de fonctions d'affichage et de traitement à ces variables internes
  • affichage conditionnel de blocs
  • imbrication de templates
  • ...

2. Installation

Prérequis

La version MALA PHP est compatible PHP3 et PHP4. PHP doit être compilé avec le support de la base de données que vous voulez utiliser. La couche PEAR est nécessaire pour les bases de données autres que MySQL et PostgreSQL. Mais en cas d'utilisation avec PHP3, seule la base de données MySQL est disponible.

La version MALA ASP requiert une version égale ou supérieur à VBScript 5 sur le serveur. Ceci est due à l'utilisation des classes qui ne sont présentes qu'à partir de cette version de VBscript. Pour l'accès aux ases de données, il suffit d'avoir les drivers ODBC correctement installés et configurés pour la base à utiliser. Vous pourrez alors accéder à des bases de données comme MS ACCESS, MS SQL Server, ...

Et dans les deux cas, vous devez avoir à votre disposition un serveur web pour générer vos pages et un navigateur internet pour les visualiser :o)

Remarques

  • MALA PHP a été testé avec PHP 3.0.17, PHP 4.0.6, PHP 4.1.2, PHP 4.2.1 sous Windows 2000 Pro et Windows 2000 Pro Server (IIS et Apache), Linux, FreeBSD.
  • MALA ASP a été testé sous Windows 2000 Pro et Windows 2000 Server avec IIS et Apache/ChiliASP.
  • Les bases de données testées sont MySQL, PostgreSQL, MS ACCESS, SQL Server 2000.

Installation

Il n'y a pas d'installation proprement dite. Vous devez simplement copier le fichier de la classe dans un répertoire du serveur (votre répertoire d'inclusion ou autre).

Version PHP

<?php require_once("MALA.php"); // require("MALA.php") dans le cas de PHP3 ?>

Si vous souhaitez utiliser une base autre que MySQL ou PostgreSQL, PEAR doit être accessible dans votre répertoire d'inclusion; MALA tente en effet de charger le fichier DB.php de PEAR comme suit: @include_once("DB.php").

Version ASP

<!--#INCLUDE FILE="MALA.asp"-->

II. MALA pour les créateurs de templates

Un fichier template MALA est un fichier HTML standard comportant des éléments propres à MALA qui indiquent au script de quelle manière utiliser ce template. L'extension de fichier n'est pas importante mais l'utilisation de .html est la plus logique. Son contenu peut être simplement une portion de code ou alors une page entière incluant les balises <html></html>. Les éléments distinctifs sont les balises et les variables.

Remarque: le format et la structure des fichiers template sont les mêmes pour les versions PHP et ASP. Cela peut être utile lors d'une migration d'un langage à l'autre, tous les modèles de pages pouvant être conservés.

1. Les balises

Les balises sont les éléments qui indiquent la structure de la page c'est à dire les différents blocs qui la composent. Pour shématiser, un template est découpé en trois grandes parties dans le cadre d'une utilisation avec base de données: l'entête (header), la partie principale (main) qui contient les données à afficher et le pied de page (footer).

Les balises propres à MALA sont les suivantes:

  • <MAIN></MAIN> délimitent la partie principale de l'affichage des données; ce bloc est affiché dans le cas ou il y a au moins un enregistrement
  • <LOOP></LOOP> délimitent la partie correspondant à l'affichage d'un enregistrement; ces balises se trouvent obligatoirement dans le bloc principal <MAIN></MAIN>
  • <NORECORDS></NORECORDS> délimitent la partie à afficher si aucun enregistrement n'a été trouvé; ces balises doivent être situées dans le footer c'est à dire après le bloc <MAIN></MAIN>
  • <IF name="condition"><ELSE></IF> permettent un affichage conditionnel de certaines parties de la page, s'utilise conjointement avec la fonction ApplyCondition(). On peut les utiliser dans n'importe quel bloc (mais en aucun cas "à cheval" sur une balise ouvrante ou fermante de type <MAIN></MAIN>, <LOOP></LOOP> ou <NORECORDS></NORECORDS>)
  • <IFNOT name="condition"><ELSE></IFNOT> fonctionne de la même manière que les balises <IF></IF> mais l'évaluation se fait sur le contraire logique de la condition utilisée

Remarques

  • il n'y a pas de balises spécifiques aux header et footer. En effet, tout ce qui se trouve avant les balises <MAIN></MAIN> est considéré comme étant le header; tout ce qui est situé après ces mêmes balises est considéré comme appartenant au footer.
  • actuellement MALA ne gère pas l'utilisation des conditions imbriquées. Cette fonctionnalité devrait être développée dans une version ultérieure.

Exemple (PHP et ASP)

<!-- Fichier contacts.html -->
<p><b>Liste des contacts</b></p>
<MAIN>
<table>
<tr>
<td>N°</td> <td>Nom</td>
<td>Email</td>
</tr>
<LOOP><tr>
<td>$id</td>
<td>$nom</td>
<td>$email</td>
</tr></LOOP>
</table>
</MAIN>
<NORECORDS><p>Aucun enregistrement n'a été trouvé.</p></NORECORDS>

2. Les variables

Syntaxe

Les variables sont les éléments qui seront remplacés par leur valeur réelle lors de l'affichage de la page. Le nom d'une telle variable doit commencer par un $ et être alpha-numérique (les underscores '_' sont autorisés) soit - en terme d'expression régulière - définies comme suit $[a-zA-Z0-9_]+.

Les variables prédéfinies

Il existe des variables predéfinies qui sont affectées automatiquement lors de la consctruction de la page. Les noms de variables correspondant ne doivent donc pas être utilisé sous peine de dysfonctionnement.

Variables générales

  • $ScriptName: nom du fichier en cours d'execution. Peut être utile pour appeler le fichier sans connaître son nom.
  • $MALA_Version: numéro de version de MALA utilisée.

Barre de navigation

  • $Count: nombre total d'enregistrements.
  • $First: indice du premier enregistrement de la page en cours d'affichage. Sa valeur est égale à 1 si le nombre d'enregistrement par page n'est pas indiqué.
  • $Last: indice du dernier enregistrement de la page en cours d'affichage. Sa valeur est égale à $Count si le nombre d'enregistrement par page n'est pas indiqué.
  • $PageNumber: indice de la page d'enregistrement en cours d'affichage. Sa valeur est égale à 1 si le nombre d'enregistrement par page n'est pas indiqué.
  • $PageCount: nombre de page total d'enregistrements nécessaires. Sa valeur est égale à 1 si le nombre d'enregistrement par page n'est pas indiqué.
  • $UrlFisrt: lien vers la première page d'enregistrements. C'est une chaine vide si le nombre d'enregistrement par page n'est pas indiqué.
  • $UrlPrev: lien vers la page précédente d'enregistrements. C'est une chaine vide si le nombre d'enregistrement par page n'est pas indiqué.
  • $UrlNext: lien vers la page suivante d'enregistrements. C'est une chaine vide si le nombre d'enregistrement par page n'est pas indiqué.
  • $UrlLast: lien vers la dernière page d'enregistrements. C'est une chaine vide si le nombre d'enregistrement par page n'est pas indiqué.

Ligne d'enregistrement

  • $LineNumber: indice d'un enregistrement. La valeur est fixée à 1 pour le premier enregistrement et est incrémentée à chaque enregistrement.
  • $BgColor: couleur de la ligne telle qu'elle a été spécifiée avec la methode SetRowBgColor(). La couleur change alternativement une ligne sur deux.

Exemple (PHP et ASP)

<MAIN>
<p>page $PageNumber sur $PageCount (enregistrements $First - $Last sur $Count)</p>
<table>
<LOOP><tr bgcolor="$BgColor">
<td>$LineNumber</td>
<td>$nom</td>
<td>$email</td>
</tr></LOOP>
</table>
<p>$UrlFirst $UrlPrev $UrlNext $UrlLast</p>
</MAIN>
<NORECORDS><p>Aucun enregistrement trouvé.</p></NORECORDS>

III. MALA pour les programmeurs

1. Les propriétés

La propriété DSN

Cette propriété n'est pas encore implémentée dans la version actuelle de MALA ASP.

Fourni la chaine de connection à la base de données. C'est MALA qui ouvrira cette connexion. Attention, la construction de la chaine de connexion est différente suivant le langage utilisé (PHP ou ASP).

Exemple PHP: voir la documentation PEAR à ce sujet: http://pear.php.net/manual/en/core.db.tut_dsn.php

$objMala->DSN = "mysql://root@localhost/MALA";

Exemple ASP: la chaine de connexion correspond à la chaine classique de connexion en ODBC.

objMala.DSN = "Driver={Microsoft Access Driver (*.mdb)}; DBQ=demo.mdb;"

La propriété Connection

L'utilisation de cette propriété est appellée à être modifiée dans une prochaine version de MALA ASP.

En utilisant cette propriété, vous passez à MALA une connexion déjà ouverte; cela vous permet d'ouvrir une connexion unique en début de script et de l'utiliser pour plusieurs instances de MALA.

Exemple PHP

$db = DB::connect("mysql://root@localhost/MALA");
$objMala->Connection = $db;

Exemple ASP

Dim objConnection
Set objConnection = Server.CreateObject("ADODB.Connection")
objConnection."Driver={Microsoft Access Driver (*.mdb)}; DBQ=demo.mdb;"

Set objMala.Connection = objConnection

La propriété File

File est un tableau associatif qui contient les différents éléments du fichier template. Cette propriété n'est pas utile si vous chargez un fichier externe avec la methode GetFile().

Les éléments de la propriété File sont:

Are you looking new car prices this is good idea . Saving money on gps car accessories for every day . You can find local car dealer we want to make sure that you like it

  • File['Header'] correspond au debut du fichier situé avant la balise <MAIN>
  • File['Footer'] correspond à la fin du fichier situé après la balise </MAIN> vous devez indiquer l'emplacement de la portion <NORECORDS></NORECORDS> à l'aide de la variable $NoRecords
  • File['Main'] correspond au bloc principal des données situé entre les balises <MAIN> </MAIN>; vous devez indiquer l'emplacement de la portion <LOOP></LOOP> à l'aide de la variable $Loop
  • File['Loop'] correspond à l'affichage d'un enregistrement situé entre les balises <LOOP></LOOP>
  • File['NoRecords'] correspond au bloc à afficher dans le cas où aucun enregistrement n'est trouvé; <NORECORDS></NORECORDS>; cette partie doit être située après le bloc <MAIN></MAIN>
  • File['Content'] contient le contenu complet de la page à afficher dans le cas où aucune base n'est utilisée

Exemple PHP (similaire en ASP)

// Affichage des données en provenance de la base
$objMala->File['Header'] = '<p><b>Liste des contacts</b></p>';
$objMala->File['Main'] = '<table><tr><td>N°</td><td>Nom</td><td>Email</td></tr>$Loop</table>';
$objMala->File['Loop'] = '<tr><td>$id</td><td>$nom</td><td>$email</td></tr>';
$objMala->File['Footer'] = '$NoRecords';
$objMala->File['NoRecords'] = '<p>Aucun enregistrement n'a été trouvé.</p>';

// Affichage d'une page simple
$objMala->File['Content'] = '<p>Bonjour, $Nom ! Nous sommes le $Date.</p>';

L'avantage de l'utilisation de la propriété File est que vous pouvez ainsi créer votre template à la volée sans connaitre avec certitude les éléments à afficher ou quand la taille du ficher template est faible et ne nécessite pas forcement la création d'un fichier externe.

Exemple PHP (similaire en ASP)

// Creation d'une liste déroulante
$objMala->Query['String'] = "select id, nom from contacts order by nom asc";
$objMala->File['Main'] = '<select name="nom">$Loop</select>';
$objMala->File['Loop'] = '<option value="$id">$nom</option>';

La propriété Query

Query est un tableau associatif qui contient soit la requête entière soit ses éléments séparés. Ces deux modes peuvent être utilisés indifféremment mais le mode ou les éléments sont séparés est la plus souple.

Les éléments de la propriété Query sont:

  • Query['String']: contient la totalité de la requête; même si la requête est passée en plusieurs éléments, cette valeur sera renseignée après l'execution de la requête.
  • Query['Select'] correspond à la clause SELECT d'une requête SQL
  • Query['From'] correspond à la clause FROM d'une requête SQL
  • Query['Where'] correspond à la clause WHERE d'une requête SQL
  • Query['GroupBy'] correspond à la clause GROUP BY d'une requête SQL
  • Query['OrderBy'] correspond à la clause ORDER BY d'une requête SQL
  • Query['Limit'] correspond à la clause LIMIT d'une requête SQL

Les noms des variables à utiliser dans le fichier template sont les noms de champs sélectionnés dans la clause Select - ou leur alias s'il existe.

Exemple PHP (similaire en ASP)

// Soit toute la requête est contenue dans un élément
$objMala->Query['String'] = "select nom, prenom, email from contacts";

// Soit la requête est séparée en éléments distincts
$objMala->Query['Select'] = "nom, prenom, email";
$objMala->Query['From'] = "contacts";

Fichier template associé

<MAIN>
<LOOP>$nom $prenom [$email]<br></LOOP>
</MAIN>

Remarque: si ni Select, ni String ne sont précisés lors de l'execution de la requête alors MALA considère qu'aucune base de données n'est utilisée et renvoie FALSE à l'execution de cette requête.

La propriété NbRecordPerPage

Cette propriété permet de spécifier le nombre d'enregistrements à afficher par page de résultat. Si elle est non précisée ou égale à 0 alors les résultats sont affichés dans une seule page.

Exemple PHP (similaire en ASP)

// Affichage de 30 enregistrements par page
$objMala->NbRecordPerPage = 30;

2. Les méthodes

Les méthodes indispensables au bon fonctionnement sont au nombre de deux. Il existe cependant des méthodes supplémentaires apportant beaucoup de souplesse au traitement et à l'affichage de données. Voir la documentation technique de la classe pour de plus amples détails sur ces méthodes.

La méthode MALA()

C'est le constructeur de l'objet qui doit être appelé en premier lieu. Aucun paramètre n'est nécessaire lors de son appel.

Exemple PHP (similaire en ASP)

$objMala = new MALA;

La méthode LoadString()

Cette méthode n'est pas implémentée dans la version actuelle de MALA ASP.

Charge une chaine de caractères en tant que données à afficher (ex: $QUERY_STRING).

Exemple

// $QUERY_STRING = "nom=Cover&prenom=Harry&email=h.cover"
$objMala->LoadString($QUERY_STRING, 'NOM, VALEUR', '=', '&');

La méthode LoadFile()

Cette méthode n'est pas implémentée dans la version actuelle de MALA ASP.

Charge un fichier de type CSV en tant que données à afficher.

Exemple

// Si le fichier est un fichier CSV MS Excel contenant un liste de contacts avec nom, prenom et email
$objMala->LoadFile('contact.csv', 'NOM, PRENOM, EMAIL', ';', "\r\n");

La méthode LoadArray()

Cette méthode n'est pas implémentée dans la version actuelle de MALA ASP.

Charge un tableau de données en tant que données à afficher.

$contacts = (
     array("Cover", "Harry", "h.cover"),
     array("Tim", "Vincent", "vtim")
);
$objMala->LoadArray($contacts, 'NOM, PRENOM, EMAIL');

La méthode Show()

C'est la méthode qui affiche le résultat final. Aucun paramètre n'est nécessaire.

Exemple PHP (similaire en ASP)

$objMala->Show();

La méthode GetFile()

Charge le fichier template et découpe les différents blocs le composant depuis un fichier externe.

Exemple PHP (similaire en ASP)

$objMala->GetFile('contact.html');

La méthode Read()

Cette méthode peut être utile dans le sens où l'on ne veut pas afficher le résultat mais plutôt le stocker dans une variable. Elle retourne donc le contenu du résultat final.

Exemple PHP (similaire en ASP)

$strContent = $objMala->Read();
echo $strContent;

La méthode Assign()

Crée une nouvelle variable interne et lui affecte une valeur. Cette variable alors sera disponible dans le fichier template.

Exemple PHP (similaire en ASP)

$objMala->Assign('$Date', date('Y-m-d H:i:s'));

La méthode ApplyFunction()

Applique une fonction à une variable interne qu'elle se trouve à l'intérieur ou à l'extérieur de la boucle des enregistrements.

Exemple PHP (similaire en ASP)

// On passe le nom des contacts en majuscules
$objMala->ApplyFunction('strtoupper', '$nom', '$nom');

La méthode ApplyCondition()

Applique une condition d'affichage à une portion de bloc. Le bloc est affiché si la condition est vérifiée, il n'est pas affiché dans le cas contraire. Une condition est caractérisée dans le fichier template par les balises <IF><ELSE></IF> ou <IFNOT><ELSE></IFNOT>.

Les conditions peuvent être utilisé n'importe où dans le fichier template, aussi bien dans les blocs HEADER, FOOTER, NORECORDS que dans les blocs MAIN ou LOOP.

Exemple PHP (similaire en ASP)

// On affiche la portion de code si l'identifiant du contact est égal à 10
$objMala->ApplyCondition('affiche_contact', '$id == 10');

Le code employé dans le fichier template est alors le suivant:

<IF name="affiche_contact">Bravo vous êtes notre 10ième contact !</IF>

Si l'on veut afficher tous les enregistrements différents de 10 en utilisant la même condition affiche_contact alors on utilise les balises <IFNOT><ELSE></IFNOT>

<IFNOT name="affiche_contact">Bravo vous n'êtes pas notre 10ième contact !</IFNOT>

La méthode SetRowBgColors()

Spécifie des couleurs de lignes d'enregistrements alternatives permettant d'avoir une alternance de couleurs pour les lignes d'enregistrements.

Exemple PHP (similaire en ASP)

$objMala->SetRowBgColors('#EEEEEE', '#FFFFFF');

Les méthodes SetNavClass(), SetNavLabels(), SetNavTitles(), SetNavAttributes()

Ces méthodes permettent de personnaliser les liens de navigation entre les pages d'enregistrements: libellés, titres et la possibilité d'ajouter n'importe quel complément à un lien.

Exemple PHP (similaire en ASP)

// Nom de la classe à appliquer aux liens
$objMala->SetNavClass('NavBar');

// Libellés des liens
$objMala->SetNavLabels(
    '<< première page',
    '< page précédente',
    'page suivante >',
    'dernière page >>');

// Titre des liens
$objMala->SetNavTitles(
    'Aller à la première page',
    'Aller à la page précédente',
    'Aller à la page suivante',
    'Aller à la dernière page');

// Complément des liens
$objMala->SetNavAttributes(
    ' '.
    '',
    ' '.
    '',
    ' '.
    '',
    ' '.
    '');

IV. Annexes

A venir... (bugs connus, faq, liens).
MALA template Links

mala-template.net v 4_3