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

The Core Concepts of CubicWeb
=============================

.. toctree::
   :maxdepth: 1

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

This section aims to provide you the keys of success with *CubicWeb*
by clarifying the terms specific to our framework. If you want to do anything
serious with CubicWeb, you should understand concepts in those lines.

*CubicWeb* defines its own terminology. To make sure there is no confusion
while reading this book, we strongly recommand you take time to go through
the following definitions that are the basics to understand while
developing with *CubicWeb*.


.. _Cube:

Cubes
-----
** Construct your application by assembling cubes **

A cube provides a specific functionality, or a complete *CubicWeb*
application usually by assembling other cubes.

It's usually composed of a data model, some logic to manipulate it and some parts
of web interface.

You can decide to write your own set of cubes if you wish to re-use the
entity types you develop or/and if you have specific needs not covered by
cubes are available from the `CubicWeb Forge`_ under a free software license.

Available cubes on your system are defined in the directory
:file:`/usr/share/cubicweb/cubes` when using a system wide installation.  For people
using the mercurial repository of cubicweb, the :file:`/path/to/forest/cubicweb/cubes`
directory is used. You can specify additional location using the :envvar:`CW_CUBES_PATH`
environment variable, using ':' as separator.

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



Instances
----------
** *CubicWeb* framework is a server/client application framework**

An instance is a specific installation of one or multiple cubes. All the required
configuration files necessary for the well being of your web application are
grouped in an instance. This will refer to the cube(s) your application is based
on.  For example logilab.org and our intranet are two instances of a single cube
`jpl`

We recommand not to define schema, entities or views in the instance
file system itself but in the cube, in order to maintain re-usability of
entities and their views. We strongly recommand to develop cubes which
could be used in other instances (modular approach).

An instance usually usually consists into a web interface which is talking to a
rql repository, itself connected to a SQL database, all into a single
process. You can have some more complicated configurations using several web
front-ends talking to a rql repository using `Pyro`_, databases replication...

.. image:: ../../images/archi_globale.en.png

The term application is sometimes used to talk about an instance and sometimes to
talk of a cube depending on the context.  So we would like to avoid using this
term and try to use *cube* and *instance* instead.

Data Repository
~~~~~~~~~~~~~~~
The repository (Be carefull not to get confused with a Mercurial repository or a
debian repository!) manages all interactions with various data sources by
providing access to them using uniformly using the Relation Query Language (RQL).  The
web interface and the repository communicate using this language.

Usually, the web server and repository sides are integrated in the same process and
interact directly, without the need for distant calls using Pyro. But, it is
important to note that those two sides, client/server, are disjointed and it is
possible to execute a couple of calls in distinct processes to balance the load
of your web site on one or more machines.


A data source is a container of data integrated in the *CubicWeb* repository. A
repository has at least one source, named `system`, which contains the schema of
the application, plain-text index and other vital informations for the
system. You'll find source for SQL databases, LDAP servers, other RQL
repositories and even mercurial /svn repositories or `Google App Engine`'s
datastore.

Web interface
~~~~~~~~~~~~~
By default the web server provides a generated interface based on its schema.
Entities can be created, displayed, updated and deleted. As display views are not
very fancy, it is usually necessary to develop your own.

Instances are defined on your system in the directory :file:`/etc/cubicweb.d` when
using a system wide installation.  For people using the mercurial repository of
cubicweb, the :file:`etc` directory is searched in the user home directory. You can
also specify an alternative directory using the :envvar:`CW_REGISTRY` environment
variable.



Schema
------
** *CubicWeb* is schema driven **

The schema describes the persistent data model using entities and
relations. It is modeled with a comprehensive language made of Python classes based on
the `yams`_ library.

When you create a new cubicweb instance, the schema is stored in the database,
and it will usually evolves as you upgrade cubicweb and used cubes.

*CubicWeb* provides a certain number of system entities included
sytematically (necessary for the core of *CubicWeb*, notably the schema itself).
You will also find a library of cubes which defines more piece of schema for standard needs.
necessary.

