Outils pour utilisateurs

Outils du site


Panneau latéral

ref:docs:declarer_un_document

Déclarer un document

Déclarer le document docName du module moduleName se fait dans le fichier modules/<moduleName>/persistentdocument/<docName>.xml. Ce fichier permet la déclaration des propriétés du document. La commande change.php create-document permet d'initialiser le fichier de déclaration.

Structure du fichier de déclaration

Le fichier de déclaration d'un document est un fichier XML dont le schéma est http://www.rbschange.fr/static/schema/change-document/1.0.xsd :

<?xml version="1.0" encoding="utf-8"?>
<document xmlns="http://www.rbs.fr/schema/change-document/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.rbs.fr/schema/change-document/1.0 http://www.rbschange.fr/static/schema/change-document/1.0.xsd"
    model-version="1.0">
  <properties />
  <serializedproperties />
  <children />
  <statuses />
</document>

Attributs de l'élément <document />

L'élément racine document accepte les attributs suivants :

Nom Obligatoire Défaut Valeurs possibles Description
backoffice-indexable Non “true” “true” ou “false” indique si le document est indexable ou non (pour la recherche en backoffice)
extend Non modules_generic/Document modules_<nomModule>/<nomDocument> le document étendu
has-url Non “true” “true” ou “false” le document a une URL qui lui est propre sur un site web (impacts sur : plan du site, indexation front, onglet URL, picker “has-url”)
icon Non NA <nomIcone> le nom de l'icône utilisée
indexable Non “false” “true” ou “false” indique si le document est indexable ou non (pour la recherche en frontoffice)
inject Non “false” “false” ou “true” N'a de sens que si extend est défini. Si vaut true, alors le document remplace son parent. Voir Extension du code existant Change
localized Non “false” “false” ou “true” déclare le document multilingue
linked-to-root-module 1) Non “false” “true” ou “false” lors de l'insertion et si aucun parent n'est indiqué, choisit le dossier racine de l'arbre du module pour parent
model-version Oui NA “x.y”, où x et y sont des entiers naturels identifie la version du modèle 2)
publish-on-day-change Non “true” “true” ou “false” les documents marqués publish-on-day-change sont régulièrement analysés pour déterminer s'il doivent être publiés ou dé-publiés. L'événement hourChange sert de déclencheur à cette analyse 3)
table-name Non mod_<nomModule>_doc_<nomDocument> libre, doit être compatible avec le SGBD utilisé nom de la table SQL utilisée
use-correction Non “false” “false” ou “true” le document gère les corrections

Propriétés d'un document

Une propriété a un nom, un type, des contraintes, … elle se traduit souvent par une colonne d'une table de la base de données et par une propriété de l'objet Document. Cette traduction est prise en charge par Change, lors de la compilation des documents (change.php compile-documents) notamment.

Types

On peut distinguer deux grand types de propriétés :

  • Les propriétés scalaires, qui stockent des valeurs simples (chaînes de caractères, nombres, …)
  • Les propriétés Document, qui stockent des liens vers d'autres documents

Propriété scalaire

Les propriétés scalaires sont représentées par un élément <add /> de la section <properties />. Dans l'extrait suivant, nous déclarons la propriété myProperty de type String :

<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://www.rbs.fr/schema/change-document/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.rbs.fr/schema/change-document/1.0 http://www.rbschange.fr/static/schema/change-document/1.0.xsd" 
  model-version="1.0">
  <properties>
    <add name="myProperty" type="String" />
  </properties>
</document>

Les propriétés scalaires peuvent être des types suivants :

Type Usage Champ de formulaire associé Représentation MySQL
Boolean Oui/Non Champ type <input type=“radio” /> tinyint(1)
DateTime Date Calendrier datetime
Double Décimal (float) Champ type <input type=“text” />, avec contraintes double
Integer Entier signé Champ type <input type=“text” />, avec contraintes int(11)
Lob Chaîne de caractère très longue Champ type <input type=“text” /> mediumtext
LongString Chaîne de caractère longue Champ type <textarea /> text
String Chaîne de caractère courte Champ simple type <input type=“text” /> varchar(255)
XHTMLFragment Fragment d'un document HTML Editeur XHTML Wysiwyg mediumtext

