.. -*- coding: utf-8 -*-

.. _cubes:

Cubes
-----

What is a cube ?
~~~~~~~~~~~~~~~~

A cube is a model grouping one or more entity types and/or views associated
in order to provide a specific feature or even a complete application using
others cubes.

You can decide to write your own set of cubes if you wish to re-use the 
entity types you develop. Lots of cubes are available from the `CubicWeb
Forge`_ under a free software license.

.. _`CubicWeb Forge`: http://www.cubicweb.org/project/

Standard library
~~~~~~~~~~~~~~~~

A library of standard cubes is part of the `CubicWeb` release (look at the
output of ``cubicweb-ctl list``). Cubes provide entities and views.

The available application entities are:

* addressbook: PhoneNumber and PostalAddress

* basket: Basket (like a shopping cart)

* blog: Blog (a *very* basic blog)

* classfolder: Folder (to organize things but grouping them in folders)

* classtags: Tag (to tag anything)

* file: File (to allow users to upload and store binary or text files)

* link: Link (to collect links to web resources)

* mailinglist: MailingList (to reference a mailing-list and the URLs
  for its archives and its admin interface)

* person: Person (easily mixed with addressbook)

* task: Task (something to be done between start and stop date)

* zone: Zone (to define places within larger places, for example a
  city in a state in a country)

The available system entities are:

* comment: Comment (to attach comment threads to entities)


Adding comments to BlogDemo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To import a cube in your application just change the line in the
``app.conf`` file. For example::

    included-yams-cubes=comment

will make the ``Comment`` entity available in your ``BlogDemo``
application.

Change the schema to add a relationship between ``BlogEntry`` and
``Comment`` and you are done. Since the comment cube defines the
``comments`` relationship, adding the line::

    comments = ObjectRelation('Comment', cardinality='1*', composite='object')

to the definition of a ``BlogEntry`` will be enough.

Clear the datastore and restart.

Cube structure
~~~~~~~~~~~~~~

A complex  cube is structured as follows:
::

  mycube/
  |
  |-- schema.py
  |
  |-- entities/
  |
  |-- sobjects/
  |
  |-- views/
  |
  |-- test/
  |
  |-- i18n/
  |
  |-- data/
  |
  |-- migration/
  | |- postcreate.py
  | \- depends.map
  |
  |-- debian/
  |
  \-- __pkginfo__.py

We can also define simple Python module instead of directories (packages), for example:
::

  mycube/
  |
  |-- entities.py
  |-- hooks.py
  \-- views.py


where:

* ``schema`` contains the definition of the schema (server side only)
* ``entities`` contains entities definition (server side and web interface)
* ``sobjects`` contains hooks and/or notification views (server side only)
* ``views`` contains the web interface components (web interface only)
* ``test`` contains tests related to the application (not installed)
* ``i18n`` contains messages 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 file 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-components used by
  the component.
 
At least you should have:

* the file ``__pkginfo__.py``
* schema definition

[WRITE ME]

* explain the cube architecture

* add comments to the blog by importing the comments cube