Les composants Mason

Description

Un composant est un morceau de site web. Un site web est généralement constitué de plusieurs pages. Ces pages sont construites à partir de plusieurs éléments : par exemple un menu, un bandeau supérieur, un bandeau inférieur, un cadre de contenu, un encart de navigation, etc. Les composants Mason permettent d'implémenter ces éléments, et de les assembler. Prenons en exemple un petit site personnel. Considérons que chaque page est structurée comme suit :

un bandeau supérieur, contenant un logo et la date du jour
un menu de navigation vers les autres pages
le contenu de la page proprement dit
un bandeau inférieur, contenant des mentions légales

Ce site web contient plusieurs pages :

une page d'accueil
une page de brèves
une page « à propos de l'auteur »

Nous pouvons structurer le site web comme suit : un composant pour chaque page, lui même constitué de composants pour les bandeaux supérieur et inférieur, la navigation et le contenu.

Syntaxe

Un composant est un fichier. Il n'a pas besoin de déclaration. Un fichier test.html contenant du HTML et du Mason est un composant sans le savoir.

Lors d'une requête sur le site web, Mason doit décider quel composant (appelé « top-level ») va être interprété en premier. Il est choisi en fonction de l'url. Par exemple, de l'adresse http://www.siteweb.com/produits/cuillere.html?modele=7 Mason déduit qu'il lui faut appeler le composant cuillere.html, dans le répertoire produits/. S'il n'existe pas (si le fichier /produits/cuillere.html est inconnu), alors Apache renverra une erreur 404. En fait, nous verrons plus tard qu'il est possible d'intercepter ce 404.

Appeler un composant

Nous venons de le voir, un composant peut s'appeler simplement en entrant son URL. Mais les composants peuvent bien sûr s'appeler entre eux. On utilise cette syntaxe :

  <& chemin/du/composant.html, arguments_optionels &>

Le composant appelé sera interprété, et le contenu HTML résultant inséré en lieu et place de l'appel. Le chemin du composant suit la syntaxe des URI, donc le séparateur est /, et il peut être absolu ou relatif. Le répertoire courant est celui du composant appelant.

Voici le composant de la page d'accueil. Nous allons le créer dans index.html, ça sera la page par défaut de notre site web d'exemple :

  %# index.html
  %# Début du composant index
  
  %# on appelle le bandeau supérieur
    <& bandeau_sup.html &>

  %# on appelle le menu de navigation
  %# on passe le nom de la page actuelle
    <& navigation.html, page_courante => 'index' &>

  %# Voici le contenu spécifique de la page d'accueil

  <center>Bonjour et bienvenue sur ce site web !</center>

  %# le bandeau inférieur
  <& bandeau_inf.html &>

Créons maintenant le composant du bandeau supérieur qui s'appelle bandeau_sup, qui va contenir les balises de début de page, et un logo. Editons donc le fichier bandeau_sup.html :

  %# bandeau_sup.html
  <html>
  <head></head>
  <body>
  <center><img src="/images/logo.png"></center>

C'est plutôt simple. Bien sûr, ce HTML n'est qu'un exemple, il n'est pas du tout conforme aux normes W3C. Voyons maintenant le composant de navigation. Le menu de navigation doit présenter un lien vers les autres pages du site web, mais pas vers celle affichée actuellement, car c'est redondant. Ainsi, sur la page d'accueil, le menu de navigation permet de se rendre sur la « page de brèves », ou vers l'« à-propos ». Sur la page « à-propos », le menu de navigation propose les liens vers la « page d'accueil » ou la « page de brèves». C'est pourquoi nous passons en argument le nom du lien à ne pas afficher (voir plus bas en détail le passage d'arguments). Voici le composant navigation :

  %# navigation.html
  
  %# récupération de l'argument
  <%args>
  $page_courante
  </%args>

  %# on commence une table
  <table>

  %# on boucle sur tous les liens
  % foreach(qw(index breves apropos)) {
  %# si le lien n'est pas la $page_courante, on l'affiche
  %   if ($_ ne $page_courante) {
  %# on affiche le HTML du lien, construit à la volée, dans une ligne de la table
        <tr><td> <a href="<% $_ . 'html' %>">$_</a> </td></tr>
  %   } 
  % }

  %# on ferme la table
   </table>