*CubicWeb* add some metadata to every entity type, such as the eid (a global
  identifier, unique into an instance), entity's creation date...


Attributes may be of the following types:
  `String`, `Int`, `Float`, `Boolean`, `Date`, `Time`, `Datetime`,
  `Interval`, `Password`, `Bytes`.

New in 3.2: RichString

see :ref:`yams.BASE_TYPES`

Data level security is defined by setting permissions on entity and relation types.
  
A schema consist of parts detailed below.


Entity type
~~~~~~~~~~~
An *entity type* defines set of attributes and is used in some relations. It may
have some permissions telling who can read/add/update/delete entities of this type.

Relation type
~~~~~~~~~~~~~
A *relation type* is used to define a semantic relation between two entity types.
It may have some permissions telling who can read/add/delete relation of this type.

In *CubicWeb* relations are ordered and binary: by convention we name the first
item of a relation the `subject` and the second the `object`.

Relation definition
~~~~~~~~~~~~~~~~~~~
A *relation definition* is a 3-uple (*subject entity type*, *relation type*, *object
entity type*), with an associated set of property such as cardinality, constraints...



Dynamic objects for reusable components
---------------------------------------
** Dynamic objects management or how CubicWeb provides really reusable components **

Application objects
~~~~~~~~~~~~~~~~~~~
Beside a few core functionalities, almost every feature of the framework is
acheived by dynamic objects (`application objects` or `appobjects`) stored in a
two-levels registry (the `vregistry`). Each object is affected to a registry with
an identifier in this registry. You may have more than one object sharing an
identifier in the same registry, At runtime, appobjects are selected in the
vregistry according to the context.

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

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

The base class of appobjects is `AppRsetObject` (module `cubicweb.appobject`).

The `vregistry`
~~~~~~~~~~~~~~~
At startup, the `registry` or registers base, inspects a number of directories
looking for compatible classes definition. After a recording process, the objects
are assigned to registers so that they can be selected dynamically while the
application is running.

Selectors
~~~~~~~~~
Each appobject has a selector, which is used to score how well it suits to a
given context by returning a score.  A score of 0 means the object doesn't apply
to the context. The score is used to choose the most pertinent object: the "more"
the appobject suits the context the higher the score.

CubicWeb provides a set of basic selectors which may be parametrized and combined
using binary `&` and `|` operators to provide a custom selector (which can be
itself reused...).

There is 3 current ways to retreive some appobject from the repository:

* get the most appropriate objects by specifying a registry and 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.

* get all appobjects applying to a context by specifying a registry.In
  that case, every objects with the a postive score are selected.

* get the object within a particular registry/identifier. In that case no
  selection process is involved, the vregistry will expect to find a single
  object in that cell.

Selector sets are the glue that tie views to the data model. Using them
appropriately is an essential part of the construction of well behaved cubes.


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 silented in production mode and one of the objects with the
higher score is picked. 

If no object has a positive score, ``NoSelectableObject`` exception is raised.

If no object is found for a particular registry and identifier,
``ObjectNotFound`` exception is raised.

In such cases you would need to review your design and make sure your views are
properly defined.



The RQL query language
----------------------
**No needs for a complicated ORM when you've a powerful query language**

All the persistant data in a CubicWeb application is retreived and modified by using the
Relation Query Language.

This query language is inspired by SQL but is on a higher level in order to
emphasize browsing relations.

db-api
~~~~~~
The repository exposes a `db-api`_ like api but using the RQL instead of SQL.
XXX feed me

Result set
~~~~~~~~~~
XXX feed me


Views
-----
** *CubicWeb* is data driven **

XXX feed me.


Hooks
-----
** *CubicWeb* provides an extensible data repository **

XXX feed me.


.. _`Python Remote Object`: http://pyro.sourceforge.net/
.. _`yams`: http://www.logilab.org/project/yams/