|
1 Access to persistent data |
|
2 -------------------------- |
|
3 |
|
4 Python-level access to persistent data is provided by the |
|
5 :class:`Entity <cubicweb.entity>` class. |
|
6 |
|
7 .. XXX this part is not clear. refactor it. |
|
8 |
|
9 An entity class is bound to a schema entity type. Descriptors are added when |
|
10 classes are registered in order to initialize the class according to its schema: |
|
11 |
|
12 * the attributes defined in the schema appear as attributes of these classes |
|
13 |
|
14 * the relations defined in the schema appear as attributes of these classes, |
|
15 but are lists of instances |
|
16 |
|
17 `Formatting and output generation`: |
|
18 |
|
19 * :meth:`view(__vid, __registry='views', **kwargs)`, applies the given view to the entity |
|
20 (and returns a unicode string) |
|
21 |
|
22 * :meth:`absolute_url(*args, **kwargs)`, returns an absolute URL including the base-url |
|
23 |
|
24 * :meth:`rest_path()`, returns a relative REST URL to get the entity |
|
25 |
|
26 * :meth:`printable_value(attr, value=_marker, attrtype=None, format='text/html', displaytime=True)`, |
|
27 returns a string enabling the display of an attribute value in a given format |
|
28 (the value is automatically recovered if necessary) |
|
29 |
|
30 `Data handling`: |
|
31 |
|
32 * :meth:`as_rset()`, converts the entity into an equivalent result set simulating the |
|
33 request `Any X WHERE X eid _eid_` |
|
34 |
|
35 * :meth:`complete(skip_bytes=True)`, executes a request that recovers at |
|
36 once all the missing attributes of an entity |
|
37 |
|
38 * :meth:`get_value(name)`, returns the value associated to the attribute name given |
|
39 in parameter |
|
40 |
|
41 * :meth:`related(rtype, role='subject', limit=None, entities=False)`, |
|
42 returns a list of entities related to the current entity by the |
|
43 relation given in parameter |
|
44 |
|
45 * :meth:`unrelated(rtype, targettype, role='subject', limit=None)`, |
|
46 returns a result set corresponding to the entities not (yet) |
|
47 related to the current entity by the relation given in parameter |
|
48 and satisfying its constraints |
|
49 |
|
50 * :meth:`cw_set(**kwargs)`, updates entity's attributes and/or relation with the |
|
51 corresponding values given named parameters. To set a relation where this |
|
52 entity is the object of the relation, use `reverse_<relation>` as argument |
|
53 name. Values may be an entity, a list of entities, or None (meaning that all |
|
54 relations of the given type from or to this object should be deleted). |
|
55 |
|
56 * :meth:`copy_relations(ceid)`, copies the relations of the entities having the eid |
|
57 given in the parameters on the current entity |
|
58 |
|
59 * :meth:`cw_delete()` allows to delete the entity |
|
60 |
|
61 |
|
62 The :class:`AnyEntity` class |
|
63 ---------------------------- |
|
64 |
|
65 To provide a specific behavior for each entity, we can define a class |
|
66 inheriting from `cubicweb.entities.AnyEntity`. In general, we define this class |
|
67 in `mycube.entities` module (or in a submodule if we want to split code among |
|
68 multiple files) so that it will be available on both server and client side. |
|
69 |
|
70 The class `AnyEntity` is a sub-class of Entity that add methods to it, |
|
71 and helps specializing (by further subclassing) the handling of a |
|
72 given entity type. |
|
73 |
|
74 Most methods defined for `AnyEntity`, in addition to `Entity`, add |
|
75 support for the `Dublin Core`_ metadata. |
|
76 |
|
77 .. _`Dublin Core`: http://dublincore.org/ |
|
78 |
|
79 `Standard meta-data (Dublin Core)`: |
|
80 |
|
81 * :meth:`dc_title()`, returns a unicode string corresponding to the |
|
82 meta-data `Title` (used by default is the first non-meta attribute |
|
83 of the entity schema) |
|
84 |
|
85 * :meth:`dc_long_title()`, same as dc_title but can return a more |
|
86 detailed title |
|
87 |
|
88 * :meth:`dc_description(format='text/plain')`, returns a unicode string |
|
89 corresponding to the meta-data `Description` (looks for a |
|
90 description attribute by default) |
|
91 |
|
92 * :meth:`dc_authors()`, returns a unicode string corresponding to the meta-data |
|
93 `Authors` (owners by default) |
|
94 |
|
95 * :meth:`dc_creator()`, returns a unicode string corresponding to the |
|
96 creator of the entity |
|
97 |
|
98 * :meth:`dc_date(date_format=None)`, returns a unicode string corresponding to |
|
99 the meta-data `Date` (update date by default) |
|
100 |
|
101 * :meth:`dc_type(form='')`, returns a string to display the entity type by |
|
102 specifying the preferred form (`plural` for a plural form) |
|
103 |
|
104 * :meth:`dc_language()`, returns the language used by the entity |
|
105 |
|
106 Inheritance |
|
107 ----------- |
|
108 |
|
109 When describing a data model, entities can inherit from other entities as is |
|
110 common in object-oriented programming. |
|
111 |
|
112 You have the possibility to redefine whatever pleases you, as follow: |
|
113 |
|
114 .. sourcecode:: python |
|
115 |
|
116 from cubes.OTHER_CUBE import entities |
|
117 |
|
118 class EntityExample(entities.EntityExample): |
|
119 |
|
120 def dc_long_title(self): |
|
121 return '%s (%s)' % (self.name, self.description) |
|
122 |
|
123 The most specific entity definition will always the one used by the |
|
124 ORM. For instance, the new EntityExample above in mycube replaces the |
|
125 one in OTHER_CUBE. These types are stored in the `etype` section of |
|
126 the `vregistry`. |
|
127 |
|
128 Notice this is different than yams schema inheritance, which is an |
|
129 experimental undocumented feature. |
|
130 |
|
131 |
|
132 Application logic |
|
133 ----------------- |
|
134 |
|
135 While a lot of custom behaviour and application logic can be |
|
136 implemented using entity classes, the programmer must be aware that |
|
137 adding new attributes and method on an entity class adds may shadow |
|
138 schema-level attribute or relation definitions. |
|
139 |
|
140 To keep entities clean (mostly data structures plus a few universal |
|
141 methods such as listed above), one should use `adapters` (see |
|
142 :ref:`adapters`). |