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 is a software component made of three parts: its data model (schema), its logic (entities) and its user interface (views).
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 Forge offers a large number of cubes developed by the community and available under a free software license.
The command cubicweb-ctl list displays the list of cubes installed on your system.
On a Unix system, the available cubes are usually stored in the directory /usr/share/cubicweb/cubes. During development, the cubes are commonly found in the directory /path/to/cubicweb_forest/cubes. The environment variable CW_CUBES_PATH gives additionnal locations where to search for cubes.
An instance is a runnable application installed on a computer and based on a cube.
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.
Instances can be of three different types: all-in-one, web engine or data repository. For applications that support high traffic, several web (front-end) and data (back-end) instances can be set-up to share the load.
The command cubicweb-ctl list also displays the list of instances installed on your system.
On a Unix system, the instances are usually stored in the directory /etc/cubicweb.d/. During development, the ~/etc/cubicweb.d/ directory is looked up, as well as the paths in CW_INSTANCES_DIR environment variable.
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.
The data repository [#]_ provides access to one or more data sources (including SQL databases, LDAP repositories, Mercurial or Subversion version control systems, other CubicWeb instance repositories, GAE’s DataStore, etc).
All interactions with the repository are done using the Relation Query Language (RQL). The repository federates the data sources and hides them from the querier, which does not realize when a query spans accross several data sources and requires running sub-queries and merges to complete.
It is common to run the web engine and the repository in the same process (see instances of type all-in-one above), but this is not a requirement. A repository can be set up to be accessed remotely using Pyro (Python Remote Objects) and act as a server.
Some logic can be attached to events that happen in the repository, like creation of entities, deletion of relations, etc. This is used for example to send email notifications when the state of an object changes. See Hooks below.
The web engine replies to http requests and runs the user interface and most of the application logic.
By default the web engine provides a default user interface based on the data model of the instance. Entities can be created, displayed, updated and deleted. As the default user interface is not very fancy, it is usually necessary to develop your own.
The data model of a cube is described as an entity-relationship schema using a comprehensive language made of Python classes imported from the yams library.
An entity type defines a set of attributes and is used in some relations. Attributes may be of the following types: String, Int, Float, Boolean, Date, Time, Datetime, Interval, Password, Bytes, RichString. See yams.BASE_TYPES for details.
A relation type is used to define an oriented binary relation between two entity types. The left-hand part of a relation is named the subject and the right-hand part is named the object.
A relation definition is a triple (subject entity type, relation type, object entity type) associated with a set of properties such as cardinality, constraints, etc.
Permissions can be set on entity types and relation types to control who will be able to create, read, update or delete entities and relations.
Some meta-data necessary to the system is added to the data model. That includes entities like users and groups, the entities used to store the data model itself and attributes like unique identifier, creation date, creator, etc.
When you create a new CubicWeb instance, the schema is stored in the database. When the cubes the instance is based on evolve, they may change their data model and provide migration scripts that will be executed when the administrator will run the upgrade process for the instance.
Beside a few core functionalities, almost every feature of the framework is achieved 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 AppObject (module cubicweb.appobject).
At startup, the registry 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 instance is running.
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.
CubicWeb provides a set of basic selectors that may be parametrized. Selectors can be combined with the binary operators & and | to build more complex selector that can be combined too.
There are three common ways to retrieve some appobject from the repository:
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 silenced 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.
No need for a complicated ORM when you have a powerful query language
All the persistent data in a CubicWeb instance is retrieved 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.
The repository exposes a db-api like api but using the RQL instead of SQL. XXX feed me
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.
** CubicWeb is data driven **
The view system is loosely coupled to data through a selection system. Views are, in essence, defined by an id, a selection predicate and an entry point (generaly producing html).
XXX feed me.
** CubicWeb provides an extensible data repository **
The data model defined using Yams types allows to express the data model in a comfortable way. However several aspects of the data model can not be expressed there. For instance:
The hook system is much like the triggers of an SQL database engine, except that:
Hooks are basically functions that dispatch on both:
They are an essential building block of any moderately complicated cubicweb application.