doc/book/annexes/rql/usecases.rst
author Philippe Pepiot <philippe.pepiot@logilab.fr>
Tue, 17 Mar 2020 13:34:54 +0100
changeset 12917 db0f56b19583
parent 12790 6f74e28be048
permissions -rw-r--r--
[pkg] merge 3.27 Require python >= 3.6 since recent typing notations require >= 3.6
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
12790
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     1
.. _rql_usecases:
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     2
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     3
RQL usecases
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     4
------------
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     5
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     6
Search bar
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     7
~~~~~~~~~~
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     8
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
     9
The search bar is available on a CubicWeb instance to use RQL and it's use and
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    10
configuration is described in `:doc:_searchbar`
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    11
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    12
Use of RQL in Card documents - ReST
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    13
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    14
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    15
With a CubicWeb instance supporting object types with ReST content (for example
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    16
`Card <https://www.cubicweb.org/project/cubicweb-card>`_), one can build content
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    17
based on RQL queries as dynamic documents.
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    18
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    19
For this, use the `rql` and `rql-table` ReST directive, for more information
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    20
about custom ReST directives `head over to the sphinx documentation
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    21
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    22
which uses them extensivelly.
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    23
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    24
rql directive
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    25
~~~~~~~~~~~~~
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    26
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    27
The `rql` directive takes as input an RQL expression and a view to apply to the
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    28
result.
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    29
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    30
For example, create a Card content by opening
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    31
http://cubicweb_example.org/add/Card and add the following content, as an
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    32
example : a table of blog entries (10 most recent blog entries table with user
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    33
and date information) ::
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    34
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    35
   Recent blog entries
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    36
   -------------------
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    37
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    38
   :rql:`Any B,U,D ORDERBY D DESC LIMIT 10 WHERE B is BlogEntry, B title T, B creation_date D, B created_by U:table`
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    39
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    40
.. image:: ../../images/example-card-with-rql-directive.png
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    41
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    42
rql-table directive
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    43
~~~~~~~~~~~~~~~~~~~
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    44
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    45
`rql-table` enables more customization, enabling you to modify the column
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    46
(`header`) contents, and the view applied for a specific column (`colvids`).
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    47
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    48
For example, create a Card content by openning http://cubicweb_example.org/add/Card and add the following content ::
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    49
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    50
        Blog entries with rql-table
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    51
        -----------------------------
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    52
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    53
        .. rql-table::
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    54
           :vid: table
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    55
           :headers: Title with link, who wrote it, at what date
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    56
           :colvids: 1=sameetypelist
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    57
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    58
           Any B,U,D ORDERBY D DESC LIMIT 10 WHERE B is BlogEntry, B title T, B creation_date D, B created_by U
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    59
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    60
All fields but the RQL string are optionnal. The ``:headers:`` option can
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    61
contain empty column names.
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    62
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    63
.. image:: ../../images/example-card-with-rql-table-directive.png
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    64
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    65
Use in python projects and CLI
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    66
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    67
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    68
`cwclientlib <https://pypi.org/project/cwclientlib/>` enables you to use RQL
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    69
in your python projects using only web requests. This project also provides a
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    70
remote command line interface (CLI) you can use to replace a server side
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    71
`cubicweb-ctl shell`.
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    72
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    73
Use in JavaScript/React components
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    74
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    75
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    76
`cwclientelements <https://forge.extranet.logilab.fr/open-source/cwclientelements>`
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    77
is a library of reusable React components for building web application with
6f74e28be048 [doc/book] add RQL use cases with search/card/python/javascript
Arthur Lutz <arthur.lutz@logilab.fr>
parents:
diff changeset
    78
cubicweb and RQL.