6 .. toctree::

     6 This section defines some terms and core concepts of the *CubicWeb*

     7    :maxdepth: 1

     7 framework. To avoid confusion while reading this book, take time to go through

     8 

     8 the following definitions and use this section as a reference during your

     9 ------------------------------

     9 reading.

    10 

    11 This section aims to provide you the keys of success with *CubicWeb*

    12 by clarifying the terms specific to our framework. If you want to do anything

    13 serious with CubicWeb, you should understand concepts in those lines.

    14 

    15 *CubicWeb* defines its own terminology. To make sure there is no confusion

    16 while reading this book, we strongly recommand you take time to go through

    17 the following definitions that are the basics to understand while

    18 developing with *CubicWeb*.

    19 

    25 ** Construct your application by assembling cubes **

    15 

    26 

    16 A cube is a software component composed of three parts: its data model (schema),

    27 A cube provides a specific functionality, or a complete *CubicWeb*

    17 its logic (entities) and its user interface (views).

    28 application usually by assembling other cubes.

    18 

    29 

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

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

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

    31 of web interface.

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

    32 

    22 commentable blog entries.

    33 You can decide to write your own set of cubes if you wish to re-use the

    23 

    34 entity types you develop or/and if you have specific needs not covered by

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

    35 cubes are available from the `CubicWeb Forge`_ under a free software license.

    25 and available under a free software license.

    36 

    26 

    37 Available cubes on your system are defined in the directory

    27 Available cubes on your system are usually stored in the directory

    38 :file:`/usr/share/cubicweb/cubes` when using a system wide installation.  For people

    28 :file:`/usr/share/cubicweb/cubes` when using a unix system wide

    39 using the mercurial repository of cubicweb, the :file:`/path/to/forest/cubicweb/cubes`

    29 installation. During development, the cubes are found in the

    40 directory is used. You can specify additional location using the :envvar:`CW_CUBES_PATH`

    30 :file:`/path/to/cubicweb_forest/cubes` directory. You can specify additional

    41 environment variable, using ':' as separator.

    31 locations using the :envvar:`CW_CUBES_PATH` environment variable, using ':' as a

    32 separator.

    44 

    35 .. _`cubicweb-blog`: http://www.cubicweb.org/project/cubicweb-blog

    36 .. _`cubicweb-comment`: http://www.cubicweb.org/project/cubicweb-comment

    49 ** *CubicWeb* framework is a server/client application framework**

    41 

    50 

    42 An instance is a runnable application installed on a computer and based on a

    51 An instance is a specific installation of one or multiple cubes. All the required

    43 cube.

    52 configuration files necessary for the well being of your web application are

    44 

    53 grouped in an instance. This will refer to the cube(s) your application is based

    45 The instance directory includes the configuration files. Several instances can

    54 on.  For example logilab.org and our intranet are two instances of a single cube

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

    55 `jpl`

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

    56 

    48 

    57 We recommand not to define schema, entities or views in the instance

    49 .. _`cubicweb-forge`: http://www.cubicweb.org/project/cubicweb-forge

    58 file system itself but in the cube, in order to maintain re-usability of

    50 

    59 entities and their views. We strongly recommand to develop cubes which

    51 Instances can be of different types: all-in-one, web engine or data repository. For

    60 could be used in other instances (modular approach).

    52 applications that support high traffic, several web (front-end) and data

    61 

    53 (back-end) instances can be set-up to share the load.

    62 An instance usually usually consists into a web interface which is talking to a

    63 rql repository, itself connected to a SQL database, all into a single

    64 process. You can have some more complicated configurations using several web

    65 front-ends talking to a rql repository using `Pyro`_, databases replication...

    69 The term application is sometimes used to talk about an instance and sometimes to

    57 The term application can refer to an instance or to a cube, depending on the

    70 talk of a cube depending on the context.  So we would like to avoid using this

    58 context. This book will try to avoid using this term and use *cube* and

    71 term and try to use *cube* and *instance* instead.

    59 *instance* as appropriate.

    72 

    60 

    73 Data Repository

    61 (Data) Repository

    74 ~~~~~~~~~~~~~~~

    62 ~~~~~~~~~~~~~~~~~~

    63