Les attributs de l'élément <add /> sont les suivants :

Nom Obligatoire Défaut Valeurs possibles Description
name Oui NA libre à l'exception de certains Mots réservés nom de la propriété
type Oui NA type de la propriété. Obligatoire lorsque que c'est une définition de propriété et non une définition complémentaire suite à l'héritage
min-occurs Non 0 Entier naturel nombre d'occurrence minimal requis de la propriété
db-mapping Non @name String, compatible avec le SGBD nom du champ utilisé pour stocker la propriété dans la table
db-size Non NA Entier naturel taille maximale de stockage prévue pour la propriété
localized Non “false” “true”, “false” indique si la propriété peut être traduite
from-list Non NA Identifiant de liste du module list la propriété prend ses valeurs dans la liste désignée
default-value Non NA Selon le type de la propriété valeur par défaut de la propriété

Propriété Document

Tout comme les propriétés scalaires, les propriétés Document sont représentées par un élément <add /> de la section <properties />.

Le type peut être :

  • modules_generic/Document : n'importe quel type de document,
  • modules_<moduleName>/<documentName> : le document <documentName> du module <moduleName>. Exemple : modules_blog/post, un billet du module blog.

Les propriétés Document sont stockées sous la forme d'entiers (les identifiants) dans la table f_relation.

En plus des attributs d'une propriété scalaire 4), les propriétés document supportent les attributs suivants :

Nom Obligatoire Défaut Valeurs possibles Description
cascade-delete Non “false” “true”, “false” Indique si les documents liés doivent être supprimés lors de la suppression du document
inverse Non “false” “true”, “false” génère une méthode dans le document cible de la relation permettant de requêter la relation "à l'envers".
max-occurs Non 1 Entier naturel ou “-1” nombre d'occurrence maximal de la propriété
tree-node Non “false” “true”, “false” déclare le document comme potentiel “parent” des documents liés

Nombre d'occurrence d'une propriété document

Par défaut, la propriété n'accepte qu'un et un seul document, pour permettre le stockage de plusieurs documents, vous devez utiliser l'attribut max-occurs, de type entier. Celui-ci vaudra n pour stocker au plus n documents et -1 pour un nombre indéterminé de documents.

Dans l'extrait suivant,

  • La propriété posts stocke un nombre indéterminé de documents post du module blog
  • La propriété favoriteposts stocke au plus 10 documents du même type
<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://www.rbs.fr/schema/change-document/1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://www.rbs.fr/schema/change-document/1.0 http://www.rbschange.fr/static/schema/change-document/1.0.xsd" 
  model-version="1.0">
  <properties>
    <add name="posts" type="modules_blog/post" max-occurs="-1" />
    <add name="favoriteposts" type="modules_blog/post" max-occurs="10" />
  </properties>
</document>

Propriété tree-node

