diff -r fd8751c3f3ee -r a721966779be doc/book/en/intro/concepts/index.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/book/en/intro/concepts/index.rst Thu May 07 16:33:22 2009 +0200 @@ -0,0 +1,265 @@ +.. -*- 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/