42 classes based on `yams`_ library. This is the core piece |
42 classes based on `yams`_ library. This is the core piece |
43 of an application. It is initially defined in the file system and is |
43 of an application. It is initially defined in the file system and is |
44 stored in the database at the time an instance is created. `CubicWeb` |
44 stored in the database at the time an instance is created. `CubicWeb` |
45 provides a certain number of system entities included automatically as |
45 provides a certain number of system entities included automatically as |
46 it is necessary for the core of `CubicWeb` and a library of |
46 it is necessary for the core of `CubicWeb` and a library of |
47 cubes (which defined application entities) that can be explicitely |
47 cubes (which defined application entities) that can be explicitely |
48 included if necessary. |
48 included if necessary. |
49 |
49 |
50 *entity type* |
50 *entity type* |
51 An entity type is a set of attributes; the essential attribute of |
51 An entity type is a set of attributes; the essential attribute of |
52 an entity is its key, named eid. |
52 an entity is its key, named eid. |
67 to an entity attribute. |
67 to an entity attribute. |
68 |
68 |
69 *relation definition* |
69 *relation definition* |
70 A relation definition is a 3-uple (subject entity type, relation type, object |
70 A relation definition is a 3-uple (subject entity type, relation type, object |
71 entity type), with an associated set of property such as cardinality, constraints... |
71 entity type), with an associated set of property such as cardinality, constraints... |
72 |
72 |
73 *repository* |
73 *repository* |
74 This is the RQL server side of `CubicWeb`. Be carefull not to get |
74 This is the RQL server side of `CubicWeb`. Be carefull not to get |
75 confused with a Mercurial repository or a debian repository. |
75 confused with a Mercurial repository or a debian repository. |
76 |
76 |
77 *source* |
77 *source* |
78 A data source is a container of data (SGBD, LDAP directory, `Google |
78 A data source is a container of data (SGBD, LDAP directory, `Google |
79 App Engine`'s datastore ...) integrated in the |
79 App Engine`'s datastore ...) integrated in the |
80 `CubicWeb` repository. This repository has at least one source, `system` which |
80 `CubicWeb` repository. This repository has at least one source, `system` which |
81 contains the schema of the application, plain-text index and others |
81 contains the schema of the application, plain-text index and others |
82 vital informations for the system. |
82 vital informations for the system. |
83 |
83 |
84 *configuration* |
84 *configuration* |
85 It is possible to create differents configurations for an instance: |
85 It is possible to create differents configurations for an instance: |
86 |
86 |
87 - ``repository`` : repository only, accessible for clients using Pyro |
87 - ``repository`` : repository only, accessible for clients using Pyro |
88 - ``twisted`` : web interface only, access the repository using Pyro |
88 - ``twisted`` : web interface only, access the repository using Pyro |
89 - ``all-in-one`` : web interface and repository in a single process. |
89 - ``all-in-one`` : web interface and repository in a single process. |
90 The repository could be or not accessible using Pyro. |
90 The repository could be or not accessible using Pyro. |
91 |
91 |
92 *cube* |
92 *cube* |
93 A cube is a model grouping one or multiple data types and/or views |
93 A cube is a model grouping one or multiple data types and/or views |
94 to provide a specific functionnality or a complete `CubicWeb` application |
94 to provide a specific functionnality or a complete `CubicWeb` application |
95 potentially using other cubes. The available cubes are located in the file |
95 potentially using other cubes. The available cubes are located in the file |
96 system at `/path/to/forest/cubicweb/cubes` for a Mercurial forest installation, |
96 system at `/path/to/forest/cubicweb/cubes` for a Mercurial forest installation, |
97 for a debian packages installation they will be located in |
97 for a debian packages installation they will be located in |
98 `/usr/share/cubicweb/cubes`. |
98 `/usr/share/cubicweb/cubes`. |
99 Larger applications can be built faster by importing cubes, |
99 Larger applications can be built faster by importing cubes, |
100 adding entities and relationships and overriding the |
100 adding entities and relationships and overriding the |
101 views that need to display or edit informations not provided by |
101 views that need to display or edit informations not provided by |
102 cubes. |
102 cubes. |
103 |
103 |
104 *instance* |
104 *instance* |
105 An instance is a specific installation of one or multiple cubes. All the required |
105 An instance is a specific installation of one or multiple cubes. All the required |
106 configuration files necessary for the well being of your web application |
106 configuration files necessary for the well being of your web application |
107 are grouped in an instance. This will refer to the cube(s) your application |
107 are grouped in an instance. This will refer to the cube(s) your application |
108 is based on. |
108 is based on. |
109 For example logilab.org and our intranet are two instances of a single |
109 For example logilab.org and our intranet are two instances of a single |
110 cube jpl, developped internally. |
110 cube jpl, developped internally. |
111 The instances are defined in the directory `/etc/cubicweb.d`. |
111 The instances are defined in the directory `/etc/cubicweb.d`. |
112 |
112 |
113 *application* |
113 *application* |
114 The term application is sometime used to talk about an instance |
114 The term application is sometime used to talk about an instance |
115 and sometimes to talk of a cube depending on the context. |
115 and sometimes to talk of a cube depending on the context. |
116 So we would like to avoid using this term and try to use *cube* and |
116 So we would like to avoid using this term and try to use *cube* and |
117 *instance* instead. |
117 *instance* instead. |
118 |
118 |
119 *result set* |
119 *result set* |
120 This object contains the results of an RQL query sent to the source |
120 This object contains the results of an RQL query sent to the source |
125 (Remote Method Invocation), which can be used for the dialog between the web |
125 (Remote Method Invocation), which can be used for the dialog between the web |
126 side of the framework and the RQL repository. |
126 side of the framework and the RQL repository. |
127 |
127 |
128 *query language* |
128 *query language* |
129 A full-blown query language named RQL is used to formulate requests |
129 A full-blown query language named RQL is used to formulate requests |
130 to the database or any sources such as LDAP or `Google App Engine`'s |
130 to the database or any sources such as LDAP or `Google App Engine`'s |
131 datastore. |
131 datastore. |
132 |
132 |
133 *views* |
133 *views* |
134 A view is applied to a `result set` to present it as HTML, XML, |
134 A view is applied to a `result set` to present it as HTML, XML, |
135 JSON, CSV, etc. Views are implemented as Python classes. There is no |
135 JSON, CSV, etc. Views are implemented as Python classes. There is no |
192 |
192 |
193 API Python/RQL |
193 API Python/RQL |
194 ~~~~~~~~~~~~~~ |
194 ~~~~~~~~~~~~~~ |
195 |
195 |
196 The Python API developped to interface with RQL is inspired from the standard db-api, |
196 The Python API developped to interface with RQL is inspired from the standard db-api, |
197 with a Connection object having the methods cursor, rollback and commit essentially. |
197 with a Connection object having the methods cursor, rollback and commit essentially. |
198 The most important method is the `execute` method of a cursor : |
198 The most important method is the `execute` method of a cursor : |
199 |
199 |
200 `execute(rqlstring, args=None, eid_key=None, build_descr=True)` |
200 `execute(rqlstring, args=None, eid_key=None, build_descr=True)` |
201 |
201 |
202 :rqlstring: the RQL query to execute (unicode) |
202 :rqlstring: the RQL query to execute (unicode) |
203 :args: if the query contains substitutions, a dictionnary containing the values to use |
203 :args: if the query contains substitutions, a dictionnary containing the values to use |
204 :eid_key: |
204 :eid_key: |
205 an implementation detail of the RQL queries cache implies that if a substitution |
205 an implementation detail of the RQL queries cache implies that if a substitution |
206 is used to introduce an eid *susceptible to raise the ambiguities in the query |
206 is used to introduce an eid *susceptible to raise the ambiguities in the query |
207 type resolution*, then we have to specify the correponding key in the dictionnary |
207 type resolution*, then we have to specify the correponding key in the dictionnary |
208 through this argument |
208 through this argument |
209 |
209 |
210 |
210 |
211 The `Connection` object owns the methods `commit` and `rollback`. You *should |
211 The `Connection` object owns the methods `commit` and `rollback`. You *should |
212 never need to use them* during the development of the web interface based on |
212 never need to use them* during the development of the web interface based on |
213 the `CubicWeb` framework as it determines the end of the transaction depending |
213 the `CubicWeb` framework as it determines the end of the transaction depending |
214 on the query execution success. |
214 on the query execution success. |
215 |
215 |
216 .. note:: |
216 .. note:: |
217 While executing updates queries (SET, INSERT, DELETE), if a query generates |
217 While executing updates queries (SET, INSERT, DELETE), if a query generates |
218 an error related to security, a rollback is automatically done on the current |
218 an error related to security, a rollback is automatically done on the current |
219 transaction. |
219 transaction. |
220 |
220 |
221 |
221 |
222 The `Request` class (`cubicweb.web`) |
222 The `Request` class (`cubicweb.web`) |
223 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
223 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
224 |
224 |
225 A request instance is created when an HTTP request is sent to the web server. |
225 A request instance is created when an HTTP request is sent to the web server. |
241 * `session_data()`, returns a dictionnary containing all the session data |
241 * `session_data()`, returns a dictionnary containing all the session data |
242 * `get_session_data(key, default=None)`, returns a value associated to the given |
242 * `get_session_data(key, default=None)`, returns a value associated to the given |
243 key or the value `default` if the key is not defined |
243 key or the value `default` if the key is not defined |
244 * `set_session_data(key, value)`, assign a value to a key |
244 * `set_session_data(key, value)`, assign a value to a key |
245 * `del_session_data(key)`, suppress the value associated to a key |
245 * `del_session_data(key)`, suppress the value associated to a key |
246 |
246 |
247 |
247 |
248 :Cookies handling: |
248 :Cookies handling: |
249 * `get_cookie()`, returns a dictionnary containing the value of the header |
249 * `get_cookie()`, returns a dictionnary containing the value of the header |
250 HTTP 'Cookie' |
250 HTTP 'Cookie' |
251 * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`, |
251 * `set_cookie(cookie, key, maxage=300)`, adds a header HTTP `Set-Cookie`, |
331 |
331 |
332 * `complete_entity(row, col=0, skip_bytes=True)`, is equivalent to `entity` but |
332 * `complete_entity(row, col=0, skip_bytes=True)`, is equivalent to `entity` but |
333 also call the method `complete()` on the entity before returning it |
333 also call the method `complete()` on the entity before returning it |
334 |
334 |
335 :Data formatting: |
335 :Data formatting: |
336 * `format_date(date, date_format=None, time=False)` returns a string for a |
336 * `format_date(date, date_format=None, time=False)` returns a string for a |
337 mx date time according to application's configuration |
337 mx date time according to application's configuration |
338 * `format_time(time)` returns a string for a mx date time according to |
338 * `format_time(time)` returns a string for a mx date time according to |
339 application's configuration |
339 application's configuration |
340 |
340 |
341 :And more...: |
341 :And more...: |
342 |
342 |
343 * `external_resource(rid, default=_MARKER)`, access to a value defined in the |
343 * `external_resource(rid, default=_MARKER)`, access to a value defined in the |
344 configuration file `external_resource` |
344 configuration file `external_resource` |
345 |
345 |
346 * `tal_render(template, variables)`, renders a precompiled page template with |
346 * `tal_render(template, variables)`, renders a precompiled page template with |
347 variables in the given dictionary as context |
347 variables in the given dictionary as context |
348 |
348 |
349 .. note:: |
349 .. note:: |
350 When we inherit from `AppObject` (even not directly), you *always* have to use |
350 When we inherit from `AppObject` (even not directly), you *always* have to use |
351 **super()** to get the methods and attributes of the superclasses, and not |
351 **super()** to get the methods and attributes of the superclasses, and not |
470 * ``debian`` contains all the files managing debian packaging (you will find |
470 * ``debian`` contains all the files managing debian packaging (you will find |
471 the usual files ``control``, ``rules``, ``changelog``... not installed) |
471 the usual files ``control``, ``rules``, ``changelog``... not installed) |
472 * file ``__pkginfo__.py`` provides component meta-data, especially the distribution |
472 * file ``__pkginfo__.py`` provides component meta-data, especially the distribution |
473 and the current version (server side and web interface) or sub-cubes used by |
473 and the current version (server side and web interface) or sub-cubes used by |
474 the cube. |
474 the cube. |
475 |
475 |
476 |
476 |
477 At least you should have: |
477 At least you should have: |
478 |
478 |
479 * the file ``__pkginfo__.py`` |
479 * the file ``__pkginfo__.py`` |
480 * the schema definition |
480 * the schema definition |
481 XXX false, we may want to have cubes which are only adding a service, |
481 XXX false, we may want to have cubes which are only adding a service, |
482 no persistent data (eg embeding for instance) |
482 no persistent data (eg embeding for instance) |
483 |
483 |
484 |
484 |
485 Standard library |
485 Standard library |
486 ```````````````` |
486 ```````````````` |