+
−.. -*- 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 ::
+
−
+
−  <type de relation>, <type d'entité cible>, <position du contexte ("subject" ou "object"
+
−
+
−et les valeurs un `set` ou un tuple de marqueurs définissant des propriétés 
+
−s'appliquant à cette relation. 
+
−
+
−Il est possible de simplifier ce dictionnaire :
+
−
+
−* 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...
+
−
+
−
+
−.. include:: sect_definition_entites.txt