# HG changeset patch
# User Sandrine Ribeau <sandrine.ribeau@logilab.fr>
# Date 1228786438 28800
# Node ID cd9cc01538355b3735bee4d129ab407926a8d60b
# Parent 46b24614282c71f702bed6e24380101aa9da176c# Parent cae87ca76f026b77830f06b447709bf3aab8d2f1
merge
diff -r cae87ca76f02 -r cd9cc0153835 doc/book/en/B051-define-entities.en.txt
--- a/doc/book/en/B051-define-entities.en.txt Mon Dec 08 17:48:20 2008 +0100
+++ b/doc/book/en/B051-define-entities.en.txt Mon Dec 08 17:33:58 2008 -0800
@@ -11,7 +11,7 @@
a given attribute.
-Control of loaded attributes and default sorting
+Loaded attributes and default sorting management
````````````````````````````````````````````````
* The class attribute `fetch_attrs` allows to defined in an entity class
@@ -46,107 +46,105 @@
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.
+Indicates that for the entity type "Transition", you have to pre-load
+the attribute `name` and sort by default on this attribute.
-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 :
+Editing forms management
+````````````````````````
+It is possible to manage attributes/relations in the simple or multiple
+editing form thanks to the following *rtags*:
+
+* `primary`, indicates that an attribute or a relation has to be inserted
+ in the simple or multiple editing forms. In the case of a relation,
+ the related entity editing form will be included in the editing form.
-* `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`, indicates that an attribute or a relation has to be inserted
+ in the simple editing form only. In the case of a relation, the related
+ entity editing form sill be included in the editing form.
+
+* `generic`, indicates that a relation has to be inserted in the simple
+ editing form, in the generic box of relation creation.
+
+* `generated`, indicates that an attribute is dynamically computed
+ or other, and that it should not be displayed in the editing form.
-* `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
+If necessarry, it is possible to overwrite the method
+`relation_category(rtype, x='subject')` to dynamically compute
+a relation editing category.
-* `generic`, indique qu'une relation doit être incorporé dans le formulaire
- d'édition simple dans la boite générique d'ajout de relation
+``add_related`` box management
+``````````````````````````````
-* `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
+The box ``add_related`` is an automatic box that allows to create
+an entity automatically related to the initial entity (context in
+which the box is displayed). By default, the links generated in this
+box are computed from the schema properties of the displayed entity,
+but it is possible to explicitely specify them thanks to the
+following *rtags*:
-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.
+* `link`, indicates that a relation is in general created pointing
+ to an existing entity and that we should not to display a link
+ for this relation
+
+* `create`, indicates that a relation is in general created pointing
+ to new entities and that we should display a link to create a new
+ entity and link to it automatically
-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
+If necessarry, it is possible to overwrite the method
+`relation_mode(rtype, targettype, x='subject')` to dynamically
+compute a relation creation category.
-* `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
+Please note that if at least one action belongs to the `addrelated` category,
+the automatic behavior is desactivated in favor of an explicit behavior
+(e.g. display of `addrelated` category actions only).
-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).
+Filtering table forms management
+````````````````````````````````
-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 :
+By default, the view ``table`` manages automatically a filtering
+form of its content. The algorithm is as follows:
-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. we consider that the first column contains the entities to constraint
+2. we collect the first entity of the table (row 0) to represent all the
+ others
+3. for all the others variables defined in the original request:
+
+ 1. if the varaible is related to the main variable by at least one relation
+ 2. we call the method ``filterform_vocabulary(rtype, x)`` on the entity,
+ if nothing is returned (meaning a tuple `Non`, see below), we go to the
+ next variable, otherwise a form filtering element is created based on
+ the vocabulary values returned
- 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.
+4. there is no others limitations to the `RQL`, it can include sorting, grouping
+ conditions... Javascripts functions are used to regenerate a request based on the
+ initial request and on the selected values from the filtering form.
-
-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 :
+The method ``filterform_vocabulary(rtype, x, var, rqlst, args, cachekey)`` takes
+the name of a relation and the target as parameters, which indicates of the
+entity on which we apply the method is subject or object of the relation. It
+has to return:
-* un 2-uple de None si elle ne sait pas gérer cette relation
+* a 2-uple of None if it does not know how to handle the relation
-* un type et une liste contenant le vocabulaire
+* a type and a list containing the vocabulary
+
+ * the list has to contain couples (value, label)
+ * the type indicates if the value designate an integer (`type == 'int'`),
+ a string (`type =='string'` or a non-final relation (`type == 'eid'`)
- * 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 :
+By example in our application managing tickets, we want to be able to filter
+them by :
* type
-* priorité
-* état (in_state)
-* étiquette (tags)
+* priority
+* state (in_state)
+* tag (tags)
* version (done_in)
-On définit donc la méthode suivante : ::
+For that we define the following method: ::
class Ticket(AnyEntity):
@@ -165,6 +163,6 @@
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.
+.. note::
+ Filtering on state and tags is automatically installed, no need to handle it.
+
diff -r cae87ca76f02 -r cd9cc0153835 doc/book/en/B060-form-management.en.txt
--- a/doc/book/en/B060-form-management.en.txt Mon Dec 08 17:48:20 2008 +0100
+++ b/doc/book/en/B060-form-management.en.txt Mon Dec 08 17:33:58 2008 -0800
@@ -1,133 +1,137 @@
.. -*- coding: utf-8 -*-
-Gestion de formulaires
-======================
+Forms handling
+==============
-Contrôle de la génération automatique de formulaire pour les entités manipulée
-------------------------------------------------------------------------------
+Automatically generated forms management for handled entities
+-------------------------------------------------------------
+
XXX FILLME
-* les formulaires 'edition' et 'creation'
+* forms ``edition`` and ``creation``
-Le formulaire généré par défaut ne vous convient pas ? Vous êtes peut-être pas
-obligé de le refaire à la main ! :)
+The form generated by default does not fit your needs? You are not
+required to re-do all by hands! :)
-* rtags primary, secondary, generated, generic,
+* rtags primary, secondary, generated, generic,
`Entity.relation_category(rtype, x='subject')`
* inline_view (now a rtag?)
-* spécification widget
+* widget specification
+Editing controller behavior by default (id: `edit`)
+---------------------------------------------------
+
+Editing control
+```````````````
-Fonctionnement du contrôleur d'édition par défaut (id: 'edit')
---------------------------------------------------------------
+Re-requisites: the parameters related to entities to edit are
+specified as follows ::
-Contrôle de l'édition
-`````````````````````
-Prérequis: les paramètres liés aux entités à éditer sont spécifiés de la forme ::
+ <field name>:<entity eid>
+
+where entity eid could be a letter in case of an entity to create. We
+name those parameters as *qualified*.
- <nom de champ>:<eid de l'entité>
-
-où l'eid de l'entité pourra être une lettre dans le cas d'une entité à créer. On
-dénommera ces paramètres comme *qualifié*.
+1. Retrieval of entities to edit by looking for the forms parameters
+ starting by `eid:` and also having a parameter `__type` associated
+ (also *qualified* by eid)
-1. récupération des entités à éditer en cherchant les paramètres de formulaire
- commençant par 'eid:' ayant également un paramètre '__type' associé
- (également *qualifié* par l'eid évidemment)
+2. For all the attributes and the relations of an entity to edit:
+
+ 1. search for a parameter `edits-<relation name>` or `edito-<relation name>`
+ qualified in the case of a relation where the entity is object
+ 2. if found, the value returned is considered as the initial value
+ for this relaiton and we then look for the new value(s) in the parameter
+ <relation name> (qualified)
+ 3. if the value returned is different from the initial value, an database update
+ request is done
-2. pour tous les attributs et relations de chaque entité à éditer
+3. For each entity to edit:
- 1. recherche d'un paramètre 'edits-<nom relation>' ou 'edito-<nom relation>'
- qualifié dans le cas d'une relation dont l'entité est objet
- 2. si trouvé, la valeur récupérée est considérée comme la valeur originale
- pour cette relation, et on cherche la (ou les) nouvelle(s) valeur(s) dans
- le paramètre <nom relation> (qualifié)
- 3. si la valeur est différente de l'originale, une requête de modification en
- base est effectuée
+ 1. if a qualified parameter `__linkto` is specified, its value has to be
+ a string (or a list of string) such as: ::
+
+ <relation type>:<eids>:<target>
+
+ where <target> is either `subject` or `object` and each eid could be
+ separated from the others by a `_`. Target specifies if the *edited entity*
+ is subject or object of the relation and each relation specified will
+ be inserted.
-3. pour chaque entité à éditer
+ 2. if a qualified parameter `__clone_eid` is specified for an entity, the
+ relations of the specified entity passed as value of this parameter are
+ copied on the edited entity.
- 1. si un paramètre `__linkto` qualifié est spécifié, sa valeur doit être une
- chaine (ou une liste de chaine) de la forme : ::
+ 3. if a qualified parameter `__delete` is specified, its value must be
+ a string or a list of string such as follows: ::
+
+ <ssubjects eids>:<relation type>:<objects eids>
- <relation type>:<eids>:<target>
+ where each eid subject or object can be seperated from the other
+ by `_`. Each relation specified will be deleted.
- où <target> vaut 'subject' ou 'object' et chaque eid peut-être séparé d'un
- autre par un '_'. Target spécifie *l'entité éditée* est sujet ou objet de la
- relation et chaque relation ainsi spécifiée sera insérée.
+ 4. if a qualified parameter `__insert` is specified, its value should
+ follow the same pattern as `__delete`, but each relation specified is
+ inserted.
- 2. si un paramètre `__cloned_eid` qualifié est spécifié pour une entité, les
- relations de l'entité spécifiée en valeur de cette argument sont copiées sur
- l'entité éditée
+4. If the parameters `__insert` and/or `__delete` are found not qualified,
+ they are interpreted as explained above (independantly from the number
+ of entities edited).
+
+5. If no entity is edited but the form contains the parameters `__linkto`
+ and `eid`, this one is interpreted by using the value specified for `eid`
+ to designate the entity on which to add the relations.
- 3. si un paramètre `__delete` qualifié est spécifié, sa valeur doit être une
- chaine (ou une liste de chaine) de la forme : ::
+.. note::
+
+ * If the parameter `__action_delete` is found, all the entities specified
+ as to be edited will be deleted.
+
+ * If the parameter`__action_cancel` is found, no action is completed.
- <subject eids>:<relation type>:<object eids>
-
- où chaque eid sujet ou objet peut-être séparé d'un autre par un '_'. Chaque
- relation ainsi spécifiée sera supprimée.
+ * If the parameter `__action_apply` is found, the editing is applied
+ normally but the redirection is done on the form
+ (see :ref:`RedirectionControl`).
- 4. si un paramètre `__insert` qualifié est spécifié, sa valeur doit être de
- même format que pour `__delete`, mais chaque relation ainsi spécifiée sera
- insérée.
+ * The parameter `__method` is also supported as for the main template
+ (XXX not very consistent, maybe __method should be dealed in the view
+ controller).
-4. si les paramètres `__insert` et/ou `__delete` sont trouvés non qualifiés,
- ils sont interprétés comme décrit ci-dessus (quelque soit le nombre d'entité
- édité)
+ * If no entity is found to be edited and if there is no parameter
+ `__action_delete`, `__action_cancel`, `__linkto`, `__delete` or
+ `__insert`, an error is raised.
-5. si aucune entité n'est éditée mais que le formulaire contient les paramètres
- `__linkto` et `eid`, celui-ci est interprété en prenant la valeur spécifié
- par le paramètre `eid` pour désigner l'entité sur laquelle ajouter les
- relations
+ * Using the parameter `__message` in the form will allow to use its value
+ as a message to provide the user once the editing is completed.
-A noter que :
-
-* si le paramètre `__action_delete` est trouvé, toutes les entités comme
- spécifiées à éditer seront supprimées
-
-* si le paramètre `__action_cancel` est trouvé, aucune action n'est effectuée
-
-* si le paramètre `__action_apply` est trouvé, l'édition est effectuée
- normalement mais la redirection sera effectuée sur le formulaire (cf `Contrôle
- de la redirection`_)
+.. _RedirectionControl:
-* le paramètre `__method` est également supporté comme sur le template principal
- (XXX not very consistent, maybe __method should be dealed in the view controller)
+Redirection control
+```````````````````
+Once editing is completed, there is still an issue left: where should we go
+now? If nothing is specified, the controller will do his job but it does not
+mean we will be happy with the result. We can control that by using the
+following parameters:
-* si aucune entité à éditer n'est trouvée et qu'il n'y a pas de paramètre
- `__action_delete`, `__action_cancel`, `__linkto`, `__delete` ou `__insert`,
- une erreur est levée
+* `__redirectpath`: path of the URL (relative to the root URL of the site,
+ no form parameters
-* placer dans le formulaire le paramètre `__message` permettra d'utiliser la
- valeur de ce paramètre comme message d'information à l'utilisateur une fois
- l'édition effectuée.
-
+* `__redirectparams`: forms parameters to add to the path
-Contrôle de la redirection
-``````````````````````````
-Une fois que l'édition s'est bien passé, reste un problème : c'est bien beau
-tout ça, mais où qu'on va maintenant ?? Si rien n'est spécifié, le controlleur
-se débrouille, mais comme il fait pas toujours ce qu'on voudrait, on peut
-controller ça en utilisant les paramètres suivant :
+* `__redirectrql`: redirection RQL request
+
+* `__redirectvid`: redirection view identifier
-* `__redirectpath`: chemin de l'url (relatif à la racine du site, sans paramètre
- de formulaire
-
-* `__redirectparams`: paramètres de formulaires à ajouter au chemin
-
-* `__redirectrql`: requête RQL de redirection
-
-* `__redirectvid`: identifiant de vue de redirection
+* `__errorurl`: initial form URL, used for redirecting in case a validation
+ error is raised during editing. If this one is not specified, an error page
+ is displayed instead of going back to the form (which is, if necessarry,
+ responsible for displaying the errors)
-* `__errorurl`: url du formulaire original, utilisé pour la redirection en cas
- d'erreur de validation pendant l'édition. Si celui-ci n'est pas spécifié, une
- page d'erreur sera présentée plutot qu'un retour sur le formulaire (qui est le
- cas échéant responsable d'afficher les erreurs)
+* `__form_id`: initial view form identifier, used if `__action_apply` is
+ found
-* `__form_id`: identifiant de vue du formulaire original, utilisée si
- `__action_apply` est trouvé
+In general we use either `__redirectpath` and `__redirectparams` or
+`__redirectrql` and `__redirectvid`.
-En général on utilise soit `__redirectpath et `__redirectparams` soit
-`__redirectrql` et `__redirectvid`.