.. _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

  |   `-- 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/

      |-- forms.py

      |-- primary.py

      `-- widgets.py

where :

* ``schema`` contains the schema definition (server side only)

* ``entities`` contains the entities definition (server side and web interface)

* ``sobjects`` contains hooks and/or views notifications (server side only)

* ``views`` contains the web interface components (web interface only)

* ``i18n`` contains message catalogs for supported languages (server side and

  web interface)

* ``data`` contains data files for static content (images, css, javascripts)

  ...(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 schema definition

  XXX false, we may want to have cubes which are only adding a service,

  no persistent data (eg embedding for instance)

The :file:`__init__.py` and :file:`site_cubicweb.py` files

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :file:`__pkginfo__.py` file

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

XXX contains metadata describing your cubes

    distname / modname

    version / numversion

    __use__

    __recommend__

: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