diff -r c243c0f65f17 -r 2b3fa6fb647b doc/book/fr/07-01-define-entities.fr.txt --- a/doc/book/fr/07-01-define-entities.fr.txt Thu Oct 14 00:01:04 2010 +0200 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,168 +0,0 @@ -.. -*- coding: utf-8 -*- - -Paramétrages et extensions spécifiques --------------------------------------- - -Valeurs par défaut dynamiques -````````````````````````````` -Il est possible de définir dans le schéma des valeurs par défaut *statiques*. -Il est également possible de définir des valeurs par défaut *dynamiques* en -définissant sur la classe d'entité une méthode `default_` pour -un attribut donnée. - - -Contrôle des attributs chargés et du tri par défaut -``````````````````````````````````````````````````` -* l'attribut de classe `fetch_attrs` permet de définir sur une classe d'entité - la liste des noms des attributs ou relations devant être chargés - automatiquement lors de la récupération d'entité(s) de ce type. Dans le cas - des relations, on est limité aux relations *sujets de cardinalité `?` ou `1`*. - -* la méthode de classe `fetch_order(attr, var)` prend en argument un nom - d'attribut (ou de relation) et un nom de variable et doit retourner une chaine - à utiliser dans la close "ORDERBY" d'une requête RQL pour trier - automatiquement les listes d'entités de ce type selon cet attribut, ou `None` - si l'on ne veut pas de tri sur l'attribut passé en argument. Par défaut les - entités sont triées selon leur date de création - -* la méthode de classe `fetch_unrelated_order(attr, var)` est similaire à la - méthode `fetch_order` mais est utilisée essentiellement pour contrôler le tri - des listes déroulantes permettant de créer des relations dans la vue d'édition - d'une entité - -La fonction `fetch_config(fetchattrs, mainattr=None)` permet de simplifier la -définition des attributs à précharger et du tri en retournant une liste des -attributs à précharger (en considérant ceux de la classe `AnyEntity` -automatiquement) et une fonction de tri sur l'attribut "principal" (le 2eme -argument si spécifié ou sinon le premier attribut de la liste `fetchattrs`). -Cette fonction est définie dans le package `ginco.entities`. - -Par exemple : :: - - class Transition(AnyEntity): - """...""" - id = 'Transition' - fetch_attrs, fetch_order = fetch_config(['name']) - -Indique que pour le type d'entité "Transition" il faut précharger l'attribut -"name" et trier par défaut selon cet attribut. - - -Contrôle des formulaires d'édition -`````````````````````````````````` -Il est possible de contrôler les attributs/relations dans la vue d'édition -simple ou multiple à l'aide des *rtags* suivants : - -* `primary`, indique qu'un attribut ou une relation doit être incorporé dans - les formulaires d'édition simple et multiple. Dans le cas d'une relation, - le formulaire d'édition de l'entité liée sera inclus dans le formulaire - -* `secondary`, indique qu'un attribut ou une relation doit être incorporé dans - le formulaire d'édition simple uniquement. Dans le cas d'une relation, - le formulaire d'édition de l'entité liée sera inclus dans le formulaire - -* `generic`, indique qu'une relation doit être incorporé dans le formulaire - d'édition simple dans la boite générique d'ajout de relation - -* `generated`, indique qu'un attribut est caculé dynamiquement ou autre, et - qu'il ne doit donc pas être présent dans les formulaires d'édition - -Au besoin il est possible de surcharger la méthode -`relation_category(rtype, x='subject')` pour calculer dynamiquement la catégorie -d'édition d'une relation. - - -Contrôle de la boîte "add_related" -`````````````````````````````````` -La boite `add related` est une boite automatique proposant de créer une entité -qui sera automatiquement liée à l'entité de départ (le contexte dans lequel -s'affiche la boite). Par défaut, les liens présents dans cette boite sont -calculés en fonction des propriétés du schéma de l'entité visualisée, mais il -est possible de les spécifier explicitement à l'aide des *rtags* suivants : - -* `link`, indique qu'une relation est généralement créée vers une entité - existante et qu'il ne faut donc pas faire apparaitre de lien pour cette - relation - -* `create`, indique qu'une relation est généralement créée vers de nouvelles - entités et qu'il faut donc faire apparaitre un lien pour créer une nouvelle - entité et la lier automatiquement - -Au besoin il est possible de surcharger la méthode -`relation_mode(rtype, targettype, x='subject')` pour caculer dynamiquement la -catégorie de création d'une relation. - -A noter également que si au moins une action dans la catégorie "addrelated" est -trouvée pour le contexte courant, le fonctionnement automatique est désactivé -en faveur du fonctionnement explicite (i.e. affichage des actions de la -catégorie "addrelated" uniquement). - -Contrôle des formulaires de filtrage de table -````````````````````````````````````````````` -La vue "table" par défaut gère dynamiquement un formulaire de filtrage du -contenu de celle-ci. L'algorithme est le suivant : - -1. on considère que la première colonne contient les entités à restreindre -2. on recupère la première entité de la table (ligne 0) pour "représenter" - toutes les autres -3. pour toutes les autres variables définies dans la requête originale : - - 1. si la variable est liée à la variable principale par au moins une - n'importe quelle relation - 2. on appelle la méthode `filterform_vocabulary(rtype, x)` sur l'entité - et si rien est retourné (ou plus exactement un tuple de valeur `None`, - voir ci-dessous) on passe à la variable suivante, sinon un élément de - formulaire de filtrage sera créé avec les valeurs de vocabulaire - retournées - -4. il n'y a pas d'autres limitations sur le rql, il peut comporter des clauses - de tris, de groupes... Des fonctions javascripts sont utilisées pour - regénérer une requête à partir de la requête de départ et des valeurs - séléctionnées dans les filtres de formulaire. - - -La méthode `filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)` prend -en argument le nom d'une relation et la "cible", qui indique si l'entité sur -laquelle la méthode est appellée est sujet ou objet de la relation. Elle doit -retourner : - -* un 2-uple de None si elle ne sait pas gérer cette relation - -* un type et une liste contenant le vocabulaire - - * la liste doit contenir des couples (valeur, label) - * le type indique si la valeur désigne un nombre entier (`type == 'int'`), une - chaîne de caractères (`type == 'string'`) ou une entité non finale (`type - == 'eid'`) - -Par exemple dans notre application de gestion de tickets, on veut pouvoir -filtrés ceux-ci par : - -* type -* priorité -* état (in_state) -* étiquette (tags) -* version (done_in) - -On définit donc la méthode suivante : :: - - - class Ticket(AnyEntity): - - ... - - def filterform_vocabulary(self, rtype, x, var, rqlst, args, cachekey): - _ = self.req._ - if rtype == 'type': - return 'string', [(x, _(x)) for x in ('bug', 'story')] - if rtype == 'priority': - return 'string', [(x, _(x)) for x in ('minor', 'normal', 'important')] - if rtype == 'done_in': - rql = insert_attr_select_relation(rqlst, var, rtype, 'num') - return 'eid', self.req.execute(rql, args, cachekey) - return super(Ticket, self).filterform_vocabulary(rtype, x, var, rqlst, - args, cachekey) - - -NOTE: Le support du filtrage sur les étiquettes et l'état est installé -automatiquement, pas besoin de le gérer ici.