La propriété tree-node permet d'enregistrer un document dans une arborescence virtuelle d'un module. Les intérêts d'une arborescence virtuelle sont multiples :

  • multi-implantation
  • permet de diminuer l'impact de la gestion arborescente lorsque l'on a une volumétrie importante
  • permet d'éviter les problèmes de fuseau lorsque l'on souhaite avoir une arborescence par date (non applicable à l'attribut tree-node)

Lorsque tree-node vaut true cela implique :

  • au save, avant l'enregistrement dans l'arbre d'un document, on va regarder s'il existe une propriété de type tree-node compatible soit sur le document lui-même (elle doit alors être inverse) soit sur son parent
  • quand on utilise ce mécanisme, il faut ajouter dans le preInsert du service du document la ligne $document→setInsertInTree(false); pour qu'il ne soit pas ajouté dans l'arbre
  • dans la perspective il faut ensuite déclarer au niveau de l'élément child l'attribut from valant le nom de la propriété tree-node

Plus d'information sur la manière de récupérer l'arborescence virtuelle dans la méthode getVirtualChildren() dans modules/generic/actions/GetTreeChildrenJSONAction.class.php

Propriété sérialisée

Lorsque les propriétés n'ont pas spécialement besoin d'être requêtées, vous pouvez faire le choix de la propriété sérialisée. La propriété n'a alors pas de colonne dédiée en base : elle est stockée sérialisée dans une unique colonne dédiée à l'ensemble des propriétés sérialisées.

Pour déclarer une propriété sérialisée, placez l'élément <add /> dans la section <serializedproperties />.

Dans l'extrait suivant, nous déclarons deux propriétés sérialisées : aStringSer et aPageSer

<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://www.rbs.fr/schema/change-document/1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.rbs.fr/schema/change-document/1.0 http://www.rbschange.fr/static/schema/change-document/1.0.xsd"
    model-version="1.0">
  <serializedproperties>
    <add name="aStringSer" type="String"/>
    <add name="aPageSer" type="modules_website/page"/>
  </serializedproperties>
</document>

Limitations des propriétés sérialisées

  • Non requêtable
  • Non traductibles
  • Non héritées

Résumé

Le tableau suivant résume les grands choix possibles :

“Catégorie” de propriété Usage Requêtable
Scalaire stockage de valeurs simples : chaînes de caractères, nombres, … oui
Document stockage d'un ou plusieurs documents d'un type donné oui
Sérialisée stockage de valeurs simples ou document non

Contraintes

Les éléments <add /> acceptent comme fils l'élément <constraints /> qui permet de définir les règles de validation de la propriété. Ces règles seront vérifiées avant sauvegarde du document.

Les contraintes font appels à des validateurs et sont définies sous la forme d'une chaîne de caractères du type : <nomValidateur>:<paramètreValidateur>;<nomValidateur2>:<paramètreValidateur2>…. Ainsi la chaîne unique:true;email:true fait appel à deux validateurs, unique et email, auxquels ont été transmis le paramètre true.

N.B : la contrainte obligatoire est gérée par l'attribut min-occurs, que l'on définit à une valeur supérieure strictement à 0.

Ci-dessous, la liste des validateurs du framework (Cf. framework/validation/*Validator.php) :

Nom validateur Valeur possible du paramètre Implication
beginsWith Chaîne de caractères La valeur (chaîne) doit commencer par la chaîne transmise en paramètre
email Booléen : true ou false Si true, la valeur doit être une adresse e-mail valide
endsWith Chaîne de caractères La valeur doit se terminer par la chaîne transmise en paramètre
float Booléen : true ou false Si true, la valeur doit être un nombre décimal
host Booléen : true ou false Si true, la valeur doit être un nom d'hôte valide, incluant le protocole (http://mon.serveur.com)
inList Liste de chaînes : [“Fred”,“Bob”,“James”] La valeur doit être une valeur parmi celles listées
integer Booléen : true ou false Si true, la valeur doit être un nombre entier
matches Expression rationnelle déprécié depuis la version 3.6.4. La valeur doit valider l'expression rationnelle indiquée. L'expression rationnelle peut être suivie d'un # pour délimiter une clé de locale utilisée pour le message d'erreur
regexp Expression rationnelle depuis 3.6.4. La valeur doit valider l'expression rationnelle indiquée. L'expression rationnelle doit être délimitée et peut être suivie d'une clé de locale utilisée pour le message d'erreur
max Nombre La valeur ne doit pas être supérieure à <Nombre>
maxSize Nombre entier La valeur doit avoir une taille maximale de <Nombre entier> éléments
min Nombre La valeur ne doit pas être inférieure à <Nombre>
minSize Nombre entier La valeur doit avoir une taille minimale de <Nombre entier> éléments
notEqual Chaîne La valeur ne doit pas être égale à <Chaîne>
nullable true ou false Si true, la valeur ne peut pas être null
password low, medium, high La valeur doit être un mot de passe valide, conformément au niveau de sécurité indiqué
range Intervalle : n1..n2 La valeur doit être comprise entre <n1> et <n2>
size Nombre (n) ou Intervalle (n1..n2) La valeur doit avoir une taille de <n> éléments ou une taille comprise entre <n1> et <n2> éléments
unique Booléen : true ou false La valeur doit être unique pour ce champ parmi tous les documents de même type
url Booléen : true ou false La valeur doit être une URL valide (#ancres acceptées)

Exemples

Exemple 1 : persistentdocument/frontenduser.xml

<?xml version="1.0"?>
<document model-version="1.0" extend="modules_users/user" icon="users3">
  <properties>
    <add name="login">
      <constraints>unique:true;email:true</constraints>
    </add>
  </properties>
</document>

Dans cet exemple, deux contraintes ont été spécifiées :

  • unique:true : la contrainte unique avec paramètre true
  • email:true : la contrainte email avec paramètre true

Exemple 2 :

<?xml version="1.0"?>
<document model-version="1.0" extend="modules_generic/Document" icon="money">
  <properties>
    <add name="discount">
      <constraints>matches:^[0-9]+%?$</constraints>
    </add>
  </properties>
</document>

Dans cet exemple, une contrainte a été spécifiée : * matches:^[0-9]+%?$ : la contrainte sur la propriété discount accepte soit un entier soit un pourcentage.

Héritage

Les documents peuvent hériter (au sens Orienté Objet du terme) d'un autre document (Cf. attribut ''extend'' de l'élément document). Lorsque un document hérite d'un autre, la classe PHP le représentant hérite de la classe du document père et les propriétés additionnelles sont stockées dans la table SQL du père.

Par défaut, un document hérite du document generic/Document qui définit les propriétés suivantes :

Nom Type Description
label String libellé du document
author String auteur du document, renseigné automatiquement
authorid Integer identifiant de l'auteur. Lien faible, renseigné automatiquement
creationdate DateTime date de création, renseignée automatiquement
modificationdate DateTime date de dernière modification, renseignée automatiquement
publicationstatus String statut de publication du document
lang String Langue du document (format ISO-639)
modelversion String version du modèle du document
documentversion Integer Numéro de révision du document, renseigné automatiquement
startpublicationdate DateTime Date de début de publication
endpublicationdate DateTime Date de fin de publication
metastring LongString Métadonnées du document

Statut de publication

Le statut de publication attribué à la création d'un document se règle dans la section <statuses /> du fichier de déclaration, la valeur par défaut étant DRAFT.

Dans l'exemple suivant, nous choisissons de positionner le statut de publication à ACTIVE dès la création du document :

<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://www.rbs.fr/schema/change-document/1.0" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.rbs.fr/schema/change-document/1.0 http://www.rbschange.fr/static/schema/change-document/1.0.xsd"
   model-version="1.0">
  <properties>
     ...
  </properties>
  <statuses default="ACTIVE" />
</document>

N.B. : même si aucun code ne vérifie cela, les valeurs cohérentes sont DRAFT (valeur par défaut) ou ACTIVE. Pour plus détails, voyez le cycle de publication des documents.

Multilinguisme

Un document multilingue (ou localisé) est un document dont au moins une des propriétés peut être traduite dans une des langues du projet. Une propriété est traductible lorsque son l'attribut localized vaut true.

Le libellé d'un document multilingue est toujours traductible : la propriété (label) est implicitement localisée, lorsque l'attribut localized du document vaut true ou lorsqu'une autre propriété est localisée.

Les propriétés Document ne peuvent être traduites : c'est le document lié qui est éventuellement traduit, s'il est multilingue.

Pour en savoir plus, consultez gestion du multilinguisme.

1)
nommage historique : en fait, la propriété désigne linked-to-root-folder
2)
Cette version n'est qu'informative, aucun code ne vérifie ou s'appuie sur cette valeur
3)
historiquement, il s'agissait de dayChange
4)
l'attribut localized n'est valable que pour les propriétés scalaires. Cf. multilinguisme.
ref/docs/declarer_un_document.txt · Dernière modification: 2017/01/19 14:54 (modification externe)