6.4 Vue d'attribut

Les vues d'attribut permettent de définir la représentation d'un attribut. Elles peuvent être utilisées lorsque la représentation par défaut du document correspond, à l'exception de quelques attributs isolés.

Les vues d'attributs sont déclarées au moyen des options :

  • viewtemplate : pour les vues de consultation,
  • edittemplate : pour les vues de modification.

Une vue d'attribut est composée de :

  • un fichier de template, définissant la structure,
  • une méthode (appelée contrôleur de vue) du document à représenter, définissant les valeurs.
    Cette méthode peut également être omise. dans ce cas, dynacase fait appel au contrôleur de vue par défaut.

Par convention :

  • le fichier de template porte l'extension .xml,
  • son nom détermine le nom de la vue,
  • la méthode associée doit porter le même nom.
    L'objet Layout est accessible au moyen de la propriété lay de l'objet courant ($this->lay).

6.4.1 Le contrôleur de vue d'attribut

Pour qu'une méthode du document soit utilisable en tant que contrôleur d'une vue, il est nécessaire de lui ajouter la phpDoc @templateController afin de se prémunir d'une éventuelle exécution arbitraire de code.

Les paramètres reçus par la méthode sont au nombre de 3 :

  • $target (string) : nom de la fenêtre graphique qui est utilisée pour les hyperliens ("_self" par défaut) ,
  • $ulink (booléen) : indique s'il faut générer les hyperliens (true par défaut) ,
  • $abstract (booléen) : indique s'il faut générer uniquement les attributs de la fiche résumé (false par défaut).

6.4.1.1 Contrôleur d'attributs par défaut

En l'absence de méthode correspondant à la vue, le contrôleur d'attributs par défaut est appelé. Cette méthode dépend de l'option :

  • viewtemplate : en consultation, la méthode appelée est Doc::viewDefaultCard,
  • edittemplate : en modification, la méthode appelée est Doc::viewProp suivi de Doc::editAttr.

6.4.2 Syntaxe d'une zone de vue d'attribut

Une zone de vue d'attribut s'exprime sous la forme APP:DOCVIEW:OPTIONS :

APP (obligatoire)
Le nom de l'application dans laquelle se trouve le template.
DOCVIEW (obligatoire)
La nom du template et du contrôleur à utiliser.
OPTIONS (facultatif)

Une option de représentation. ces options dépendent du type de vue :

