diff -r 488099333160 -r b4e970513117 doc/book/en/intro/concepts/index.rst --- a/doc/book/en/intro/concepts/index.rst Sat Jun 27 00:59:36 2009 +0200 +++ b/doc/book/en/intro/concepts/index.rst Thu Jul 02 22:01:19 2009 +0200 @@ -1,5 +1,7 @@ .. -*- coding: utf-8 -*- +.. _Concepts: + The Core Concepts of CubicWeb ============================= @@ -13,8 +15,9 @@ Cubes ----- -A cube is a software component composed of three parts: its data model (schema), -its logic (entities) and its user interface (views). +A cube is a software component made of three parts: its data model +(:file:`schema`), its logic (:file:`entities`) and its user interface +(:file:`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`_ @@ -24,12 +27,14 @@ The `CubicWeb Forge`_ offers a large number of cubes developed by the community and available under a free software license. -Available cubes on your system are usually stored in the directory -:file:`/usr/share/cubicweb/cubes` when using a unix system wide -installation. During development, the cubes are found in the -:file:`/path/to/cubicweb_forest/cubes` directory. You can specify additional -locations using the :envvar:`CW_CUBES_PATH` environment variable, using ':' as a -separator. +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 +:file:`/usr/share/cubicweb/cubes`. During development, the cubes are commonly +found in the directory :file:`/path/to/cubicweb_forest/cubes`. The environment +variable :envvar:`CW_CUBES_PATH` gives additionnal locations where to search for +cubes. .. _`CubicWeb Forge`: http://www.cubicweb.org/project/ .. _`cubicweb-blog`: http://www.cubicweb.org/project/cubicweb-blog @@ -37,124 +42,113 @@ Instances ----------- +--------- An instance is a runnable application installed on a computer and based on a cube. -The instance directory includes the configuration files. Several instances can -be created based on the same cube. For exemple, several software forges can be -set up on one computer system based on the `cubicweb-forge`_ 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. .. _`cubicweb-forge`: http://www.cubicweb.org/project/cubicweb-forge -Instances can be of 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. +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. .. image:: ../../images/archi_globale.en.png +The command ``cubicweb-ctl list`` displays the list of instances installed on +your system. + +On a Unix system, the instances are usually stored in the directory +:file:`/etc/cubicweb.d/`. During development, the :file:`~/etc/cubicweb.d/` +directory is looked up, as well as the paths in :envvar:`CW_REGISTRY` +environment variable. + The term application can refer to an instance or to a cube, depending on the context. This book will try to avoid using this term and use *cube* and *instance* as appropriate. -(Data) Repository -~~~~~~~~~~~~~~~~~~ +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. +The data repository [#]_ provides access to one or more data sources (including +SQL databases, LDAP repositories, Mercurial or Subversion version control +systems, other CubicWeb repositories, GAE's DataStore, etc). -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. - +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. -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. +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. -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. +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. + +.. _[#]: not to be confused with a Mercurial repository or a Debian repository. +.. _`Python Remote Objects`: http://pyro.sourceforge.net/ -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. - - +Web Engine +---------- -Schema ------- -** *CubicWeb* is schema driven ** +The web engine replies to http requests and runs the user interface and most of +the application logic. -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. +By default the web engine provides a generated 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. -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. +Schema (Data Model) +------------------- -*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. +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. -*CubicWeb* add some metadata to every entity type, such as the eid (a global - identifier, unique into an instance), entity's creation date... - +.. _yams: http://www.logilab.org/project/yams/ -Attributes may be of the following types: - `String`, `Int`, `Float`, `Boolean`, `Date`, `Time`, `Datetime`, - `Interval`, `Password`, `Bytes`. - -New in 3.2: RichString +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 +:ref:`yams.BASE_TYPES` for details. -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. +A `relation type` is used to define a binary oriented 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. -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. +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. -In *CubicWeb* relations are ordered and binary: by convention we name the first -item of a relation the `subject` and the second the `object`. +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. -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... +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. - +Registries and Objects +---------------------- -Dynamic objects for reusable components ---------------------------------------- -** Dynamic objects management or how CubicWeb provides really reusable components ** +XXX registry, register, registries, registers ??? 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 +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 @@ -168,6 +162,7 @@ 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 @@ -175,23 +170,22 @@ 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. + +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 which may be parametrized and combined -using binary `&` and `|` operators to provide a custom selector (which can be -itself reused...). +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 is 3 current ways to retreive some appobject from the repository: +There are three common ways to retrieve 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. + that case, every object with the a postive score is 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 @@ -218,9 +212,10 @@ 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 +**No need for a complicated ORM when you have a powerful query language** + +All the persistant data in a CubicWeb application 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 @@ -228,16 +223,19 @@ 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. @@ -248,7 +246,3 @@ ** *CubicWeb* provides an extensible data repository ** XXX feed me. - - -.. _`Python Remote Object`: http://pyro.sourceforge.net/ -.. _`yams`: http://www.logilab.org/project/yams/