Et pour finir voici le source du bandeau inférieur qui ferme la page web :

  %# bandeau_inf.html
  </body>
  </html>

Le fichier index.html est chargé par défaut lorsque l'utilisateur navigue sur le site web. Il est cependant également possible d'appeler les autres pages (donc composants) du site. Ainsi l'URL http://www.siteweb.com/bandeau_sup.html permet d'appeler le composant bandeau_sup.html.

Passer des arguments

Voici quelques précisions sur le passage d'arguments d'un composant à un autre. Les arguments peuvent être de tout type : scalaire (nombre ou chaîne de caractères), tableau, ou hash. Ils peuvent être obligatoires ou optionnels. Voici un petit code d'exemple de passage d'arguments. Le prototypage est faite dans le composant appelé :

  <%args>
  $a
  @b       # des arguments obligatoires, de type scalaire, tableau ou hash
  %c
  $d => 5  # voici un argument scalaire optionnel, et sa valeur par défaut
  $e => $d * 2
  @f => ('foo', 'bar')
  %g => (joe => 1, bob => 2)
  $h => undef # optionnel, par défaut undef
  </%args>

Et @_ ?

Si vous n'aimez pas le passage de paramètres nommés, Il est toujours possible d'utiliser @_ :

  # côté appelant
  <& composant, 42, 'chaîne' &>

  # côté appelé
  my ($reponse, $chaine) = @_;

Le passage des arguments se fait par nom. $a, @b et %c sont des arguments obligatoires, de type scalaire, tableau et hash. $d est un argument scalaire optionnel, car il a une valeur par défaut définie, 5. $e est également optionnel, mais sa valeur par défaut est dépendante de $d. @f et %g sont des arguments optionnels, avec des valeurs par défaut. La définition des arguments est à mettre entre les balises <%args> et </%args>. Les variables ainsi définies peuvent être utilisées dans le reste du composant, et seront locales au composant. La règle a retenir est : un argument avec une valeur par défaut est optionnel, sinon il est obligatoire.

Du côté du composant appelant, voici comment passer des arguments :

  % <& composant, a => 5 &>
  % <& composant, b => ['une', 'référence', 'de', 'liste'] &>
  % <& composant, c => { un => 'hash', en => 'référence'} &>

Il est possible de faire appel à des fonctions avancées de passage d'arguments, comme utiliser @_ ou %ARGS directement, mais nous ne les aborderons pas ici, car elles sont plus rarement utilisées.

Nous avons vu précédemment qu'il est possible d'accéder à un composant directement par son URL. Bien sûr, il est possible de spécifier des arguments dans l'URL. Ainsi, pour appeler le composant navigation.html en lui passant un nom de page, nous utiliserons cette syntaxe :

  http://www.siteweb.com/navigation?page_courante=index

Voici comment passer en argument d'URL le tableau @b et le hash %c, vu ci-dessus :

  http://www.siteweb.com/composant?b=une&b=reference&b=de&b=liste
  http://www.siteweb.com/composant?c=un&c=hash&c=en&b=reference

Params::Validate

Ce style de passage d'argument est disponible en dehors de Mason grâce au module Params::Validate de Dave Rolsky (un des auteurs de Mason). Ce module permet de passer des arguments comme le fait Mason, et de les vérifier.

Le passage d'arguments dans Mason est simple et puissant, et couvre tout type de donnée. Comme dans la quasi-totalité des frameworks web modernes, il est également transparent, c'est à dire que le développeur web n'a pas à se soucier de la provenance des arguments, ni de leur récupération manuelle. Ainsi, comme il est facile de passer des arguments d'un composant à un autre, il est possible (et recommandé) de faire beaucoup de composants distincts, un par fonctionnalité.

Les sections spéciales

Définition

Il existe quelques balises spéciales en Mason, qui permettent de déclarer des sections à l'intérieur d'un composant. Les sections sont des blocs qui contiennent du Perl uniquement, qui sont donc exécutées dans un contexte particulier.

<%init>

