# HG changeset patch # User Sandrine Ribeau # Date 1227563949 28800 # Node ID 213f07dffde3c3588adc60e357d692c8644c18c6 # Parent 061fa802e2a3874539c47ad3a57627ee19c5de78 [doc] Translation to english. diff -r 061fa802e2a3 -r 213f07dffde3 doc/book/en/B050-data-as-objects.en.txt --- a/doc/book/en/B050-data-as-objects.en.txt Mon Nov 24 10:22:04 2008 -0800 +++ b/doc/book/en/B050-data-as-objects.en.txt Mon Nov 24 13:59:09 2008 -0800 @@ -1,142 +1,144 @@ .. -*- coding: utf-8 -*- -Manipulation des données stockées -================================= +Stored data handling +==================== -Les classes `Entity` et `AnyEntity` ------------------------------------ -Pour fournir un comportement spécifique à un type d'entité, il suffit de définir -une classe héritant de la class `ginco.entities.AnyEntity`. En général il faut -définir ces classes dans un module du package `entities` d'une application pour -qu'elle soit disponible à la fois coté serveur et coté client. +Classes `Entity` and `AnyEntity` +-------------------------------- -La classe `AnyEntity` est une classe chargée dynamiquement héritant de la classe -de base `Entity` (`ginco.common.entity`). On définit une sous-classe pour -ajouter des méthodes ou spécialiser les comportements d'un type d'entité donné. +To provide a specific behavior for each entity, we just need to define +a class inheriting from `cubicweb.entities.EnyEntity`. In genera, we have +to defined those classes in a module of `entites` package of an application +so that it will be available on both server and client side. -Des descripteurs sont ajoutés à l'enregistrement pour initialiser la classe en -fonction du schéma : +The class `AnyEntity` is loaded dynamically from the class `Entity` +(`cubciweb.common.entity`). We define a sub-class to add methods or to +specialize the handling of a given entity type -* on peut accéder aux attributs définis dans le schéma via les attributs de même - nom sur les instances (valeur typée) +Descriptors are added when classes are registered in order to initialize the class +according to its schema: + +* we can access the defined attributes in the schema thanks the attributes of + the same name on instances (typed value) -* on peut accéder aux relations définies dans le schéma via les attributs de même - nom sur les instances (liste d'instances d'entité) +* we can access the defined relations in the schema thanks to the relations of + the same name on instances (entities instances list) -Les méthodes définies sur la classe `AnyEntity` ou `Entity` sont les suivantes : +The methods defined for `AnyEntity` or `Entity` are the following ones: -* `has_eid()`, retourne vrai si l'entité à un eid affecté (i.e. pas en cours de - création) +* `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the + creation process) -* `check_perm(action)`, vérifie que l'utilisateur à le droit d'effectuer - l'action demandée sur l'entité +* `check_perm(action)`, checks if the user has the permission to execcute the + requested action on the entity -:Formattage et génération de la sortie: +:Formatting and output generation: - * `view(vid, **kwargs)`, applique la vue donnée à l'entité + * `view(vid, **kwargs)`, apply the given view to the entity - * `absolute_url(**kwargs)`, retourne une URL absolue permettant d'accéder à la - vue primaire d'une entité + * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view + of an entity + + * `rest_path()`, returns a relative REST URL to get the entity - * `rest_path()`, renvoie une l'URL REST relative permettant d'obtenir l'entité - - * `format(attr)`, retourne le format (type MIME) du champ passé en argument + * `format(attr)`, returns the format (MIME type) of the field given un parameter * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, - retourne une chaine permettant l'affichage dans un format donné de la valeur - d'un attribut (la valeur est automatiquement récupérée au besoin) + returns a string enabling the display of an attribute value in a given format + (the value is automatically recovered if necessarry) - * `display_name(form='')`, retourne une chaîne pour afficher le type de - l'entité, en spécifiant éventuellement la forme désirée ('plural' pour la - forme plurielle) + * `display_name(form='')`, returns a string to display the entity type by + specifying the preferred form (`plural` for a plural form) -:Gestion de données: +:Data handling: - * `as_rset()`, transforme l'entité en un resultset équivalent simulant - le résultat de la requête `Any X WHERE X eid _eid_` + * `as_rset()`, converts the entity into an equivalent result set simulating the + request `Any X WHERE X eid _eid_` - * `complete(skip_bytes=True)`, effectue une requête permettant de récupérer d'un - coup toutes les valeurs d'attributs manquant sur l'entité + * `complete(skip_bytes=True)`, executes a request that recovers in one time + all the missing attributes of an entity - * `get_value(name)`, récupere la valeur associée à l'attribut passé en argument + * `get_value(name)`, returns the value associated to the attribute name given + in parameter - * `related(rtype, x='subject', limit=None, entities=False)`, retourne une liste - des entités liées à l'entité courant par la relation donnée en argument - - * `unrelated(rtype, targettype, x='subject', limit=None)`, retourne un result set - des entités not liées à l'entité courante par la relation donnée en argument - et satisfaisants les contraintes de celle-ci + * `related(rtype, x='subject', limit=None, entities=False)`, returns a list + of entities related to the current entity by the relation given in parameter - * `set_attributes(**kwargs)`, met à jour la liste des attributs avec - les valeurs correspondantes passées sous forme d'arguments nommés + * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set + corresponding to the entities not related to the current entity by the + relation given in parameter and satisfying its constraints - * `copy_relations(ceid)`, copie les relations de l'entité ayant l'eid passé en - argument sur l'entité courante + * `set_attributes(**kwargs)`, updates the attributes list with the corresponding + values given named parameters - * `last_modified(view)`, retourne la date à laquelle on doit considérer - l'objet comme modifié (utiliser par la gestion de cache HTTP) + * `copy_relations(ceid)`, copies the relations of the entities having the eid + given in the parameters on the current entity + + * `last_modified(view)`, returns the date the object has been modified + (used by HTTP cache handling) - * `delete()` permet de supprimer l'entité représentée + * `delete()` allows to delete the entity -:Meta-données standard (Dublin Core): +:Standard meta-data (Dublin Core): - * `dc_title()`, retourne une chaine unicode correspondant à la méta-donnée - 'Title' (utilise par défaut le premier attribut non 'meta' du schéma de - l'entité) + * `dc_title()`, returns a unicode string corresponding to the meta-data + `Title` (used by default the first attribute non-meta of the entity + schema) - * `dc_long_title()`, comme dc_title mais peut retourner un titre plus détaillé + * `dc_long_title()`, same as dc_title but can return a more + detailled title - * `dc_description(format='text/plain')`, retourne une chaine unicode - correspondant à la méta-donnée 'Description' (cherche un attribut - 'description' par défaut) + * `dc_description(format='text/plain')`, returns a unicode string + corresponding to the meta-data `Description` (look for a description + attribute by default) - * `dc_authors()`, retourne une chaine unicode correspondant à la méta-donnée - 'Authors' (propriétaires par défaut) + * `dc_authors()`, returns a unicode string corresponding to the meta-data + `Authors` (owners by default) - * `dc_date(date_format=None)`, retourne une chaine unicode - correspondant à la méta-donnée 'Date' (date de modification par défaut) + * `dc_date(date_format=None)`, returns a unicode string corresponding to + the meta-data `Date` (update date by default) -:Contrôle du vocabulaire pour les relations: +:Vocabulary control on relations: - * `vocabulary(rtype, x='subject', limit=None)`, appelée notamment - par les vues d'édition d'erudi, elle renvoie une liste de couple - (label, eid) des entités qui pourraient être liées à l'entité - via la relation `rtype` - * `subject_relation_vocabulary(rtype, limit=None)`, appelée - en interne par `vocabulary` dans le cas d'une relation sujet - * `object_relation_vocabulary(rtype, limit=None)`, appelée - en interne par `vocabulary` dans le cas d'une relation objet - * `relation_vocabulary(rtype, targettype, x, limit=None)`, appelé - en interne par `subject_relation_vocabulary` et `object_relation_vocabulary` + * `vocabulary(rtype, x='subject', limit=None)`, called by the + editing views, it returns a list of couples (label, eid) of entities + that could be related to the entity by the relation `rtype` + * `subject_relation_vocabulary(rtype, limit=None)`, called internally + by `vocabulary` in the case of a subject relation + * `object_relation_vocabulary(rtype, limit=None)`, called internally + by `vocabulary` in the case of an object relation + * `relation_vocabulary(rtype, targettype, x, limit=None)`, called + internally by `subject_relation_vocabulary` and `object_relation_vocabulary` -Les *rtags* ------------ -Les *rtags* permettent de spécifier certains comportements propres aux relations -d'un type d'entité donné (voir plus loin). Ils sont définis sur la classe -d'entité via l'attribut `rtags` qui est un dictionnaire dont les clés sont un -triplet :: +*rtags* +------- - , , , , -Il est possible de simplifier ce dictionnaire : +and as the values a `set` or a tuple of markers defining the properties that +apply to this relation. + +It is possible to simplify this dictionnary: -* si l'on veut spécifier un seul marqueur, il n'est pas nécessaire d'utiliser - un tuple comme valeur, le marqueur seul (chaine de caractères) suffit -* si l'on s'intéresse uniquement à un type de relation et non à la cible et à la - position du contexte (ou que celui-ci n'est pas ambigüe), on peut simplement - utiliser le nom du type de relation comme clé -* si l'on veut qu'un marqueur s'applique quelque soit le type d'entité cible, il - faut utiliser la chaine `*` comme type d'entité cible - -A noter également que ce dictionnaire est *traité à la création de la classe*. -Il est automatiquement fusionné avec celui de la ou des classe(s) parentes (pas -besoin de copier celui de la classe parent pour le modifier). De même modifier -celui-ci après création de la classe n'aura aucun effet... +* if we want to specifiy a single marker, it is not necessarry to + use a tuple as the value, the marker by itself (characters string) + is enough +* if we only care about a single type of relation and not about the target + and the context position (or when this one is not ambigous), we can simply + use the name of the relation type as the key +* if we want a marker to apply independently from the target entity type, + we have to use the string `*` as the target entity type +Please note that this dictionnary is *treated at the time the class is created*. +It is automatically merged with the parent class(es) (no need to copy the +dictionnary from the parent class to modify it). Also, modify it after the +class is created will not have any effect... + .. include:: B051-define-entities.en.txt diff -r 061fa802e2a3 -r 213f07dffde3 doc/book/en/B051-define-entities.en.txt --- a/doc/book/en/B051-define-entities.en.txt Mon Nov 24 10:22:04 2008 -0800 +++ b/doc/book/en/B051-define-entities.en.txt Mon Nov 24 13:59:09 2008 -0800 @@ -1,43 +1,45 @@ .. -*- coding: utf-8 -*- -Paramétrages et extensions spécifiques --------------------------------------- +Parametrization and specific extensions +--------------------------------------- -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. +Dynamic default values +`````````````````````` +It is possible to define in the schema *static* default values. +It is also possible to define in the schema *dynamic* default values +by defining in the entity class a method `default_` for +a given attribute. -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`*. +Control of loaded attributes and default sorting +```````````````````````````````````````````````` -* 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 +* The class attribute `fetch_attrs` allows to defined in an entity class + a list of names of attributes or relations that should be automatically + loaded when we recover the entities of this type. In the case of relations, + we are limited to *subject of cardinality `?` or `1`* relations. + +* The class method `fetch_order(attr, var)` expects an attribute (or relation) + name as a parameter and a variable name, and it should return a string + to use in the requirement `ORDER BY` of an RQL query to automatically + sort the list of entities of such type according to this attribute, or + `None` if we do not want to sort on the attribute given in the parameter. + By default, the entities are sorted according to their creation date. -* 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é +* The class method `fetch_unrelated_order(attr, var)` is similar to the + method `fetch_order` except that it is essentially used to control + the sorting of drop-down lists enabling relations creation in + the editing view of an entity. -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`. +The function `fetch_config(fetchattrs, mainattr=None)` simplifies the +definition of the attributes to load and the sorting by returning a +list of attributes to pre-load (considering automatically the attributes +of `AnyEntity`) and a sorting function based on the main attribute +(the second parameter if specified otherwisethe first attribute from +the list `fetchattrs`). +This function is defined in `cubicweb.entities`. -Par exemple : :: +By example: :: class Transition(AnyEntity): """..."""