diff -r 000000000000 -r b97547f5f1fa doc/devmanual_fr/chap_manipulation_donnees.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/devmanual_fr/chap_manipulation_donnees.txt Wed Nov 05 15:52:50 2008 +0100 @@ -0,0 +1,142 @@ +.. -*- coding: utf-8 -*- + + +Manipulation des données stockées +================================= + +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. + +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é. + +Des descripteurs sont ajoutés à l'enregistrement pour initialiser la classe en +fonction du schéma : + +* 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) + +* 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é) + +Les méthodes définies sur la classe `AnyEntity` ou `Entity` sont les suivantes : + +* `has_eid()`, retourne vrai si l'entité à un eid affecté (i.e. pas en cours de + création) + +* `check_perm(action)`, vérifie que l'utilisateur à le droit d'effectuer + l'action demandée sur l'entité + +:Formattage et génération de la sortie: + + * `view(vid, **kwargs)`, applique la vue donnée à l'entité + + * `absolute_url(**kwargs)`, retourne une URL absolue permettant d'accéder à la + vue primaire d'une entité + + * `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 + + * `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) + + * `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) + +:Gestion de données: + + * `as_rset()`, transforme l'entité en un resultset équivalent simulant + le résultat de la requête `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é + + * `get_value(name)`, récupere la valeur associée à l'attribut passé en argument + + * `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 + + * `set_attributes(**kwargs)`, met à jour la liste des attributs avec + les valeurs correspondantes passées sous forme d'arguments nommés + + * `copy_relations(ceid)`, copie les relations de l'entité ayant l'eid passé en + argument sur l'entité courante + + * `last_modified(view)`, retourne la date à laquelle on doit considérer + l'objet comme modifié (utiliser par la gestion de cache HTTP) + + * `delete()` permet de supprimer l'entité représentée + +:Meta-données standard (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_long_title()`, comme dc_title mais peut retourner un titre plus détaillé + + * `dc_description(format='text/plain')`, retourne une chaine unicode + correspondant à la méta-donnée 'Description' (cherche un attribut + 'description' par défaut) + + * `dc_authors()`, retourne une chaine unicode correspondant à la méta-donnée + 'Authors' (propriétaires par défaut) + + * `dc_date(date_format=None)`, retourne une chaine unicode + correspondant à la méta-donnée 'Date' (date de modification par défaut) + +:Contrôle du vocabulaire pour les 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` + + +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 :: + + , ,