doc/book/intro/concepts.rst
author Sylvain Thénault <sylvain.thenault@logilab.fr>
Wed, 29 Mar 2017 14:56:04 +0200
branch3.25
changeset 12122 92aef8c6e7c8
parent 10501 1031d4a17a69
child 12853 48e066c9655a
permissions -rw-r--r--
[hg] Add generated slapd.conf to hgignore
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
     2
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
     3
.. _Concepts:
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
     4
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
     5
The Core Concepts of |cubicweb|
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
     6
===============================
301
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 300
diff changeset
     7
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
     8
This section defines some terms and core concepts of the |cubicweb| framework. To
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
     9
avoid confusion while reading this book, take time to go through the following
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    10
definitions and use this section as a reference during your reading.
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    11
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    12
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    13
.. _Cube:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    14
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    15
Cubes
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    16
-----
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    17
10501
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    18
A cube is a software component made of three parts:
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    19
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    20
- its data model (:mod:`schema`),
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    21
- its logic (:mod:`entities`) and
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    22
- its user interface (:mod:`views`).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    23
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    24
A cube can use other cubes as building blocks and assemble them to provide a
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    25
whole with richer functionnalities than its parts. The cubes `cubicweb-blog`_ and
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    26
`cubicweb-comment`_ could be used to make a cube named *myblog* with commentable
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    27
blog entries.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    28
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    29
The `CubicWeb.org Forge`_ offers a large number of cubes developed by the community
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    30
and available under a free software license.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    31
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    32
.. note::
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    33
10501
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    34
   The command :command:`cubicweb-ctl list` displays the list of available cubes.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    35
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    36
.. _`CubicWeb.org Forge`: http://www.cubicweb.org/project/
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    37
.. _`cubicweb-blog`: http://www.cubicweb.org/project/cubicweb-blog
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    38
.. _`cubicweb-comment`: http://www.cubicweb.org/project/cubicweb-comment
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    39
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    40
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    41
.. _Instance:
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    42
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    43
Instances
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    44
---------
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    45
10501
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    46
An instance is a runnable application installed on a computer and
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    47
based on one or more cubes.
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    48
10501
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    49
The instance directory contains the configuration files. Several
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    50
instances can be created and based on the same cube. For example,
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    51
several software forges can be set up on one computer system based on
1031d4a17a69 [doc] remove mentions of pyro and reposity instance type
David Douard <david.douard@logilab.fr>
parents: 10495
diff changeset
    52
the `cubicweb-forge`_ cube.
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    53
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    54
.. _`cubicweb-forge`: http://www.cubicweb.org/project/cubicweb-forge
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    55
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
    56
The command :command:`cubicweb-ctl list` also displays the list of instances
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
    57
installed on your system.
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    58
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5388
diff changeset
    59
.. note::
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    60
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    61
  The term application is used to refer to "something that should do something as
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    62
  a whole", eg more like a project and so can refer to an instance or to a cube,
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    63
  depending on the context. This book will try to use *application*, *cube* and
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    64
  *instance* as appropriate.
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    65
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    66
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    67
.. _RepositoryIntro:
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    68
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    69
Data Repository
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    70
---------------
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2172
diff changeset
    71
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    72
The data repository [1]_ encapsulates and groups an access to one or
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    73
more data sources (including SQL databases, LDAP repositories, other
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    74
|cubicweb| instance repositories, filesystems, Google AppEngine's
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    75
DataStore, etc).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    76
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    77
All interactions with the repository are done using the `Relation Query Language`
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    78
(:ref:`RQL`). The repository federates the data sources and hides them from the
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    79
querier, which does not realize when a query spans several data sources
4446
a413fac5ff5e damn me, more stupid sed fix...
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4442
diff changeset
    80
and requires running sub-queries and merges to complete.
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
    81
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    82
Application logic can be mapped to data events happenning within the
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    83
repository, like creation of entities, deletion of relations,
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    84
etc. This is used for example to send email notifications when the
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    85
state of an object changes. See :ref:`HookIntro` below.
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    86
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
    87
.. [1] not to be confused with a Mercurial repository or a Debian repository.
8825
7f296f07070a [doc] fix Pyro url
Dimitri Papadopoulos <dimitri.papadopoulos@cea.fr>
parents: 7632
diff changeset
    88
.. _`Python Remote Objects`: http://pythonhosted.org/Pyro4/
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    89
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    90
.. _WebEngineIntro:
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
    91
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    92
Web Engine
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
    93
----------
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    94
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
    95
The web engine replies to http requests and runs the user interface.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
    96
5144
5a09bea07302 [doc/book] a new chapter on how to use the ORM
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5143
diff changeset
    97
