1 |
|
2 .. _foundationsCube: |
|
3 |
|
4 .. _cubelayout: |
|
5 |
|
6 Standard structure for a cube |
|
7 ----------------------------- |
|
8 |
|
9 A cube is structured as follows: |
|
10 |
|
11 :: |
|
12 |
|
13 mycube/ |
|
14 | |
|
15 |-- data/ |
|
16 | |-- cubes.mycube.css |
|
17 | |-- cubes.mycube.js |
|
18 | `-- external_resources |
|
19 | |
|
20 |-- debian/ |
|
21 | |-- changelog |
|
22 | |-- compat |
|
23 | |-- control |
|
24 | |-- copyright |
|
25 | |-- cubicweb-mycube.prerm |
|
26 | `-- rules |
|
27 | |
|
28 |-- entities.py |
|
29 | |
|
30 |-- i18n/ |
|
31 | |-- en.po |
|
32 | |-- es.po |
|
33 | `-- fr.po |
|
34 | |
|
35 |-- __init__.py |
|
36 | |
|
37 |-- MANIFEST.in |
|
38 | |
|
39 |-- migration/ |
|
40 | |-- postcreate.py |
|
41 | `-- precreate.py |
|
42 | |
|
43 |-- __pkginfo__.py |
|
44 | |
|
45 |-- schema.py |
|
46 | |
|
47 |-- setup.py |
|
48 | |
|
49 |-- site_cubicweb.py |
|
50 | |
|
51 |-- hooks.py |
|
52 | |
|
53 |-- test/ |
|
54 | |-- data/ |
|
55 | | `-- bootstrap_cubes |
|
56 | |-- pytestconf.py |
|
57 | |-- realdb_test_mycube.py |
|
58 | `-- test_mycube.py |
|
59 | |
|
60 `-- views.py |
|
61 |
|
62 |
|
63 We can use subpackages instead of python modules for ``views.py``, ``entities.py``, |
|
64 ``schema.py`` or ``hooks.py``. For example, we could have: |
|
65 |
|
66 :: |
|
67 |
|
68 mycube/ |
|
69 | |
|
70 |-- entities.py |
|
71 |-- hooks.py |
|
72 `-- views/ |
|
73 |-- __init__.py |
|
74 |-- forms.py |
|
75 |-- primary.py |
|
76 `-- widgets.py |
|
77 |
|
78 |
|
79 where : |
|
80 |
|
81 * ``schema`` contains the schema definition (server side only) |
|
82 * ``entities`` contains the entity definitions (server side and web interface) |
|
83 * ``hooks`` contains hooks and/or views notifications (server side only) |
|
84 * ``views`` contains the web interface components (web interface only) |
|
85 * ``test`` contains tests related to the cube (not installed) |
|
86 * ``i18n`` contains message catalogs for supported languages (server side and |
|
87 web interface) |
|
88 * ``data`` contains data files for static content (images, css, |
|
89 javascript code)...(web interface only) |
|
90 * ``migration`` contains initialization files for new instances (``postcreate.py``) |
|
91 and a file containing dependencies of the component depending on the version |
|
92 (``depends.map``) |
|
93 * ``debian`` contains all the files managing debian packaging (you will find |
|
94 the usual files ``control``, ``rules``, ``changelog``... not installed) |
|
95 * file ``__pkginfo__.py`` provides component meta-data, especially the distribution |
|
96 and the current version (server side and web interface) or sub-cubes used by |
|
97 the cube. |
|
98 |
|
99 |
|
100 At least you should have the file ``__pkginfo__.py``. |
|
101 |
|
102 |
|
103 The :file:`__init__.py` and :file:`site_cubicweb.py` files |
|
104 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
105 |
|
106 .. XXX WRITEME |
|
107 |
|
108 The :file:`__pkginfo__.py` file |
|
109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
110 |
|
111 It contains metadata describing your cube, mostly useful for packaging. |
|
112 |
|
113 Two important attributes of this module are __depends__ and __recommends__ |
|
114 dictionaries that indicates what should be installed (and each version if |
|
115 necessary) for the cube to work. |
|
116 |
|
117 Dependency on other cubes are expected to be of the form 'cubicweb-<cubename>'. |
|
118 |
|
119 When an instance is created, dependencies are automatically installed, while |
|
120 recommends are not. |
|
121 |
|
122 Recommends may be seen as a kind of 'weak dependency'. Eg, the most important |
|
123 effect of recommending a cube is that, if cube A recommends cube B, the cube B |
|
124 will be loaded before the cube A (same thing happend when A depends on B). |
|
125 |
|
126 Having this behaviour is sometime desired: on schema creation, you may rely on |
|
127 something defined in the other's schema; on database creation, on something |
|
128 created by the other's postcreate, and so on. |
|
129 |
|
130 |
|
131 :file:`migration/precreate.py` and :file:`migration/postcreate.py` |
|
132 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
133 |
|
134 .. XXX detail steps of instance creation |
|
135 |
|
136 |
|
137 External resources such as image, javascript and css files |
|
138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
139 |
|
140 .. XXX naming convention external_resources file |
|
141 |
|
142 |
|
143 Out-of the box testing |
|
144 ~~~~~~~~~~~~~~~~~~~~~~ |
|
145 |
|
146 .. XXX MANIFEST.in, __pkginfo__.include_dirs, debian |
|
147 |
|
148 |
|
149 Packaging and distribution |
|
150 ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
151 |
|
152 .. XXX MANIFEST.in, __pkginfo__.include_dirs, debian |
|
153 |
|