Commençons par une section simple : <%init>. Le contenu de ce bloc sera interprété au début du composant, même si la section <%init> est définie à la fin du composant. C'est utile pour séparer l'initialisation de variables Perl, qu'on peut reléguer à la fin du composant, et le contenu HTML de la page, qu'il est préférable de présenter au début du composant. Voici un exemple de syntaxe de ce bloc :

  %# début du composant

  <html>
    <head>
      <title>titre</title>
    </head>
  <body>
  %# Contenu de la page, qui utilise des variables
  Bonjour, nous sommes le <% $day %> du mois.
  </body>
  </html>

  %# Section init, utilisée pour initialiser $day
  <%init>
    $day = (localtime(time))[3];
  </%init>

Dans cet exemple, la section <%init> évite d'avoir à écrire la ligne d'initialisation de $day au tout début du composant. On peut placer <%init> n'importe où dans le composant, on est sûr que son code sera interprété au début du composant. Les lecteurs avertis se demanderont s'il est possible d'avoir plusieurs sections <%init> dans un seul composant. La réponse est : oui, c'est possible, même si ce n'est pas conseillé. Dans le cas de plusieurs sections <%init>, le code sera interprété dans l'ordre des sections <%init>.

Il est utile de noter que <%init> est interprété à chaque appel du composant, contrairement à d'autres sections.

<%cleanup>

<%cleanup> est l'inverse de <%init>, son contenu est exécuté à la fin du composant. <%cleanup> est rarement utilisé, car les variables normales du composant sont détruites à la fin de celui-ci (on dit qu'elles sortent de la portée du composant). <%cleanup> est donc utile uniquement dans le cas où un traitement spécial est à effectuer à la fin, par exemple libérer une connexion à une base de données.

<%once>

<%once> est une section dont le contenu est exécuté une seule fois, à l'initialisation du composant. Apache crée plusieurs processus (ou des threads, selon sa configuration), pour répondre aux requêtes des utilisateurs du site web. Un composant est initialisé la première fois qu'il est demandé par un utilisateur, pour un processus donné. Une fois initialisé, le composant est précompilé, et mis en cache interne de Mason. <%once> permet d'exécuter du code Perl lors de cette initialisation. <%once> ne sera plus jamais appelé avant qu'un nouveau processus soit créé par Apache, ou que Apache soit redémarré.

Quelle est donc l'utilité de <%once> ? Cette section est très pratique pour déclarer des variables, qui seront valides pendant toute la durée de vie du processus, et qu'on pourra initialiser une seule fois. Par exemple, il est pratique d'utiliser conjointement <%init> et <%once> pour créer une connexion à une base de données permanente :

  <%once>
    # déclaration de l'objet database handler
    use DBI;
    my $db;
  </%once>
  
  %# Au début de l'appel du composant, on initialise $db si besoin

  <%init>
    if (!defined $db) {
      $db = DBI->connect('dbi:mysql:dbname=foobar');
    }
  </%init>

  %# $db est utilisable dans le composant

<%filter>

Dans une section <%filter>, la variable spéciale $_ contient le HTML final de la page, tel qu'il va être renvoyé. <%filter> permet donc de modifier le résultat final d'un composant : il suffit d'altérer $_. L'exemple suivant passe le HTML de la page en majuscule.

    <%filter>
    y/a-z/A-Z/;
    </%filter>

La section <%filter> est intéressante pour opérer une transformation sur le flux en sortie, sans se préoccuper de la manière dont il a été créé. Cependant cela peut nuire à la lisibilité et à la maintenabilité du code, car le fait de multiplier les interventions sur les données, dans des endroits différents du code, peut complexifier les processus.

Autres sections

<%shared>
Similaire à <%once>, mais les variables déclarées dans cette section ont leur portée limitée à la requête, et non au processus Apache.
<%def>
Permet de définir un sous-composant. La convention veut que les noms des sous-composants commencent par un point.
<%method>
Permet de définir une méthode du composant. Les méthodes seront expliquées dans le prochain article.
<%flags> et <%attr>
Permettent d'assigner des états ou attributs aux composants. Utilisés principalement dans la programmation objet (voir le prochain article).
<%doc>
Son contenu est traité comme des commentaires.

Exemple d'utilisation des sections

Voici un exemple concret d'utilisation des sections. Pour un développement web conséquent, il peut être important de soigner la forme du code HTML renvoyé. Notamment, un code HTML source bien indenté est utile pour repérer et comprendre les problèmes d'affichage d'une page web. Mais indenter du HTML dans un composant Mason n'est généralement pas possible : certaines portions d'HTML sont incorporées dans certains cas uniquement, on ne peut pas prévoir l'indentation avant que les pages ne soient générées totalement.