By default the web engine provides a `CRUD`_ user interface based on
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
    98
the data model of the instance. Entities can be created, displayed,
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
    99
updated and deleted. As the default user interface is not very fancy,
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   100
it is usually necessary to develop your own.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   101
5144
5a09bea07302 [doc/book] a new chapter on how to use the ORM
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5143
diff changeset
   102
.. _`CRUD`: http://en.wikipedia.org/wiki/Create,_read,_update_and_delete
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   103
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   104
.. _SchemaIntro:
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   105
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   106
Schema (Data Model)
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   107
-------------------
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   108
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   109
The data model of a cube is described as an entity-relationship schema using a
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   110
comprehensive language made of Python classes imported from the yams_ library.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   111
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   112
.. _yams: http://www.logilab.org/project/yams/
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   113
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   114
An `entity type` defines a sequence of attributes. Attributes may be
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   115
of the following types: `String`, `Int`, `Float`, `Boolean`, `Date`,
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   116
`Time`, `Datetime`, `Interval`, `Password`, `Bytes`, `RichString`.
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   117
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   118
A `relation type` is used to define an oriented binary relation
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   119
between entity types.  The left-hand part of a relation is named the
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   120
`subject` and the right-hand part is named the `object`.
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   121
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   122
A `relation definition` is a triple (*subject entity type*, *relation type*, *object
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   123
entity type*) associated with a set of properties such as cardinality,
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   124
constraints, etc.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   125
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   126
Permissions can be set on entity types or relation definition to control who
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   127
will be able to create, read, update or delete entities and relations. Permissions
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   128
are granted to groups (to which users may belong) or using rql expressions (if the
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   129
rql expression returns some results, the permission is granted).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   130
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   131
Some meta-data necessary to the system are added to the data model. That includes
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   132
entities like users and groups, the entities used to store the data model
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   133
itself and attributes like unique identifier, creation date, creator, etc.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   134
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
   135
When you create a new |cubicweb| instance, the schema is stored in the database.
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   136
When the cubes the instance is based on evolve, they may change their data model
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   137
and provide migration scripts that will be executed when the administrator will
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   138
run the upgrade process for the instance.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   139
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   140
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   141
.. _VRegistryIntro:
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   142
5143
43afbdd5c8b4 improved doc on selectors an vregistry
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5134
diff changeset
   143
Registries and application objects
43afbdd5c8b4 improved doc on selectors an vregistry
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5134
diff changeset
   144
----------------------------------
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   145
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   146
Application objects
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   147
~~~~~~~~~~~~~~~~~~~
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   148
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   149
Besides a few core functionalities, almost every feature of the framework is
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   150
achieved by dynamic objects (`application objects` or `appobjects`) stored in a
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   151
two-levels registry. Each object is affected to a registry with
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   152
an identifier in this registry. You may have more than one object sharing an
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   153
identifier in the same registry:
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   154
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   155
  object's `__registry__` : object's `__regid__` : [list of app objects]
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   156
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   157
In other words, the `registry` contains several (sub-)registries which hold a
5306
763319a51e72 [doc/book] some fixes for vregistry, selectors & appobjects
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5257
diff changeset
   158
list of appobjects associated to an identifier.
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   159
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   160
The base class of appobjects is :class:`cubicweb.appobject.AppObject`.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   161
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   162
Selectors
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   163
~~~~~~~~~
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   164
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   165
At runtime, appobjects can be selected in a registry according to some
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   166
contextual information. Selection is done by comparing the *score*
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   167
returned by each appobject's *selector*.
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   168
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   169
The better the object fits the context, the higher the score. Scores
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   170
are the glue that ties appobjects to the data model. Using them
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   171
appropriately is an essential part of the construction of well behaved
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   172
cubes.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   173
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   174
|cubicweb| provides a set of basic selectors that may be parametrized.  Also,
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   175
selectors can be combined with the `~` unary operator (negation) and the binary
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   176
operators `&` and `|` (respectivly 'and' and 'or') to build more complex
5608
f9ab62103ad4 proof read documentation
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 5400
diff changeset
   177
selectors. Of course complex selectors may be combined too. Last but not least, you
5143
43afbdd5c8b4 improved doc on selectors an vregistry
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5134
diff changeset
   178
can write your own selectors.
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   179
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   180
The `registry`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   181
~~~~~~~~~~~~~~~
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   182
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   183
At startup, the `registry` inspects a number of directories looking
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   184
for compatible class definitions. After a recording process, the
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   185
objects are assigned to registries and become available through the
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   186
selection process.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   187
5143
43afbdd5c8b4 improved doc on selectors an vregistry
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5134
diff changeset
   188
