|
1 .. -*- coding: utf-8 -*- |
|
2 |
|
3 The Core Concepts of CubicWeb |
|
4 ============================= |
|
5 |
|
6 .. toctree:: |
|
7 :maxdepth: 1 |
|
8 |
|
9 ------------------------------ |
|
10 |
|
11 This section aims to provide you the keys of success with *CubicWeb* |
|
12 by clarifying the terms specific to our framework. If you want to do anything |
|
13 serious with CubicWeb, you should understand concepts in those lines. |
|
14 |
|
15 *CubicWeb* defines its own terminology. To make sure there is no confusion |
|
16 while reading this book, we strongly recommand you take time to go through |
|
17 the following definitions that are the basics to understand while |
|
18 developing with *CubicWeb*. |
|
19 |
|
20 |
|
21 .. _Cube: |
|
22 |
|
23 Cubes |
|
24 ----- |
|
25 ** Construct your application by assembling cubes ** |
|
26 |
|
27 A cube provides a specific functionality, or a complete *CubicWeb* |
|
28 application usually by assembling other cubes. |
|
29 |
|
30 It's usually composed of a data model, some logic to manipulate it and some parts |
|
31 of web interface. |
|
32 |
|
33 You can decide to write your own set of cubes if you wish to re-use the |
|
34 entity types you develop or/and if you have specific needs not covered by |
|
35 cubes are available from the `CubicWeb Forge`_ under a free software license. |
|
36 |
|
37 Available cubes on your system are defined in the directory |
|
38 :file:`/usr/share/cubicweb/cubes` when using a system wide installation. For people |
|
39 using the mercurial repository of cubicweb, the :file:`/path/to/forest/cubicweb/cubes` |
|
40 directory is used. You can specify additional location using the :envvar:`CW_CUBES_PATH` |
|
41 environment variable, using ':' as separator. |
|
42 |
|
43 .. _`CubicWeb Forge`: http://www.cubicweb.org/project/ |
|
44 |
|
45 |
|
46 |
|
47 Instances |
|
48 ---------- |
|
49 ** *CubicWeb* framework is a server/client application framework** |
|
50 |
|
51 An instance is a specific installation of one or multiple cubes. All the required |
|
52 configuration files necessary for the well being of your web application are |
|
53 grouped in an instance. This will refer to the cube(s) your application is based |
|
54 on. For example logilab.org and our intranet are two instances of a single cube |
|
55 `jpl` |
|
56 |
|
57 We recommand not to define schema, entities or views in the instance |
|
58 file system itself but in the cube, in order to maintain re-usability of |
|
59 entities and their views. We strongly recommand to develop cubes which |
|
60 could be used in other instances (modular approach). |
|
61 |
|
62 An instance usually usually consists into a web interface which is talking to a |
|
63 rql repository, itself connected to a SQL database, all into a single |
|
64 process. You can have some more complicated configurations using several web |
|
65 front-ends talking to a rql repository using `Pyro`_, databases replication... |
|
66 |
|
67 .. image:: ../../images/archi_globale.en.png |
|
68 |
|
69 The term application is sometimes used to talk about an instance and sometimes to |
|
70 talk of a cube depending on the context. So we would like to avoid using this |
|
71 term and try to use *cube* and *instance* instead. |
|
72 |
|
73 Data Repository |
|
74 ~~~~~~~~~~~~~~~ |
|
75 The repository (Be carefull not to get confused with a Mercurial repository or a |
|
76 debian repository!) manages all interactions with various data sources by |
|
77 providing access to them using uniformly using the Relation Query Language (RQL). The |
|
78 web interface and the repository communicate using this language. |
|
79 |
|
80 Usually, the web server and repository sides are integrated in the same process and |
|
81 interact directly, without the need for distant calls using Pyro. But, it is |
|
82 important to note that those two sides, client/server, are disjointed and it is |
|
83 possible to execute a couple of calls in distinct processes to balance the load |
|
84 of your web site on one or more machines. |
|
85 |
|
86 |
|
87 A data source is a container of data integrated in the *CubicWeb* repository. A |
|
88 repository has at least one source, named `system`, which contains the schema of |
|
89 the application, plain-text index and other vital informations for the |
|
90 system. You'll find source for SQL databases, LDAP servers, other RQL |
|
91 repositories and even mercurial /svn repositories or `Google App Engine`'s |
|
92 datastore. |
|
93 |
|
94 Web interface |
|
95 ~~~~~~~~~~~~~ |
|
96 By default the web server provides a generated interface based on its schema. |
|
97 Entities can be created, displayed, updated and deleted. As display views are not |
|
98 very fancy, it is usually necessary to develop your own. |
|
99 |
|
100 Instances are defined on your system in the directory :file:`/etc/cubicweb.d` when |
|
101 using a system wide installation. For people using the mercurial repository of |
|
102 cubicweb, the :file:`etc` directory is searched in the user home directory. You can |
|
103 also specify an alternative directory using the :envvar:`CW_REGISTRY` environment |
|
104 variable. |
|
105 |
|
106 |
|
107 |
|
108 Schema |
|
109 ------ |
|
110 ** *CubicWeb* is schema driven ** |
|
111 |
|
112 The schema describes the persistent data model using entities and |
|
113 relations. It is modeled with a comprehensive language made of Python classes based on |
|
114 the `yams`_ library. |
|
115 |
|
116 When you create a new cubicweb instance, the schema is stored in the database, |
|
117 and it will usually evolves as you upgrade cubicweb and used cubes. |
|
118 |
|
119 *CubicWeb* provides a certain number of system entities included |
|
120 sytematically (necessary for the core of *CubicWeb*, notably the schema itself). |
|
121 You will also find a library of cubes which defines more piece of schema for standard needs. |
|
122 necessary. |
|
123 |
|
124 *CubicWeb* add some metadata to every entity type, such as the eid (a global |
|
125 identifier, unique into an instance), entity's creation date... |
|
126 |
|
127 |
|
128 Attributes may be of the following types: |
|
129 `String`, `Int`, `Float`, `Boolean`, `Date`, `Time`, `Datetime`, |
|
130 `Interval`, `Password`, `Bytes`. |
|
131 |
|
132 New in 3.2: RichString |
|
133 |
|
134 see :ref:`yams.BASE_TYPES` |
|
135 |
|
136 Data level security is defined by setting permissions on entity and relation types. |
|
137 |
|
138 A schema consist of parts detailed below. |
|
139 |
|
140 |
|
141 Entity type |
|
142 ~~~~~~~~~~~ |
|
143 An *entity type* defines set of attributes and is used in some relations. It may |
|
144 have some permissions telling who can read/add/update/delete entities of this type. |
|
145 |
|
146 Relation type |
|
147 ~~~~~~~~~~~~~ |
|
148 A *relation type* is used to define a semantic relation between two entity types. |
|
149 It may have some permissions telling who can read/add/delete relation of this type. |
|
150 |
|
151 In *CubicWeb* relations are ordered and binary: by convention we name the first |
|
152 item of a relation the `subject` and the second the `object`. |
|
153 |
|
154 Relation definition |
|
155 ~~~~~~~~~~~~~~~~~~~ |
|
156 A *relation definition* is a 3-uple (*subject entity type*, *relation type*, *object |
|
157 entity type*), with an associated set of property such as cardinality, constraints... |
|
158 |
|
159 |
|
160 |
|
161 Dynamic objects for reusable components |
|
162 --------------------------------------- |
|
163 ** Dynamic objects management or how CubicWeb provides really reusable components ** |
|
164 |
|
165 Application objects |
|
166 ~~~~~~~~~~~~~~~~~~~ |
|
167 Beside a few core functionalities, almost every feature of the framework is |
|
168 acheived by dynamic objects (`application objects` or `appobjects`) stored in a |
|
169 two-levels registry (the `vregistry`). Each object is affected to a registry with |
|
170 an identifier in this registry. You may have more than one object sharing an |
|
171 identifier in the same registry, At runtime, appobjects are selected in the |
|
172 vregistry according to the context. |
|
173 |
|
174 Application objects are stored in the registry using a two level hierarchy : |
|
175 |
|
176 object's `__registry__` : object's `id` : [list of app objects] |
|
177 |
|
178 The base class of appobjects is `AppRsetObject` (module `cubicweb.appobject`). |
|
179 |
|
180 The `vregistry` |
|
181 ~~~~~~~~~~~~~~~ |
|
182 At startup, the `registry` or registers base, inspects a number of directories |
|
183 looking for compatible classes definition. After a recording process, the objects |
|
184 are assigned to registers so that they can be selected dynamically while the |
|
185 application is running. |
|
186 |
|
187 Selectors |
|
188 ~~~~~~~~~ |
|
189 Each appobject has a selector, which is used to score how well it suits to a |
|
190 given context by returning a score. A score of 0 means the object doesn't apply |
|
191 to the context. The score is used to choose the most pertinent object: the "more" |
|
192 the appobject suits the context the higher the score. |
|
193 |
|
194 CubicWeb provides a set of basic selectors which may be parametrized and combined |
|
195 using binary `&` and `|` operators to provide a custom selector (which can be |
|
196 itself reused...). |
|
197 |
|
198 There is 3 current ways to retreive some appobject from the repository: |
|
199 |
|
200 * get the most appropriate objects by specifying a registry and an identifier. In |
|
201 that case, the object with the greatest score is selected. There should always |
|
202 be a single appobject with a greater score than others. |
|
203 |
|
204 * get all appobjects applying to a context by specifying a registry.In |
|
205 that case, every objects with the a postive score are selected. |
|
206 |
|
207 * get the object within a particular registry/identifier. In that case no |
|
208 selection process is involved, the vregistry will expect to find a single |
|
209 object in that cell. |
|
210 |
|
211 Selector sets are the glue that tie views to the data model. Using them |
|
212 appropriately is an essential part of the construction of well behaved cubes. |
|
213 |
|
214 |
|
215 When no score is higher than the others, an exception is raised in development |
|
216 mode to let you know that the engine was not able to identify the view to |
|
217 apply. This error is silented in production mode and one of the objects with the |
|
218 higher score is picked. |
|
219 |
|
220 If no object has a positive score, ``NoSelectableObject`` exception is raised. |
|
221 |
|
222 If no object is found for a particular registry and identifier, |
|
223 ``ObjectNotFound`` exception is raised. |
|
224 |
|
225 In such cases you would need to review your design and make sure your views are |
|
226 properly defined. |
|
227 |
|
228 |
|
229 |
|
230 The RQL query language |
|
231 ---------------------- |
|
232 **No needs for a complicated ORM when you've a powerful query language** |
|
233 |
|
234 All the persistant data in a CubicWeb application is retreived and modified by using the |
|
235 Relation Query Language. |
|
236 |
|
237 This query language is inspired by SQL but is on a higher level in order to |
|
238 emphasize browsing relations. |
|
239 |
|
240 db-api |
|
241 ~~~~~~ |
|
242 The repository exposes a `db-api`_ like api but using the RQL instead of SQL. |
|
243 XXX feed me |
|
244 |
|
245 Result set |
|
246 ~~~~~~~~~~ |
|
247 XXX feed me |
|
248 |
|
249 |
|
250 Views |
|
251 ----- |
|
252 ** *CubicWeb* is data driven ** |
|
253 |
|
254 XXX feed me. |
|
255 |
|
256 |
|
257 Hooks |
|
258 ----- |
|
259 ** *CubicWeb* provides an extensible data repository ** |
|
260 |
|
261 XXX feed me. |
|
262 |
|
263 |
|
264 .. _`Python Remote Object`: http://pyro.sourceforge.net/ |
|
265 .. _`yams`: http://www.logilab.org/project/yams/ |