Gestion des labels

De Sydonie

Important : cette page a été rédigée pour la version antérieure de Sydonie et contient donc quelques imprécisions dues à l'absence des namespaces

Principes généraux

Pour gérer l'affichage des pages en diverses langues, Sydonie utilise des labels. Un label est un code auquel on associe un contenu qui sera fonction de la langue de l'interface que l'utilisateur a choisi.

Par exemple, on pourra avoir le label de code 'greetings' qui aura pour valeur "Bonjour" en français, "Hello" en anglais et "Buenos dias" en espagnol. La liste des labels disponibles est stockée dans divers fichiers XML. Les labels sont définis dans les packages, et sont donc utilisés dans un contexte d'exécution particulier en rapport avec le package utilisé. Les labels les plus généraux sont donc placés dans le package Abestract_SydonieBase et correspondent pour la plupart à des éléments d'interface indépendants de toute classe particulière (par exemple le texte générique d'un bouton submit).

Les labels sont chargés en mémoire suivant les mêmes principes qui sont utilisés pour le chargement des configurations de classe, de templates et de formulaires, c'est-à-dire en "remontant" la branche de dérivation des classes PHP et en utilisant la double cascade entre le site et Sydonie. Cela permet pour les labels de package de redéfinir certains labels.

Conventions d'écriture

Les codes de labels sont écrits en "camelCase" de façon à être compréhensibles uniquement par le code. Ils ne doivent PAS faire mention du package.

Managers de labels

Les labels sont gérés par un Manager : Manager_PackageConfig_Labels. Ce manager dispose de méthodes pour les interroger mais à priori ne sont pas utilisées directement (utiliser la méthode label() des templates).


Utilisation dans les templates

La méthode label($codeLabel) de la classe Ui recherche dans les labels de package de l'objet dont on utilise le Ui correspondant. L'héritage et la double cascades telle que Sydonie la définit (pour les config.xml des Packages par exemple) s'applique aussi pour les labels.

On utilisera donc par exemple : 

<li><?php echo $ui->label('view'); ?></li>

Utilisations de labels généraux

La fonction Aglae 
label('codeLabel')
affiche le label tel qu'il est défini dans la classe Abstract_SydonieBase, fichier labels.xml.

On peut donc l'utiliser en dehors de templates (dans les fragments ou les layouts). Mais il faut que les termes soient définis dans le fichier Sydonie/Abstract/SydonieBase/labels.xml

Dans le cas où le terme souhaité n'est pas défini dans ce fichier, on peut écrire dans le compte de l'application un fichier Abstract/SydonieBase/labels.xml qui sera utilisé. On peut également surcharger les labels existant à cet endroit si le terme de convient pas ou pour ajouter une traduction dans une autre langue (dans ce cas, ne mettre que la version dans la nouvelle langue au sein de l'application).

Algorithme de choix du label à afficher

Lorsqu'un label est demandé, il peut être demandé dans uen langue donnée : 

<li><?php echo $ui->label('view', 'de'); ?></li>

Lors de l'appel à un label, le Manager va chercher une valeur du label 'view' dans cet ordre :

  1. dans la langue demandée (s'il y en a une)
  2. dans la langue de l'interface
  3. dans les langues spécifiées dans les préférences du navigateur
  4. la langue par défaut du site
  5. si rien n'est trouvé, retourne le code du label. En mode 'TEMPLATE_DEBUG' ce code sera précédé de la mention 'undefined label'.

Pour faire des liens

L'utilisation de la fonction linkTo permet de faire un lien et prend en paramètre une instance ou un nom de classe, l'action à effectuer puis le code de label à utiliser pour le lien. La fonction ira alors chercher le texte correspondant au label. ATTENTION : le texte du label sera cherché dans les labels du package de la classe donnée en paramètre, et non des labels du package du template dans lequel la fonction est appelée.

Utilisation des labels par les formulaires

Lors de l'utilisation des templates par les formuaires, la gestion des Attribute est automatique. Prenons l'exemple d'une classe News qui possède les attributs managerEmail et contactEmail, tous les deux de type AttributeType_Email. Dans le formulaire, on trouve : 

<?php echo $ui->input('managerEmail'); ?>
<?php echo $ui->input('contactEmail'); ?>

Rappelons que l'objet AttributeType_Email contient un prédicat 'email'. Pour afficher l'input texte de l'adresse email ('email'), le label 'email' est utilisé. Cependant, il nous faut ici pouvoir différencier les 2 champs 'email' dans le formulaire, et ceci ne dépend pas de la classe AttributeType_Email mais de la classe News.

Dans ce cas, le système va alors hercher le texte à utiliser de la façon suivante, par ex. pour managerEmail :

  1. cherche si un label 'managerEmail.email' existe dans les labels de la classe News
  2. si non, utilise le label 'email' défini par défaut dans la classe AttributeType_Email
  3. si celui-ci n'existe pas, le code managerEmail.email est utilisé

Pour l'affichage des messages d'erreur, lescodes de label générs par le système sont de la forme errorCode@attributeName.propertyName.

Par exemple si le code d'erreur pour le champ email est invalidEmail alors le label 'invalidEmail@managerEmail.email' de la classe News sera utilisé. S'il n'existe pas, le label 'invalidEmail@email' de la classe AttributeType_Email sera utilisé puis le label 'invalidEmail'. Si aucun de ces labels n'existe alors 'invalidEmail@managerEmail.email' sera affiché.

Ce mécanisme permet de personnaliser tous les labels en fonction de la classe mais aussi en focntion de l'attribut.

Création des fichiers de labels

Les labels de classe sont dans le répertoire de chaque classe dans le fichier labels.xml. Les fichiers labels.xml qui sont dans Sydonie contiennent les labels par défaut. Ces labels peuvent être modifiés dans le site en ne redéfinissant que les labels à modifier.

La double cascade utilisée dans Sydonie s'applique aux fichiers de labels. Les labels les plus généraux sont donc placés dans le package Abstract_SydonieBase et correspondent pour la plupart à des éléments d'interface indépendants de toute classe particulière (par exemple le texte générique d'un bouton submit).

Exemple 1

<?xml version="1.0" encoding="utf-8" ?>
<tmx version="1.4">
   <header
      datatype="PlainText"
      segtype="sentence"
      creationtool="sydonie"
      creationtoolversion="1.0"
      srclang="en"
      o-encoding="utf-8"
      o-tmf="plaintext"
   >
      <note>Version de base créée à la main par jml</note>
   </header>
 
   <body>
      <tu tuid="title" srclang="en">
         <tuv xml:lang="en">
            <seg>Title</seg>
         </tuv>
         <tuv xml:lang="fr">
            <seg>Titre</seg>
         </tuv>
	<tuv xml:lang="de">
            <seg>Titel</seg>
         </tuv>
      </tu>
 
      <tu tuid="content" srclang="en">
         <tuv xml:lang="en">
            <seg>Content</seg>
         </tuv>
         <tuv xml:lang="fr">
            <seg>Contenu</seg>
         </tuv>
      </tu>
 
<!-- general document error labels -->
      <tu tuid="emptyField@title" srclang="en">
         <tuv xml:lang="en">
            <seg>Enter a title</seg>
         </tuv>
         <tuv xml:lang="fr">
            <seg>Saisir un titre</seg>
         </tuv>
      </tu>
 
<!-- here for the example (shouldn't be here) -->
      <tu tuid="SydonieGong.text" srclang="en">
         <tuv xml:lang="en">
            <seg>SydonieGong Identifier</seg>
         </tuv>
         <tuv xml:lang="en">
            <seg>Identifiant SydonieGong</seg>
         </tuv>
      </tu>
 
      <tu tuid="errorGong@SydonieGong.text" srclang="en">
         <tuv xml:lang="en">
            <seg>Invalid SydonieGong Identifier</seg>
         </tuv>
         <tuv xml:lang="en">
            <seg>Identifiant SydonieGong erroné</seg>
         </tuv>
      </tu>      
 
    </body>
</tmx>
</xml>

Exemple 2

Soit le fichier de configuration config.xml suivant pour une classe définit pour une application donnée : 

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <class>
        <name>SydonieDocument_Test</name>
        <extends>Abstract_SydonieDocument</extends>
        <mandatoryProp>
        </mandatoryProp>
    </class>
 
<attribute entityLevel="work"
           minOccur="1"
           maxOccur="1"
           mandatory="0">
  <predicate>workDate</predicate>
  <objectClass>AttributeType_Date</objectClass>
</attribute>
 
<attribute entityLevel="work"
           minOccur="1"
           maxOccur="1"
           mandatory="0">
  <predicate>workDateTime</predicate>
  <objectClass>AttributeType_DateTime</objectClass>
</attribute>
 
<attribute entityLevel="work"
           minOccur="1"
           maxOccur="1"
           mandatory="0">
  <predicate>workDateInterval</predicate>
  <objectClass>AttributeType_DateInterval</objectClass>
</attribute>
 
<attribute entityLevel="work"
           minOccur="1"
           maxOccur="1"
           mandatory="0">
  <predicate>workText</predicate>
  <objectClass>AttributeType_Text</objectClass>
</attribute>
 
<attribute entityLevel="work"
           minOccur="1"
           maxOccur="1"
           mandatory="0">
  <predicate>workInt</predicate>
  <objectClass>AttributeType_Int</objectClass>
</attribute>
 
<attribute entityLevel="work"
           minOccur="1"
           maxOccur="1"
           mandatory="0">
  <predicate>workComposite</predicate>
  <objectClass>AttributeType_Composite</objectClass>
</attribute>

Nous pouvons définir les labels pour ces attributs du package SydonieDocument_Test de la manière suivante, dans le fichier labels.xml à la racine du dossier contenant les informations de ce package (SYDONIE_SITE/Sydonie_Document/Test/) : 

<?xml version="1.0" encoding="utf-8" ?>
<!-- <!DOCTYPE tmx SYSTEM "../xml/tmx14.dtd"> -->
<tmx version="1.4">
   <header
      datatype="PlainText"
      segtype="sentence"
      creationtool="sydonie"
      creationtoolversion="1.0"
      srclang="en"
      o-encoding="utf-8"
      o-tmf="plaintext"
   >
   </header>
 
   <body>
    <tu tuid="workText.text" srclang="fr">
      <tuv xml:lang="en">
        <seg>Work :: text</seg>
      </tuv>
      <tuv xml:lang="fr">
        <seg>Work :: texte</seg>
      </tuv>
    </tu>
 
    <tu tuid="workDate.date" srclang="fr">
      <tuv xml:lang="en">
        <seg>Work :: date</seg>
      </tuv>
      <tuv xml:lang="fr">
        <seg>Work :: date</seg>
      </tuv>
    </tu>
 
    <tu tuid="workDateTime.dateTime" srclang="fr">
      <tuv xml:lang="en">
        <seg>Work :: date and time</seg>
      </tuv>
      <tuv xml:lang="fr">
        <seg>Work :: date et heure</seg>
      </tuv>
    </tu>
 
    <tu tuid="workDateInterval" srclang="fr">
      <tuv xml:lang="en">
        <seg>Work :: Interval (between two dates)</seg>
      </tuv>
      <tuv xml:lang="fr">
        <seg>Work :: Intervalle (entre deux dates)</seg>
      </tuv>
    </tu>
 
    <tu tuid="workDateInterval.begins" srclang="fr">
      <tuv xml:lang="en">
        <seg>Start</seg>
      </tuv>
      <tuv xml:lang="fr">
        <seg>Début</seg>
      </tuv>
    </tu>
 
    <tu tuid="workDateInterval.ends" srclang="fr">
      <tuv xml:lang="en">
        <seg>End</seg>
      </tuv>
      <tuv xml:lang="fr">
        <seg>Fin</seg>
      </tuv>
    </tu>
 
   </body>
</tmx>
Récupérée de « http://wiki.sydonie.net/index.php?title=Gestion_des_labels&oldid=1702 »