This section defines some terms and core concepts of the |cubicweb| framework. To

avoid confusion while reading this book, take time to go through the following

definitions and use this section as a reference during your reading.

A cube can use other cubes as building blocks and assemble them to provide a

whole with richer functionnalities than its parts. The cubes `cubicweb-blog`_ and

`cubicweb-comment`_ could be used to make a cube named *myblog* with commentable

blog entries.

The `CubicWeb.org Forge`_ offers a large number of cubes developed by the community

The command :command:`cubicweb-ctl list` displays the list of cubes installed on

your system.

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

.. _Instance:

The instance directory contains the configuration files. Several instances can be

created and based on the same cube. For exemple, several software forges can be

set up on one computer system based on the `cubicweb-forge`_ cube.

.. Note::

  The term application is used to refer to "something that should do something as

  a whole", eg more like a project and so can refer to an instance or to a cube,

  depending on the context. This book will try to use *application*, *cube* and

  *instance* as appropriate.

.. _RepositoryIntro:

SQL databases, LDAP repositories, other |cubicweb| instance repositories, GAE's

DataStore, etc).

(:ref:`RQL`). The repository federates the data sources and hides them from the

.. _WebEngineIntro:

.. _SchemaIntro:

Permissions can be set on entity types and relation definition to control who

will be able to create, read, update or delete entities and relations. Permissions

are granted to groups (to which users may belong) or using rql expression (if the

rql expression returns some results, the permission is granted).

.. _VRegistryIntro:

identifier in the same registry, At runtime, appobjects are selected in a

registry according to the context. Selection is done by comparing *score*

returned by each appobject's *selector*.

Application objects are stored in the vregistry using a two-level hierarchy :

  object's `__registry__` : object's `__regid__` : [list of app objects]

E.g. The `vregistry` contains several registries which hold a list of

appobjects associated to an identifier.

The base class of appobjects is :class:`cubicweb.appobject.AppObject`.

Selectors

~~~~~~~~~

Each appobject has a selector, that is used to compute how well the object fits a

given context. The better the object fits the context, the higher the score. They

are the glue that tie appobjects to the data model. Using them appropriately is

an essential part of the construction of well behaved cubes.

|cubicweb| provides a set of basic selectors that may be parametrized.  Also,

selectors can be combined with the `~` unary operator (negation) and the binary

operators `&` and `|` (respectivly 'and' and 'or') to build more complex

selector. Of course complex selector may be combined too.

At startup, the `vregistry` inspects a number of directories looking for

compatible classes definition. After a recording process, the objects are

assigned to registries so that they can be selected dynamically while the

instance is running.

In a cube, appobject classes are looked in the following modules or packages:

- `entities`

- `views`

- `sobjects`

- `hooks`

Once initialized, there are three common ways to retrieve some appobject from a

registry:

* get the most appropriate object by specifying an identifier. In that case, the

  object with the greatest score is selected. There should always be a single

  appobject with a greater score than others for a particular context (see note

  below).

  - If no object has a positive score, :class:`cubicweb.NoSelectableObject`

    exception is raised.

* get all appobjects applying to a context by specifying a registry. In that

  case, a list of objects will be returned containing the object with the

  highest score (> 0) for each identifier in that registry.

In all cases:

- If no object is found for the identifier, :class:`cubicweb.ObjectNotFound`

  exception is raised.

- If you ask the `vregistry` for an unexistant registry,

  :class:`cubicweb.RegistryNotFound` exception is raised.

.. note::

  When no score is higher than the others, an exception is raised in development

  mode to let you know that the engine was not able to identify the view to

  apply. This error is silenced in production mode and one of the objects with

  the higher score is picked.

  In such cases you would need to review your design and make sure your selectors

  or appobjects are properly defined.

.. _RQLIntro:

All the persistent data in a |cubicweb| instance is retrieved and modified by

using the Relation Query Language.

You basically get a connection using :ref:`cubicweb.dbapi.connect` , then

get a cursor to call its `execute` method which will return result set for the

given rql query.

You can also get additional information through the connection, such as the

repository'schema, version configuration, etc.

Every request made (using RQL) to the data repository returns an object we call a

Result Set. It enables easy use of the retrieved data, providing a translation

layer between the backend's native datatypes and |cubicweb| schema's EntityTypes.

Result sets provide access to the raw data, yielding either basic Python data

types, or schema-defined high-level entities, in a straightforward way.

.. _ViewIntro:

**CubicWeb is data driven**

The view system is loosely coupled to data through the selection system explained

above. Views are application objects with a dedicated interface to 'render'

something, eg producing some html, text, xml, pdf, or whatsover that can be

displayed to a user.

The two main entry points of a view are:

* `call()`, used to render a view on a context with no result set, or on a whole

  result set

* `cell_call(row, col)`, used to render a view on a the cell with index `row` and

  `col` of the context's result set (remember result set may be seen as a two

  dimensions array).

Then view may gets refined into different kind of objects such as `template`,

`boxes`, `components`, which are more high-level abstraction useful to build

the user interface in an object oriented way.

.. _HookIntro:

Hooks and operations

--------------------

Hooks are also application objects registered on events such as after/before

add/update/delete on entities/relations, server startup or shutdown, etc. As all

appobjects, they have a selector defining when they should be called or not.

`Operations` may be instantiated by hooks to do further processing at different

steps of the transaction's commit / rollback, which usually can not be done

safely at the hook execution time.

Hooks and operation are an essential building block of any moderately complicated