|
1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 |
|
4 Stored data handling |
|
5 ==================== |
|
6 |
|
7 Classes `Entity` and `AnyEntity` |
|
8 -------------------------------- |
|
9 |
|
10 To provide a specific behavior for each entity, we just need to define |
|
11 a class inheriting from `cubicweb.entities.EnyEntity`. In genera, we have |
|
12 to defined those classes in a module of `entites` package of an application |
|
13 so that it will be available on both server and client side. |
|
14 |
|
15 The class `AnyEntity` is loaded dynamically from the class `Entity` |
|
16 (`cubciweb.common.entity`). We define a sub-class to add methods or to |
|
17 specialize the handling of a given entity type |
|
18 |
|
19 Descriptors are added when classes are registered in order to initialize the class |
|
20 according to its schema: |
|
21 |
|
22 * we can access the defined attributes in the schema thanks the attributes of |
|
23 the same name on instances (typed value) |
|
24 |
|
25 * we can access the defined relations in the schema thanks to the relations of |
|
26 the same name on instances (entities instances list) |
|
27 |
|
28 The methods defined for `AnyEntity` or `Entity` are the following ones: |
|
29 |
|
30 * `has_eid()`, returns true is the entity has an definitive eid (e.g. not in the |
|
31 creation process) |
|
32 |
|
33 * `check_perm(action)`, checks if the user has the permission to execcute the |
|
34 requested action on the entity |
|
35 |
|
36 :Formatting and output generation: |
|
37 |
|
38 * `view(vid, **kwargs)`, apply the given view to the entity |
|
39 |
|
40 * `absolute_url(**kwargs)`, returns an absolute URL to access the primary view |
|
41 of an entity |
|
42 |
|
43 * `rest_path()`, returns a relative REST URL to get the entity |
|
44 |
|
45 * `format(attr)`, returns the format (MIME type) of the field given un parameter |
|
46 |
|
47 * `printable_value(attr, value=_marker, attrtype=None, format='text/html')`, |
|
48 returns a string enabling the display of an attribute value in a given format |
|
49 (the value is automatically recovered if necessarry) |
|
50 |
|
51 * `display_name(form='')`, returns a string to display the entity type by |
|
52 specifying the preferred form (`plural` for a plural form) |
|
53 |
|
54 :Data handling: |
|
55 |
|
56 * `as_rset()`, converts the entity into an equivalent result set simulating the |
|
57 request `Any X WHERE X eid _eid_` |
|
58 |
|
59 * `complete(skip_bytes=True)`, executes a request that recovers in one time |
|
60 all the missing attributes of an entity |
|
61 |
|
62 * `get_value(name)`, returns the value associated to the attribute name given |
|
63 in parameter |
|
64 |
|
65 * `related(rtype, x='subject', limit=None, entities=False)`, returns a list |
|
66 of entities related to the current entity by the relation given in parameter |
|
67 |
|
68 * `unrelated(rtype, targettype, x='subject', limit=None)`, returns a result set |
|
69 corresponding to the entities not related to the current entity by the |
|
70 relation given in parameter and satisfying its constraints |
|
71 |
|
72 * `set_attributes(**kwargs)`, updates the attributes list with the corresponding |
|
73 values given named parameters |
|
74 |
|
75 * `copy_relations(ceid)`, copies the relations of the entities having the eid |
|
76 given in the parameters on the current entity |
|
77 |
|
78 * `last_modified(view)`, returns the date the object has been modified |
|
79 (used by HTTP cache handling) |
|
80 |
|
81 * `delete()` allows to delete the entity |
|
82 |
|
83 :Standard meta-data (Dublin Core): |
|
84 |
|
85 * `dc_title()`, returns a unicode string corresponding to the meta-data |
|
86 `Title` (used by default the first attribute non-meta of the entity |
|
87 schema) |
|
88 |
|
89 * `dc_long_title()`, same as dc_title but can return a more |
|
90 detailled title |
|
91 |
|
92 * `dc_description(format='text/plain')`, returns a unicode string |
|
93 corresponding to the meta-data `Description` (look for a description |
|
94 attribute by default) |
|
95 |
|
96 * `dc_authors()`, returns a unicode string corresponding to the meta-data |
|
97 `Authors` (owners by default) |
|
98 |
|
99 * `dc_date(date_format=None)`, returns a unicode string corresponding to |
|
100 the meta-data `Date` (update date by default) |
|
101 |
|
102 :Vocabulary control on relations: |
|
103 |
|
104 * `vocabulary(rtype, x='subject', limit=None)`, called by the |
|
105 editing views, it returns a list of couples (label, eid) of entities |
|
106 that could be related to the entity by the relation `rtype` |
|
107 * `subject_relation_vocabulary(rtype, limit=None)`, called internally |
|
108 by `vocabulary` in the case of a subject relation |
|
109 * `object_relation_vocabulary(rtype, limit=None)`, called internally |
|
110 by `vocabulary` in the case of an object relation |
|
111 * `relation_vocabulary(rtype, targettype, x, limit=None)`, called |
|
112 internally by `subject_relation_vocabulary` and `object_relation_vocabulary` |
|
113 |
|
114 |
|
115 *rtags* |
|
116 ------- |
|
117 |
|
118 *rtags* allows to specify certain behaviors of relations relative to a given |
|
119 entity type (see later). They are defined on the entity class by the attribute |
|
120 `rtags` which is a dictionnary with as its keys the triplet :: |
|
121 |
|
122 <relation type>, <target entity type>, <context position ("subject" ou "object")> |
|
123 |
|
124 and as the values a `set` or a tuple of markers defining the properties that |
|
125 apply to this relation. |
|
126 |
|
127 It is possible to simplify this dictionnary: |
|
128 |
|
129 * if we want to specifiy a single marker, it is not necessarry to |
|
130 use a tuple as the value, the marker by itself (characters string) |
|
131 is enough |
|
132 * if we only care about a single type of relation and not about the target |
|
133 and the context position (or when this one is not ambigous), we can simply |
|
134 use the name of the relation type as the key |
|
135 * if we want a marker to apply independently from the target entity type, |
|
136 we have to use the string `*` as the target entity type |
|
137 |
|
138 |
|
139 Please note that this dictionnary is *treated at the time the class is created*. |
|
140 It is automatically merged with the parent class(es) (no need to copy the |
|
141 dictionnary from the parent class to modify it). Also, modify it after the |
|
142 class is created will not have any effect... |
|
143 |
|
144 .. include:: B051-define-entities.en.txt |