1 .. _TutosPhotoWebSiteCubeCreation: |
|
2 |
|
3 Cube creation and schema definition |
|
4 ----------------------------------- |
|
5 |
|
6 .. _adv_tuto_create_new_cube: |
|
7 |
|
8 Step 1: creating a new cube for my web site |
|
9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
10 |
|
11 One note about my development environment: I wanted to use the packaged |
|
12 version of CubicWeb and cubes while keeping my cube in my user |
|
13 directory, let's say `~src/cubes`. I achieve this by setting the |
|
14 following environment variables:: |
|
15 |
|
16 CW_CUBES_PATH=~/src/cubes |
|
17 CW_MODE=user |
|
18 |
|
19 I can now create the cube which will hold custom code for this web |
|
20 site using:: |
|
21 |
|
22 cubicweb-ctl newcube --directory=~/src/cubes sytweb |
|
23 |
|
24 |
|
25 .. _adv_tuto_assemble_cubes: |
|
26 |
|
27 Step 2: pick building blocks into existing cubes |
|
28 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
29 |
|
30 Almost everything I want to handle in my web-site is somehow already modelized in |
|
31 existing cubes that I'll extend for my need. So I'll pick the following cubes: |
|
32 |
|
33 * `folder`, containing the `Folder` entity type, which will be used as |
|
34 both 'album' and a way to map file system folders. Entities are |
|
35 added to a given folder using the `filed_under` relation. |
|
36 |
|
37 * `file`, containing `File` entity type, gallery view, and a file system import |
|
38 utility. |
|
39 |
|
40 * `zone`, containing the `Zone` entity type for hierarchical geographical |
|
41 zones. Entities (including sub-zones) are added to a given zone using the |
|
42 `situated_in` relation. |
|
43 |
|
44 * `person`, containing the `Person` entity type plus some basic views. |
|
45 |
|
46 * `comment`, providing a full commenting system allowing one to comment entity types |
|
47 supporting the `comments` relation by adding a `Comment` entity. |
|
48 |
|
49 * `tag`, providing a full tagging system as an easy and powerful way to classify |
|
50 entities supporting the `tags` relation by linking the to `Tag` entities. This |
|
51 will allows navigation into a large number of picture. |
|
52 |
|
53 Ok, now I'll tell my cube requires all this by editing :file:`cubes/sytweb/__pkginfo__.py`: |
|
54 |
|
55 .. sourcecode:: python |
|
56 |
|
57 __depends__ = {'cubicweb': '>= 3.10.0', |
|
58 'cubicweb-file': '>= 1.9.0', |
|
59 'cubicweb-folder': '>= 1.1.0', |
|
60 'cubicweb-person': '>= 1.2.0', |
|
61 'cubicweb-comment': '>= 1.2.0', |
|
62 'cubicweb-tag': '>= 1.2.0', |
|
63 'cubicweb-zone': None} |
|
64 |
|
65 Notice that you can express minimal version of the cube that should be used, |
|
66 `None` meaning whatever version available. All packages starting with 'cubicweb-' |
|
67 will be recognized as being cube, not bare python packages. You can still specify |
|
68 this explicitly using instead the `__depends_cubes__` dictionary which should |
|
69 contains cube's name without the prefix. So the example below would be written |
|
70 as: |
|
71 |
|
72 .. sourcecode:: python |
|
73 |
|
74 __depends__ = {'cubicweb': '>= 3.10.0'} |
|
75 __depends_cubes__ = {'file': '>= 1.9.0', |
|
76 'folder': '>= 1.1.0', |
|
77 'person': '>= 1.2.0', |
|
78 'comment': '>= 1.2.0', |
|
79 'tag': '>= 1.2.0', |
|
80 'zone': None} |
|
81 |
|
82 If your cube is packaged for debian, it's a good idea to update the |
|
83 `debian/control` file at the same time, so you won't forget it. |
|
84 |
|
85 |
|
86 Step 3: glue everything together in my cube's schema |
|
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
88 |
|
89 .. sourcecode:: python |
|
90 |
|
91 from yams.buildobjs import RelationDefinition |
|
92 |
|
93 class comments(RelationDefinition): |
|
94 subject = 'Comment' |
|
95 object = 'File' |
|
96 cardinality = '1*' |
|
97 composite = 'object' |
|
98 |
|
99 class tags(RelationDefinition): |
|
100 subject = 'Tag' |
|
101 object = 'File' |
|
102 |
|
103 class filed_under(RelationDefinition): |
|
104 subject = 'File' |
|
105 object = 'Folder' |
|
106 |
|
107 class situated_in(RelationDefinition): |
|
108 subject = 'File' |
|
109 object = 'Zone' |
|
110 |
|
111 class displayed_on(RelationDefinition): |
|
112 subject = 'Person' |
|
113 object = 'File' |
|
114 |
|
115 |
|
116 This schema: |
|
117 |
|
118 * allows to comment and tag on `File` entity type by adding the `comments` and |
|
119 `tags` relations. This should be all we've to do for this feature since the |
|
120 related cubes provide 'pluggable section' which are automatically displayed on |
|
121 the primary view of entity types supporting the relation. |
|
122 |
|
123 * adds a `situated_in` relation definition so that image entities can be |
|
124 geolocalized. |
|
125 |
|
126 * add a new relation `displayed_on` relation telling who can be seen on a |
|
127 picture. |
|
128 |
|
129 This schema will probably have to evolve as time goes (for security handling at |
|
130 least), but since the possibility to let a schema evolve is one of CubicWeb's |
|
131 features (and goals), we won't worry about it for now and see that later when needed. |
|
132 |
|
133 |
|
134 Step 4: creating the instance |
|
135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
136 |
|
137 Now that I have a schema, I want to create an instance. To |
|
138 do so using this new 'sytweb' cube, I run:: |
|
139 |
|
140 cubicweb-ctl create sytweb sytweb_instance |
|
141 |
|
142 Hint: if you get an error while the database is initialized, you can |
|
143 avoid having to answer the questions again by running:: |
|
144 |
|
145 cubicweb-ctl db-create sytweb_instance |
|
146 |
|
147 This will use your already configured instance and start directly from the create |
|
148 database step, thus skipping questions asked by the 'create' command. |
|
149 |
|
150 Once the instance and database are fully initialized, run :: |
|
151 |
|
152 cubicweb-ctl start sytweb_instance |
|
153 |
|
154 to start the instance, check you can connect on it, etc... |
|
155 |
|