1 .. -*- coding: utf-8 -*- |
1 .. -*- coding: utf-8 -*- |
2 |
2 |
3 Entity type definition |
3 Entity type definition |
4 ---------------------- |
4 ---------------------- |
5 |
5 |
6 An entity type is defined by a Python class which inherits `EntityType`. The |
6 An entity type is defined by a Python class which inherits from `EntityType`. |
7 class name correponds to the type name. Then the content of the class contains |
7 The class definition contains the description of attributes and relations |
8 the description of attributes and relations for the defined entity type, |
8 for the defined entity type. |
9 for example :: |
9 The class name corresponds to the entity type name. |
|
10 |
|
11 For example :: |
10 |
12 |
11 class Person(EntityType): |
13 class Person(EntityType): |
12 """A person with the properties and the relations necessary for my |
14 """A person with the properties and the relations necessary for my |
13 application""" |
15 application""" |
14 |
16 |
15 last_name = String(required=True, fulltextindexed=True) |
17 last_name = String(required=True, fulltextindexed=True) |
16 first_name = String(required=True, fulltextindexed=True) |
18 first_name = String(required=True, fulltextindexed=True) |
17 title = String(vocabulary=('M', 'Mme', 'Mlle')) |
19 title = String(vocabulary=('Mr', 'Mrs', 'Miss')) |
18 date_of_birth = Date() |
20 date_of_birth = Date() |
19 works_for = SubjectRelation('Company', cardinality='?*') |
21 works_for = SubjectRelation('Company', cardinality='?*') |
20 |
22 |
|
23 |
21 * the name of the Python attribute corresponds to the name of the attribute |
24 * the name of the Python attribute corresponds to the name of the attribute |
22 or the relation in `CubicWeb` application. |
25 or the relation in `CubicWeb` application. |
23 |
26 |
24 * all built-in types are available : `String`, `Int`, `Float`, |
27 * all `CubicWeb` built-in types are available : `String`, `Int`, `Float`, |
25 `Boolean`, `Date`, `Datetime`, `Time`, `Byte`. |
28 `Boolean`, `Date`, `Datetime`, `Time`, `Byte`; they are and implicitely |
|
29 imported (as well as the special the function "_"). |
26 |
30 |
27 * each entity type has at least the following meta-relations : |
31 * each entity type has at least the following meta-relations : |
28 |
32 |
29 - `eid` (`Int`) |
33 - `eid` (`Int`) |
30 |
34 |
32 |
36 |
33 - `modification_date` (`Datetime`) |
37 - `modification_date` (`Datetime`) |
34 |
38 |
35 - `created_by` (`EUser`) (which user created the entity) |
39 - `created_by` (`EUser`) (which user created the entity) |
36 |
40 |
37 - `owned_by` (`EUser`) (who does the entity belongs to, by default the |
41 - `owned_by` (`EUser`) (to whom the entity belongs; by default the |
38 creator but not necessary and it could have multiple owners) |
42 creator but not necessary, and it could have multiple owners) |
39 |
43 |
40 - `is` (`EEType`) |
44 - `is` (`EEType`) |
41 |
45 |
42 |
46 |
43 * it is also possible to define relations of type object by using `ObjectRelation` |
47 * relations can be defined by using `ObjectRelation` or `SubjectRelation`. |
44 instead of `SubjectRelation` |
48 The first argument of `SubjectRelation` or `ObjectRelation` gives respectively |
45 |
|
46 * the first argument of `SubjectRelation` and `ObjectRelation` gives respectively |
|
47 the object/subject entity type of the relation. This could be : |
49 the object/subject entity type of the relation. This could be : |
48 |
50 |
49 * a string corresponding to an entity type |
51 * a string corresponding to an entity type |
50 |
52 |
51 * a tuple of string correponding to multiple entities types |
53 * a tuple of string corresponding to multiple entity types |
52 |
54 |
53 * special string such as follows : |
55 * special string such as follows : |
54 |
56 |
55 - "**" : all types of entities |
57 - "**" : all types of entities |
56 - "*" : all types of non-meta entities |
58 - "*" : all types of non-meta entities |
60 * it is possible to use the attribute `meta` to flag an entity type as a `meta` |
62 * it is possible to use the attribute `meta` to flag an entity type as a `meta` |
61 (e.g. used to describe/categorize other entities) |
63 (e.g. used to describe/categorize other entities) |
62 |
64 |
63 * optional properties for attributes and relations : |
65 * optional properties for attributes and relations : |
64 |
66 |
65 - `description` : string describing an attribute or a relation. By default |
67 - `description` : a string describing an attribute or a relation. By default |
66 this string will be used in the editing form of the entity, which means |
68 this string will be used in the editing form of the entity, which means |
67 that it is supposed to help the end-user and should be flagged by the |
69 that it is supposed to help the end-user and should be flagged by the |
68 function `_` to be properly internationalized. |
70 function `_` to be properly internationalized. |
69 |
71 |
70 - `constraints` : list of conditions/constraints that the relation needs to |
72 - `constraints` : a list of conditions/constraints that the relation has to |
71 satisfy (c.f. `Contraints`_) |
73 satisfy (c.f. `Contraints`_) |
72 |
74 |
73 - `cardinality` : two characters string which specify the cardinality of the |
75 - `cardinality` : a two character string which specify the cardinality of the |
74 relation. The first character defines the cardinality of the relation on |
76 relation. The first character defines the cardinality of the relation on |
75 the subject, the second on the object of the relation. When a relation |
77 the subject, and the second on the object. When a relation can have |
76 has multiple possible subjects or objects, the cardinality applies to all |
78 multiple subjects or objects, the cardinality applies to all, |
77 and not on a one to one basis (so it must be consistent...). The possible |
79 not on a one-to-one basis (so it must be consistent...). The possible |
78 values are inspired from regular expressions syntax : |
80 values are inspired from regular expression syntax : |
79 |
81 |
80 * `1`: 1..1 |
82 * `1`: 1..1 |
81 * `?`: 0..1 |
83 * `?`: 0..1 |
82 * `+`: 1..n |
84 * `+`: 1..n |
83 * `*`: 0..n |
85 * `*`: 0..n |
84 |
86 |
85 - `meta` : boolean indicating that the relation is a meta-relation (false by |
87 - `meta` : boolean indicating that the relation is a meta-relation (false by |
86 default) |
88 default) |
87 |
89 |
88 * optionnal properties for attributes : |
90 * optional properties for attributes : |
89 |
91 |
90 - `required` : boolean indicating if the attribute is required (false by default) |
92 - `required` : boolean indicating if the attribute is required (false by default) |
91 |
93 |
92 - `unique` : boolean indicating if the value of the attribute has to be unique |
94 - `unique` : boolean indicating if the value of the attribute has to be unique |
93 or not within all entities of the same type (false by default) |
95 or not within all entities of the same type (false by default) |
96 attribute in the database (false by default). This is usefull only if |
98 attribute in the database (false by default). This is usefull only if |
97 you know that you will have to run numerous searches on the value of this |
99 you know that you will have to run numerous searches on the value of this |
98 attribute. |
100 attribute. |
99 |
101 |
100 - `default` : default value of the attribute. In case of date types, the values |
102 - `default` : default value of the attribute. In case of date types, the values |
101 which could be used correpond to the RQL keywords `TODAY` and `NOW`. |
103 which could be used correspond to the RQL keywords `TODAY` and `NOW`. |
102 |
104 |
103 - `vocabulary` : specify static possible values of an attribute |
105 - `vocabulary` : specify static possible values of an attribute |
104 |
106 |
105 * optionnal properties of type `String` : |
107 * optional properties of type `String` : |
106 |
108 |
107 - `fulltextindexed` : boolean indicating if the attribute is part of |
109 - `fulltextindexed` : boolean indicating if the attribute is part of |
108 the full text index (false by default) (*applicable on the type `Byte` |
110 the full text index (false by default) (*applicable on the type `Byte` |
109 as well*) |
111 as well*) |
110 |
112 |
111 - `internationalizable` : boolean indicating if the value of the attribute |
113 - `internationalizable` : boolean indicating if the value of the attribute |
112 is internationalizable (false by default) |
114 is internationalizable (false by default) |
113 |
115 |
114 - `maxsize` : integer providing the maximum size of the string (no limit by default) |
116 - `maxsize` : integer providing the maximum size of the string (no limit by default) |
115 |
117 |
116 * optionnal properties for relations : |
118 * optional properties for relations : |
117 |
119 |
118 - `composite` : string indicating that the subject (composite == 'subject') |
120 - `composite` : string indicating that the subject (composite == 'subject') |
119 is composed of the objects of the relations. For the opposite case (when |
121 is composed of the objects of the relations. For the opposite case (when |
120 the object is composed of the subjects of the relation), we just need |
122 the object is composed of the subjects of the relation), we just set |
121 to set 'object' as the value. The composition implies that when the relation |
123 'object' as value. The composition implies that when the relation |
122 is deleted (so when the composite is deleted), the composed are also deleted. |
124 is deleted (so when the composite is deleted), the composed are also deleted. |
123 |
125 |
124 Contraints |
126 Contraints |
125 `````````` |
127 `````````` |
126 By default, the available constraints types are : |
128 By default, the available constraint types are : |
127 |
129 |
128 * `SizeConstraint` : allows to specify a minimum and/or maximum size on |
130 * `SizeConstraint` : allows to specify a minimum and/or maximum size on |
129 string (generic case of `maxsize`) |
131 string (generic case of `maxsize`) |
130 |
132 |
131 * `BoundConstraint` : allows to specify a minimum and/or maximum value on |
133 * `BoundConstraint` : allows to specify a minimum and/or maximum value on |
133 |
135 |
134 * `UniqueConstraint` : identical to "unique=True" |
136 * `UniqueConstraint` : identical to "unique=True" |
135 |
137 |
136 * `StaticVocabularyConstraint` : identical to "vocabulary=(...)" |
138 * `StaticVocabularyConstraint` : identical to "vocabulary=(...)" |
137 |
139 |
138 * `RQLConstraint` : allows to specify a RQL query that needs to be satisfied |
140 * `RQLConstraint` : allows to specify a RQL query that has to be satisfied |
139 by the subject and/or the object of the relation. In this query the variables |
141 by the subject and/or the object of the relation. In this query the variables |
140 `S` and `O` are reserved for the entities subject and object of the |
142 `S` and `O` are reserved for the entities subject and object of the |
141 relation. |
143 relation. |
142 |
144 |
143 * `RQLVocabularyConstraint` : similar to the previous type of constraint except |
145 * `RQLVocabularyConstraint` : similar to the previous type of constraint except |
144 that it does not express a "strong" constraint, which means it is only used to |
146 that it does not express a "strong" constraint, which means it is only used to |
145 restrict the values listed in the drop-down menu of editing form, but it does |
147 restrict the values listed in the drop-down menu of editing form, but it does |
146 not prevent another entity to be selected |
148 not prevent another entity to be selected. |
147 |
149 |
148 |
150 |
149 Relation definition |
151 Relation definition |
150 ------------------- |
152 ------------------- |
151 |
153 |
152 XXX add note about defining relation type / definition |
154 XXX add note about defining relation type / definition |
153 |
155 |
154 A relation is defined by a Python class heriting `RelationType`. The name |
156 A relation is defined by a Python class heriting `RelationType`. The name |
155 of the class corresponds to the name of the type. The class then contains |
157 of the class corresponds to the name of the type. The class then contains |
156 a description of the properties of this type of relation, and could as well |
158 a description of the properties of this type of relation, and could as well |
157 contains a string for the subject and a string for the object. This allows to create |
159 contain a string for the subject and a string for the object. This allows to create |
158 new definition of associated relations, (so that the class can have the |
160 new definition of associated relations, (so that the class can have the |
159 definition properties from the relation) for example :: |
161 definition properties from the relation) for example :: |
160 |
162 |
161 class locked_by(RelationType): |
163 class locked_by(RelationType): |
162 """relation on all entities indicating that they are locked""" |
164 """relation on all entities indicating that they are locked""" |
172 * `inlined` : boolean handling the physical optimization for archiving |
174 * `inlined` : boolean handling the physical optimization for archiving |
173 the relation in the subject entity table, instead of creating a specific |
175 the relation in the subject entity table, instead of creating a specific |
174 table for the relation. This applies to the relation when the cardinality |
176 table for the relation. This applies to the relation when the cardinality |
175 of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) |
177 of subject->relation->object is 0..1 (`?`) or 1..1 (`1`) |
176 |
178 |
177 * `symetric` : boolean indication that the relation is symetrical, which |
179 * `symmetric` : boolean indicating that the relation is symmetrical, which |
178 means `X relation Y` implies `Y relation X` |
180 means `X relation Y` implies `Y relation X` |
179 |
181 |
180 In the case of simultaneous relations definitions, `subject` and `object` |
182 In the case of simultaneous relations definitions, `subject` and `object` |
181 can both be equal to the value of the first argument of `SubjectRelation` |
183 can both be equal to the value of the first argument of `SubjectRelation` |
182 and `ObjectRelation`. |
184 and `ObjectRelation`. |
183 |
185 |
184 When a relation is not inlined and not symetrical, and it does not require |
186 When a relation is not inlined and not symmetrical, and it does not require |
185 specific permissions, its definition (by using `SubjectRelation` and |
187 specific permissions, its definition (by using `SubjectRelation` and |
186 `ObjectRelation`) is all we need. |
188 `ObjectRelation`) is all we need. |
187 |
189 |
188 |
190 |
189 The security model |
191 The security model |