La solution est d'indenter le HTML à la volée, avant de le renvoyer vers le navigateur de l'internaute. Ce faisant, nous pouvons également en profiter pour analyser syntaxiquement le HTML grâce à un module ad-hoc ; si cet analyseur détecte des erreurs, les lignes incriminées peuvent être affichées en bas de page, en couleur.

Après une petite recherche sur CPAN, HTML::Tidy paraît l'outil idéal pour vérifier la syntaxe d'un source HTML, et l'indenter. Tout d'abord, il faut organiser le site pour que tous les composants héritent d'un composant racine, que nous appelons tidy.html. Cela peut se faire à l'aide d'un autohandler (voir plus bas), ou bien grâce à l'orienté objet (expliqué dans le prochain article). Ce composant indente et analyse le contenu avant qu'il ne soit retourné à l'internaute. Voici le code commenté. Il illustre l'utilisation des balises <%once>, <%init> et <%filter>.

  %# Nous allons utiliser un objet tidy valable pour toute la durée de vie du
  %# processus alloué par Apache. %once est idéal pour une telle déclaration
  
  <%once>
    # déclaration de l'objet d'indentation du code
    use HTML::Tidy;
    my $tidy;
  </%once>
  
  %# Au début de l'appel du composant, il nous faut affecter $tidy, s'il n'est
  %# pas déjà défini.

  <%init>
    # initialisation si besoin est, pour être fork-safe
    if (!defined $tidy) {
      $tidy = HTML::Tidy->new( { config_file => '/tmp/tidy.cfg' } );
    }
  </%init>

  %# On applique un filtre pour auto-indenter le html qui sort.
  %# Pour cela, on utilise la section %filter, qui est appelée en
  %# fin de calcul du composant.  
  <%filter>
    # récupération du HTML
    my $html = $_;
    # on nettoie la sortie du composant
    $html = $tidy->clean($html);
    
    # s'il y a des erreurs ou des avertissements, on les affiche à la fin
    if ($tidy->messages) {

	# récupération des erreurs ou avertissements
        my @messages = $tidy->messages();
        
        # On ajoute les erreurs et avertissements HTML à la fin du contenu
	# si le _type du message est à 1, c'est un warning, sinon une erreur
        $html .= '<br><br><hr size=2 noshade>html warnings/errors : <br>' .
          join("\n<br>", map  {
              ($_->{_type} ? 'warning : ' : 'error : ') . $_->as_string;
          } ($tidy->messages)) . '<br><br>';
    }

    $_ = $html;

    # on réinitialise l'objet tidy
    $tidy->clear_messages();
  
  </%filter>

Mason - Première partie

Chapeau

HTML::Mason : Introduction

Hello World !

Exemples de syntaxe

Commentaires

Condition

Boucle

Appel à un module Perl

Les différents intervenants

Configuration d'Apache

Mise en œuvre express

Configuration avancée

Paramètres de configurations

Tester la configuration

Les composants Mason

Description

Syntaxe

Appeler un composant

Passer des arguments

Les sections spéciales

Définition

<%init>

<%cleanup>

<%once>

<%filter>

Exemple d'utilisation des sections

`$r` et `$m` : Deux couteaux suisses

`$r`

`$m`

Les handlers

le dhandler

Autohandler

Conclusion

Liens

Auteur

Notes

Mason - Première partie

Chapeau

HTML::Mason : Introduction

Hello World !

Exemples de syntaxe

Commentaires

Condition

Boucle

Appel à un module Perl

Les différents intervenants

Configuration d'Apache

Mise en œuvre express

Configuration avancée

Paramètres de configurations

Tester la configuration

Les composants Mason

Description

Syntaxe

Appeler un composant

Passer des arguments

Les sections spéciales

Définition

<%init>

<%cleanup>

<%once>

<%filter>

Exemple d'utilisation des sections

$r et $m : Deux couteaux suisses

$r

$m

Les handlers

le dhandler

Autohandler

Conclusion

Liens

Auteur

Notes

`$r` et `$m` : Deux couteaux suisses

`$r`

`$m`