|
1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 |
|
4 Manipulation des données stockées |
|
5 ================================= |
|
6 |
|
7 Les classes `Entity` et `AnyEntity` |
|
8 ----------------------------------- |
|
9 Pour fournir un comportement spécifique à un type d'entité, il suffit de définir |
|
10 une classe héritant de la class `ginco.entities.AnyEntity`. En général il faut |
|
11 définir ces classes dans un module du package `entities` d'une application pour |
|
12 qu'elle soit disponible à la fois coté serveur et coté client. |
|
13 |
|
14 La classe `AnyEntity` est une classe chargée dynamiquement héritant de la classe |
|
15 de base `Entity` (`ginco.common.entity`). On définit une sous-classe pour |
|
16 ajouter des méthodes ou spécialiser les comportements d'un type d'entité donné. |
|
17 |
|
18 Des descripteurs sont ajoutés à l'enregistrement pour initialiser la classe en |
|
19 fonction du schéma : |
|
20 |
|
21 * on peut accéder aux attributs définis dans le schéma via les attributs de même |
|
22 nom sur les instances (valeur typée) |
|
23 |
|
24 * on peut accéder aux relations définies dans le schéma via les attributs de même |
|
25 nom sur les instances (liste d'instances d'entité) |
|
26 |
|
27 Les méthodes définies sur la classe `AnyEntity` ou `Entity` sont les suivantes : |
|
28 |
|
29 * `has_eid()`, retourne vrai si l'entité à un eid affecté (i.e. pas en cours de |
|
30 création) |
|
31 |
|
32 * `check_perm(action)`, vérifie que l'utilisateur à le droit d'effectuer |
|
33 l'action demandée sur l'entité |
|
34 |
|
35 :Formattage et génération de la sortie: |
|
36 |
|
37 * `view(vid, **kwargs)`, applique la vue donnée à l'entité |
|
38 |
|
39 * `absolute_url(**kwargs)`, retourne une URL absolue permettant d'accéder à la |
|
40 vue primaire d'une entité |
|
41 |
|
42 * `rest_path()`, renvoie une l'URL REST relative permettant d'obtenir l'entité |
|
43 |
|
44 * `format(attr)`, retourne le format (type MIME) du champ passé en argument |
|
45 |
|
46 * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, |
|
47 retourne une chaine permettant l'affichage dans un format donné de la valeur |
|
48 d'un attribut (la valeur est automatiquement récupérée au besoin) |
|
49 |
|
50 * `display_name(form='')`, retourne une chaîne pour afficher le type de |
|
51 l'entité, en spécifiant éventuellement la forme désirée ('plural' pour la |
|
52 forme plurielle) |
|
53 |
|
54 :Gestion de données: |
|
55 |
|
56 * `as_rset()`, transforme l'entité en un resultset équivalent simulant |
|
57 le résultat de la requête `Any X WHERE X eid _eid_` |
|
58 |
|
59 * `complete(skip_bytes=True)`, effectue une requête permettant de récupérer d'un |
|
60 coup toutes les valeurs d'attributs manquant sur l'entité |
|
61 |
|
62 * `get_value(name)`, récupere la valeur associée à l'attribut passé en argument |
|
63 |
|
64 * `related(rtype, x='subject', limit=None, entities=False)`, retourne une liste |
|
65 des entités liées à l'entité courant par la relation donnée en argument |
|
66 |
|
67 * `unrelated(rtype, targettype, x='subject', limit=None)`, retourne un result set |
|
68 des entités not liées à l'entité courante par la relation donnée en argument |
|
69 et satisfaisants les contraintes de celle-ci |
|
70 |
|
71 * `set_attributes(**kwargs)`, met à jour la liste des attributs avec |
|
72 les valeurs correspondantes passées sous forme d'arguments nommés |
|
73 |
|
74 * `copy_relations(ceid)`, copie les relations de l'entité ayant l'eid passé en |
|
75 argument sur l'entité courante |
|
76 |
|
77 * `last_modified(view)`, retourne la date à laquelle on doit considérer |
|
78 l'objet comme modifié (utiliser par la gestion de cache HTTP) |
|
79 |
|
80 * `delete()` permet de supprimer l'entité représentée |
|
81 |
|
82 :Meta-données standard (Dublin Core): |
|
83 |
|
84 * `dc_title()`, retourne une chaine unicode correspondant à la méta-donnée |
|
85 'Title' (utilise par défaut le premier attribut non 'meta' du schéma de |
|
86 l'entité) |
|
87 |
|
88 * `dc_long_title()`, comme dc_title mais peut retourner un titre plus détaillé |
|
89 |
|
90 * `dc_description(format='text/plain')`, retourne une chaine unicode |
|
91 correspondant à la méta-donnée 'Description' (cherche un attribut |
|
92 'description' par défaut) |
|
93 |
|
94 * `dc_authors()`, retourne une chaine unicode correspondant à la méta-donnée |
|
95 'Authors' (propriétaires par défaut) |
|
96 |
|
97 * `dc_date(date_format=None)`, retourne une chaine unicode |
|
98 correspondant à la méta-donnée 'Date' (date de modification par défaut) |
|
99 |
|
100 :Contrôle du vocabulaire pour les relations: |
|
101 |
|
102 * `vocabulary(rtype, x='subject', limit=None)`, appelée notamment |
|
103 par les vues d'édition d'erudi, elle renvoie une liste de couple |
|
104 (label, eid) des entités qui pourraient être liées à l'entité |
|
105 via la relation `rtype` |
|
106 * `subject_relation_vocabulary(rtype, limit=None)`, appelée |
|
107 en interne par `vocabulary` dans le cas d'une relation sujet |
|
108 * `object_relation_vocabulary(rtype, limit=None)`, appelée |
|
109 en interne par `vocabulary` dans le cas d'une relation objet |
|
110 * `relation_vocabulary(rtype, targettype, x, limit=None)`, appelé |
|
111 en interne par `subject_relation_vocabulary` et `object_relation_vocabulary` |
|
112 |
|
113 |
|
114 Les *rtags* |
|
115 ----------- |
|
116 Les *rtags* permettent de spécifier certains comportements propres aux relations |
|
117 d'un type d'entité donné (voir plus loin). Ils sont définis sur la classe |
|
118 d'entité via l'attribut `rtags` qui est un dictionnaire dont les clés sont un |
|
119 triplet :: |
|
120 |
|
121 <type de relation>, <type d'entité cible>, <position du contexte ("subject" ou "object" |
|
122 |
|
123 et les valeurs un `set` ou un tuple de marqueurs définissant des propriétés |
|
124 s'appliquant à cette relation. |
|
125 |
|
126 Il est possible de simplifier ce dictionnaire : |
|
127 |
|
128 * si l'on veut spécifier un seul marqueur, il n'est pas nécessaire d'utiliser |
|
129 un tuple comme valeur, le marqueur seul (chaine de caractères) suffit |
|
130 * si l'on s'intéresse uniquement à un type de relation et non à la cible et à la |
|
131 position du contexte (ou que celui-ci n'est pas ambigüe), on peut simplement |
|
132 utiliser le nom du type de relation comme clé |
|
133 * si l'on veut qu'un marqueur s'applique quelque soit le type d'entité cible, il |
|
134 faut utiliser la chaine `*` comme type d'entité cible |
|
135 |
|
136 A noter également que ce dictionnaire est *traité à la création de la classe*. |
|
137 Il est automatiquement fusionné avec celui de la ou des classe(s) parentes (pas |
|
138 besoin de copier celui de la classe parent pour le modifier). De même modifier |
|
139 celui-ci après création de la classe n'aura aucun effet... |
|
140 |
|
141 |
|
142 .. include:: B051-define-entities.en.txt |