.. _foundationsCube:

.. _cubelayout:

Standard structure for a cube
-----------------------------

A cube named "mycube" is Python package "cubicweb-mycube" structured as
follows:

::

  cubicweb-mycube/
  |
  |-- cubicweb_mycube/
  |   |
  |   |-- data/
  |   |   |-- cubes.mycube.css
  |   |   |-- cubes.mycube.js
  |   |   `-- external_resources
  |   |
  |   |
  |   |-- entities.py
  |   |
  |   |-- i18n/
  |   |   |-- en.po
  |   |   |-- es.po
  |   |   `-- fr.po
  |   |
  |   |-- __init__.py
  |   |
  |   |
  |   |-- migration/
  |   |   |-- postcreate.py
  |   |   `-- precreate.py
  |   |
  |   |-- __pkginfo__.py
  |   |
  |   |-- schema.py
  |   |
  |   |
  |   |-- site_cubicweb.py
  |   |
  |   |-- hooks.py
  |   |
  |   |
  |   `-- views.py
  |-- debian/
  |   |-- changelog
  |   |-- compat
  |   |-- control
  |   |-- copyright
  |   |-- cubicweb-mycube.prerm
  |   `-- rules
  |-- MANIFEST.in
  |-- setup.py
  `-- test/
      |-- data/
      |   `-- bootstrap_cubes
      |-- pytestconf.py
      |-- realdb_test_mycube.py
      `-- test_mycube.py


We can use subpackages instead of Python modules for ``views.py``, ``entities.py``,
``schema.py`` or ``hooks.py``. For example, we could have:

::

  cubicweb-mycube/
  |
  |-- cubicweb_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.

The :file:`setup.py` file
-------------------------

This is standard setuptools based setup module which reads most of its data
from :file:`__pkginfo__.py`. In the ``setup`` function call, it should also
include an entry point definition under the ``cubicweb.cubes`` group so that
CubicWeb can discover cubes (in particular their custom ``cubicweb-ctl``
commands):

::

    setup(
      # ...
      entry_points={
          'cubicweb.cubes': [
              'mycube=cubicweb_mycube',
          ],
      },
      # ...
    )


: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