[book] some more documentation and cleanups
* merged existing facets documentation with the one I've just written and
put almost everything within the code
* added a note about __depends__ and __recommends__ and about the recommends
semantic (extracted from a post on the ml)
* added a note about write security checking (extracted from a post on the ml)
* fixed some dumb sphinx errors
.. _foundationsCube:
.. _cubelayout:
Standard structure for a cube
-----------------------------
A cube is structured as follows:
::
mycube/
|
|-- data/
| |-- cubes.mycube.css
| |-- cubes.mycube.js
| `-- external_resources
|
|-- debian/
| |-- changelog
| |-- compat
| |-- control
| |-- copyright
| |-- cubicweb-mycube.prerm
| `-- rules
|
|-- entities.py
|
|-- i18n/
| |-- en.po
| |-- es.po
| `-- fr.po
|
|-- __init__.py
|
|-- MANIFEST.in
|
|-- migration/
| |-- postcreate.py
| `-- precreate.py
|
|-- __pkginfo__.py
|
|-- schema.py
|
|-- setup.py
|
|-- site_cubicweb.py
|
|-- hooks.py
|
|-- test/
| |-- data/
| | `-- bootstrap_cubes
| |-- pytestconf.py
| |-- realdb_test_mycube.py
| `-- test_mycube.py
|
`-- views.py
We can use subpackages instead of python modules for ``views.py``, ``entities.py``,
``schema.py`` or ``hooks.py``. For example, we could have:
::
mycube/
|
|-- entities.py
|-- hooks.py
`-- views/
|-- __init__.py
|-- forms.py
|-- primary.py
`-- widgets.py
where :
* ``schema`` contains the schema definition (server side only)
* ``entities`` contains the entity definitions (server side and web interface)
* ``hooks`` contains hooks and/or views notifications (server side only)
* ``views`` contains the web interface components (web interface only)
* ``test`` contains tests related to the cube (not installed)
* ``i18n`` contains message catalogs for supported languages (server side and
web interface)
* ``data`` contains data files for static content (images, css,
javascript code)...(web interface only)
* ``migration`` contains initialization files for new instances (``postcreate.py``)
and a file containing dependencies of the component depending on the version
(``depends.map``)
* ``debian`` contains all the files managing debian packaging (you will find
the usual files ``control``, ``rules``, ``changelog``... not installed)
* file ``__pkginfo__.py`` provides component meta-data, especially the distribution
and the current version (server side and web interface) or sub-cubes used by
the cube.
At least you should have the file ``__pkginfo__.py``.
The :file:`__init__.py` and :file:`site_cubicweb.py` files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX WRITEME
The :file:`__pkginfo__.py` file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It contains metadata describing your cube, mostly useful for packaging.
Two important attributes of this module are __depends__ and __recommends__
dictionaries that indicates what should be installed (and each version if
necessary) for the cube to work.
Dependency on other cubes are expected to be of the form 'cubicweb-<cubename>'.
When an instance is created, dependencies are automatically installed, while
recommends are not.
Recommends may be seen as a kind of 'weak dependency'. Eg, the most important
effect of recommending a cube is that, if cube A recommends cube B, the cube B
will be loaded before the cube A (same thing happend when A depends on B).
Having this behaviour is sometime desired: on schema creation, you may rely on
something defined in the other's schema; on database creation, on something
created by the other's postcreate, and so on.
:file:`migration/precreate.py` and :file:`migration/postcreate.py`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX detail steps of instance creation
External resources such as image, javascript and css files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX naming convention external_resources file
Out-of the box testing
~~~~~~~~~~~~~~~~~~~~~~
.. XXX MANIFEST.in, __pkginfo__.include_dirs, debian
Packaging and distribution
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. XXX MANIFEST.in, __pkginfo__.include_dirs, debian