In a cube, application object classes are looked in the following modules or
43afbdd5c8b4 improved doc on selectors an vregistry
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5134
diff changeset
   189
packages:
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   190
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   191
- `entities`
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   192
- `views`
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   193
- `hooks`
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   194
- `sobjects`
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   195
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   196
There are three common ways to look up some application object from a
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   197
registry:
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   198
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   199
* get the most appropriate object by specifying an identifier and
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   200
  context objects. The object with the greatest score is
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   201
  selected. There should always be a single appobject with a greater
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   202
  score than others for a particular context.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   203
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   204
* get all objects applying to a context by specifying a registry. A
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   205
  list of objects will be returned containing the object with the
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   206
  highest score (> 0) for each identifier in that registry.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   207
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   208
* get the object within a particular registry/identifier. No selection
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   209
  process is involved: the registry will expect to find a single
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   210
  object in that cell.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   211
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   212
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   213
.. _RQLIntro:
119
7a56ca431d65 [doc] missing file
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff changeset
   214
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   215
The RQL query language
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   216
----------------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   217
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5388
diff changeset
   218
No need for a complicated ORM when you have a powerful data
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5388
diff changeset
   219
manipulation language.
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   220
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5388
diff changeset
   221
All the persistent data in a |cubicweb| instance is retrieved and
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5388
diff changeset
   222
modified using RQL (see :ref:`rql_intro`).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   223
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   224
This query language is inspired by SQL but is on a higher level in order to
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   225
emphasize browsing relations.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   226
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   227
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   228
Result set
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   229
~~~~~~~~~~
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   230
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   231
Every request made (using RQL) to the data repository returns an object we call a
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   232
Result Set. It enables easy use of the retrieved data, providing a translation
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   233
layer between the backend's native datatypes and |cubicweb| schema's EntityTypes.
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   234
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   235
Result sets provide access to the raw data, yielding either basic Python data
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   236
types, or schema-defined high-level entities, in a straightforward way.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   237
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   238
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   239
.. _ViewIntro:
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   240
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   241
Views
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   242
-----
2279
b4e970513117 [doc] improve description of core concepts
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2175
diff changeset
   243
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   244
**CubicWeb is data driven**
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   245
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   246
The view system is loosely coupled to data through the selection system explained
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   247
above. Views are application objects with a dedicated interface to 'render'
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   248
something, eg producing some html, text, xml, pdf, or whatsover that can be
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   249
displayed to a user.
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   250
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   251
Views actually are partitioned into different kind of objects such as
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   252
`templates`, `boxes`, `components` and proper `views`, which are more
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   253
high-level abstraction useful to build the user interface in an object
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   254
oriented way.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   255
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   256
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   257
.. _HookIntro:
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   258
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   259
Hooks and operations
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   260
--------------------
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
   261
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
   262
**CubicWeb provides an extensible data repository**
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents: 1398
diff changeset
   263
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   264
The data model defined using Yams types allows to express the data
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   265
model in a comfortable way. However several aspects of the data model
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   266
can not be expressed there. For instance:
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   267
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   268
* managing computed attributes
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   269
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   270
* enforcing complicated business rules
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   271
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   272
* real-world side-effects linked to data events (email notification
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   273
  being a prime example)
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   274
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   275
The hook system is much like the triggers of an SQL database engine,
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   276
except that:
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   277
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   278
* it is not limited to one specific SQL backend (every one of them
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   279
  having an idiomatic way to encode triggers), nor to SQL backends at
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   280
  all (think about LDAP or a Subversion repository)
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   281
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   282
* it is well-coupled to the rest of the framework
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   283
6928
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   284
Hooks are also application objects (in the `hooks` registry) and
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   285
selected on events such as after/before add/update/delete on
62b8ef1e859a [doc/book] simplify & fix the overview chapter
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 6397
diff changeset
   286
entities/relations, server startup or shutdown, etc.
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   287
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   288
`Operations` may be instantiated by hooks to do further processing at different
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   289
steps of the transaction's commit / rollback, which usually can not be done
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   290
safely at the hook execution time.
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   291
5134
910e021131d1 [doc] enhanced concepts section
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4446
diff changeset
   292
Hooks and operation are an essential building block of any moderately complicated
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2535
diff changeset
   293
cubicweb application.
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 3283
diff changeset
   294
5400
b7ab099b128a [doc/book] various content fixes
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5388
diff changeset
   295
.. note::
5608
f9ab62103ad4 proof read documentation
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 5400
diff changeset
   296
   RQL queries executed in hooks and operations are *unsafe* by default, i.e. the
5146
fe56baf63ecb add note about running repository / client code
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5144
diff changeset
   297
   read and write security is deactivated unless explicitly asked.