Des paramètres supplémentaires peuvent être fournis en utilisant une syntaxe identique aux paramètres des URL. Les valeurs des paramètres doivent être encodés comme les URL (l'utilisation de la fonction urlencode est recommandée).
La syntaxe complète avec les paramètres est donc : APP:DOCVIEW:OPTIONS?param1=valeur1[&param=valeur]*.
Ces paramètres supplémentaires sont accessibles depuis le contrôleur avec la fonction getHttpVars().

Le couple APP:DOCVIEW indique le template et le contrôleur à utiliser.

  • Le fichier template est recherché avec la logique suivante :
    1. Si DOCVIEW ne comporte pas d'extension, alors l'extension .xml est ajoutée.
    2. Le fichier template est recherché par la fonction getLayoutFile dans le répertoire APP/Layout.
      1. Le fichier est d'abord recherché avec le nom DOCVIEW tel qu'il est décrit
      2. Si le fichier n'est pas trouvé, le nom en minuscule est recherché.
  • Le nom de la méthode est le nom DOCVIEW.
    Dans ce cas, la casse du nom de la méthode n'est pas prise en compte (comme pour les méthodes de PHP en général).

6.4.3 Vue de consultation d'attribut

La vue d'attribut remplace la valeur d'un attribut.

Elle s'insère à la place de la valeur d'un attribut depuis la zone FDL:VIEWBODYCARD.

Extrait d'une consultation de document avec la zone FDL:VIEWBODYCARD :

<table>
    <tr>
       <td>Label 1</td>
       <td>:</td>
       <td>valeur 1</td>
    </tr>
    <tr>
       <td>Label 2</td>
       <td>:</td>
       <td>valeur 2</td>
    </tr>
</table>

Afin de spécifier la vue d'attribut à utiliser en consultation, il faut utiliser l'option viewtemplate. Si l'attribut n°2 a une vue d'attribut le document de consultation est :

<table>
    <tr>
       <td>Label 1</td>
       <td>:</td>
       <td>valeur 1</td>
    </tr>
    <tr>
       <td>Label 2</td>
       <td>:</td>
       <td>ICI LE RESULTAT DE LA VUE D'ATTRIBUT</td>
    </tr>
</table>

La vue d'attribut est présentée dans une cellule de tableau HTML comme représenté ci-dessous.
Label1 : Valeur1
Label2 : ICI LE RESULTAT DE LA VUE D'ATTRIBUT

Si l'option est portée sur un attribut tableau (array), la vue remplace tout le tableau.

Si l'option est portée sur un attribut cadre (frame) la vue remplace tout le contenu du cadre mais le contour avec le libellé est conservé.

6.4.3.1 Options des vues d'attribut en consultation

Les options disponibles en consultation sont les suivantes :

S

signifie que le libellé de l'attribut n'est pas affiché et le template prend toute la largeur du document. Cette option n'est pas applicable si l'attribut est de type frame.

Dans ce cas le document de consultation est :

<table>
     <tr>
       <td>Label 1</td>
       <td>:</td>
       <td>valeur 1</td>
    </tr>
    <tr>
       <td colspan="3">ICI LE RESULTAT DE LA VUE D'ATTRIBUT POUR L'ATTRIBUT N°2</td>
    </tr>
</table>

La vue d'attribut avec l'option S est présentée dans une cellule de tableau HTML comme représenté ci-dessous :

Label 1 : valeur 1
ICI LE RESULTAT DE LA VUE D'ATTRIBUT
POUR L'ATTRIBUT N°2

6.4.3.2 Utilisation des valeurs du document en consultation

Le contrôleur par défaut fait automatiquement appel aux méthodes Doc::viewAttr et Doc::viewProp. Elles initialisent les clés suivantes :

  • viewAttr va créer :
    • L_ATTRID pour chaque attribut : le libellé (traduit) de l'attribut,
    • V_ATTRID pour chaque attribut : la valeur (au format html) de l'attribut,
    • S_ATTRID pour chaque attribut : true si l'attribut est vide, false sinon
  • viewProp va créer :
    • ATTRID pour chaque attribut : la valeur brute de l'attribut
    • PROPID pour chaque propriété : la valeur brute de la propriété
    • V_TITLE une ancre vers le document lui-même avec son titre

Note : Toutes ces clefs sont en majuscules.

Lors de l'utilisation d'un contrôleur personnalisé, il est possible d'appeler ces méthodes afin de générer les clés correspondantes. Il est également possible de définir d'autres clés en utilisant les différentes méthodes du Layout.

Attention : Toutes ces clés respectent les visibilités : si la visibilité d'un attribut est H pour un utilisateur, les clés L_ATTRID et V_ATTRID seront des chaînes vides. S_ATTRID, pour sa part, n'est pas affecté par les visibilités.

Exemple d'un template d'attribut sans contrôleur :

MYAPP/Layout/mySpecialText.html
<h2>
    La valeur de [L_MY_TEXT] est <strong>[V_MY_TEXT]</strong>
</h2>

Dans cet exemple le template est associé à l'attribut MY_TEXT avec l'option viewtemplate=MYAPP:mySpecialText.html.

6.4.3.3 Utilisation d'un contrôleur d'attribut spécifique

Le contrôleur d'attribut est identique à un contrôleur de vue de documents.

La seule différence est qu'il ne contrôle qu'un attribut ou un ensemble d'attributs dans le cas d'un tableau ou d'un cadre.

Exemple :

Class.MyFamily.php
namespace My;
class MyFamily extends \Dcp\Family\Documents {
  /**
   * Affiche le nombre sur 3 chiffres
   * @templateController affichage en rouge si négatif, en vert sinon
   */
  public function mySpecialNumber($target = "_self", $ulink = true, $abstract = false)
  {
      $number=$this->getRawValue("my_number");
      if ($number > 0) {
          $this->lay->set("color", "green");
      } else {
          $this->lay->set("color", "red");
      }  
      $this->lay->set("theNumber", sprintf("%.03d",$number));
  }
}
MYAPP/Layout/mySpecialNumber.html
<h2>  La valeur est   
    <strong style="color:[color]">[theNumber]</strong>
</h2>

Dans cet exemple le template est associé à l'attribut MY_NUMBER avec l'option viewtemplate=MYAPP:mySpecialNumber.html. La méthode mySpecialNumber() est déclarée dans le fichier CLASS de la famille.

6.4.4 Vue de modification d'attribut

La vue d'attribut remplace le champ de saisie d'un attribut du formulaire.

Elle s'insère à la place de la valeur d'un attribut depuis la zone FDL:EDITBODYCARD.

Extrait d'un formulaire de document avec la zone FDL:EDITBODYCARD :

<table>
    <tr>
       <td>Label 1 :</td>
       <td><input value="Value 1"/> …</td>
       <td><input type="button"/> aide à la saisie/ extra link </td>
    </tr>
</table>
<table>
    <tr>
       <td>Label 2</td>
       <td><input value="Value 2">…</td>
       <td><input type="button"/> aide à la saisie/ extra link </td>
    </tr>
</table>

Afin de spécifier la vue d'attribut à utiliser en modification, il faut utiliser l'option edittemplate.

La vue d'attribut remplace le champ de saisie de l'attribut.

Si l'attribut n°2 a une vue d'attribut le formulaire de saisie est :

<table>
    <tr>
       <td>Label 1 :</td>
       <td><input value="Value 1"/>…</td>
       <td><input type="button"/> aide à la saisie/ extra link </td>
    </tr>
</table>
<table>
    <tr>
       <td>Label 2</td>
       <td>ICI LE RESULTAT DE LA VUE D'ATTRIBUT</td>
    </tr>
</table>

La vue d'attribut est présentée dans une cellule de tableau HTML comme représenté ci-dessus. Le template d'un champ doit retourner deux éléments :

  • le champ de saisie,
  • les éventuelle boutons de contrôle.

Ces éléments doivent être séparé par des éléments de cellule </td><td>, car au final le tableau doit comporter trois colonnes pour avoir un alignement correct.

6.4.4.1 Options des vues d'attribut en modification

Les options disponibles en modification sont les suivantes :

S

Signifie que le libellé de l'attribut ne est pas affiché et le template prend toute la largeur du document.

L'insertion se fait dans le fragment html suivant :

<table>
    <tr>
       <td>Label 1 :</td>
       <td><input value="Value 1"/> ...</td>
       <td><input type="button"/> aide à la saisie/ extra link </td>
    </tr>
</table>
<table>
    <tr>
       <td colspan="3">ICI LE RÉSULTAT DE LA VUE D'ATTRIBUT </td>
    </tr>
</table>
U

Signifie que l'input généré par le mot-clef [V_ATTRNAME] prend toute la largeur disponible. Elle n'ajoute pas de </td><td> supplémentaire. Cette option est à utiliser si les mots-clefs [V_ATTRNAME] sont présents dans le template.

<table>
    <tr>
       <td>Label 1 :</td>
       <td><input value="Value 1"/> ...</td>
       <td><input type="button"/> aide à la saisie/ extra link </td>
    </tr>
</table>
<table>
    <tr>
       <td>Label 2 :</td>
       <td>RÉSULTAT DE LA VUE SANS AUTRE TD : Tableau à 2 cellules</td>
    </tr>
</table>

6.4.4.2 Utilisation des valeurs du document en modification

le contrôleur par défaut fait automatiquement appel aux méthodes Doc::editAttr et Doc::viewProp. Elles initialisent les clés suivantes :

  • editAttr va créer :
    • L_ATTRID pour chaque attribut : le libellé (traduit) de l'attribut, entouré d'une balise <b/> si l'attribut est obligatoire),
    • V_ATTRID pour chaque attribut : un input pour l'attribut,
    • W_ATTRID pour chaque attribut : true si l'attribut est visible, false sinon.
  • viewProp va créer :
    • ATTRID pour chaque attribut : la valeur brute de l'attribut
    • PROPID pour chaque propriété : la valeur brute de la propriété
    • V_TITLE une ancre vers le document lui-même avec son titre

Lors de l'utilisation d'un contrôleur personnalisé, il est possible d'appeler ces méthodes afin de générer les clés correspondantes. Il est également possible de définir d'autres clés en utilisant les différentes méthodes du Layout.

Les clefs V_ATTRID fournies par Doc::editattr() retournent par défaut les 2 élements champ de saisie et boutons de contrôle séparés par </td><td> pour une insertion dans le formulaire. La méthode Doc::editAttr() possède un argument qui permet d'omettre le séparateur </td><td> pour des constructions de vues plus spécialisées.

Attention : toutes ces clés respectent les visibilités : si l'utilisateur n'a pas le droit de voir un attribut, la clé V_ATTRID génère un <input type="hidden"/>. Les clés L_ATTRID ne sont pas affectées par la visibilité. Exemple :

Class.MyFamily.php
 
namespace My;
class MyFamily extends \Dcp\Family\Documents {
  /**
   * Affiche le nombre sur 3 chiffres
   * @templateController affichage en rouge si négatif, en vert sinon
   */
  public function myEditSpecialNumber($target = "_self", $ulink = true, $abstract = false)
  {
      $this->editAttr();
  }
}
MYAPP/Layout/myEditSpecialNumber.html
  Nombre à saisir
    [V_MY_NUMBER]
 

Dans ce cas le résultat est :

<table>
    <tr>
       <td>Label 1 :</td>
       <td><input value="Value 1"/> ...</td>
       <td><input type="button"/> aide à la saisie/ extra link </td>
    </tr>
</table>
<table>
    <tr>
       <td>My number</td>
       <td>Nombre à saisir <input name=_"my_number" value="45"/></td><td></td>
    </tr>
</table>

Ce qui donne la représentation suivante :

Label 1 :
My number Nombre à saisir

6.4.5 Limitations

Les vues d'attribut ne sont pas gérées par Dynacase dans les vues de document personnalisées. Elles ne sont utilisées que dans les vues FDL:VIEWBODYCARD pour la consultation et FDL:EDITBODYCARD pour la modification.

Chaque vue d'attribut utilise la même instance de l'objet Doc correspondant au document en cours de consultation ou de modification.

Les vues d'attributs ne sont pas applicables aux attributs de type tab, ni aux attributs insérés dans un tableau. Dans ce dernier cas, il faut utiliser une vue de tableau.

Source : representations/vue_d_attribut.md Dynacase Platform 3.2 | Core Manuel de référence, version 3.2 édition 13, © Anakeen Labs <labs@anakeen.com>
×
Publié sous licence CC (http://creativecommons.org/licenses/by-nc-sa/2.0/fr/) par Anakeen [www.anakeen.com]
Attribution Vous devez créditer l'Oeuvre, intégrer un lien vers la licence et indiquer si des modifications ont été effectuées à l'Oeuvre. Vous devez indiquer ces informations par tous les moyens possibles mais vous ne pouvez pas suggérer que l'Offrant vous soutient ou soutient la façon dont vous avez utilisé son Oeuvre.
Pas d’Utilisation Commerciale Vous n'êtes pas autoriser à faire un usage commercial de cette Oeuvre, tout ou partie du matériel la composant.
Partage dans les Mêmes Conditions Dans le cas où vous effectuez un remix, que vous transformez, ou créez à partir du matériel composant l'Oeuvre originale, vous devez diffuser l'Oeuvre modifiée dans les même conditions, c'est à dire avec la même licence avec laquelle l'Oeuvre originale a été diffusée.