1 .. _rql_usecases:

     2 

     3 RQL usecases

     4 ------------

     5 

     6 Search bar

     7 ~~~~~~~~~~

     8 

     9 The search bar is available on a CubicWeb instance to use RQL and it's use and

    10 configuration is described in `:doc:_searchbar`

    11 

    12 Use of RQL in Card documents - ReST

    13 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    14 

    15 With a CubicWeb instance supporting object types with ReST content (for example

    16 `Card <https://www.cubicweb.org/project/cubicweb-card>`_), one can build content

    17 based on RQL queries as dynamic documents.

    18 

    19 For this, use the `rql` and `rql-table` ReST directive, for more information

    20 about custom ReST directives `head over to the sphinx documentation

    21 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html>`_

    22 which uses them extensivelly.

    23 

    24 rql directive

    25 ~~~~~~~~~~~~~

    26 

    27 The `rql` directive takes as input an RQL expression and a view to apply to the

    28 result.

    29 

    30 For example, create a Card content by opening

    31 http://cubicweb_example.org/add/Card and add the following content, as an

    32 example : a table of blog entries (10 most recent blog entries table with user

    33 and date information) ::

    34 

    35    Recent blog entries

    36    -------------------

    37 

    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`

    39 

    40 .. image:: ../../images/example-card-with-rql-directive.png

    41 

    42 rql-table directive

    43 ~~~~~~~~~~~~~~~~~~~

    44 

    45 `rql-table` enables more customization, enabling you to modify the column

    46 (`header`) contents, and the view applied for a specific column (`colvids`).

    47 

    48 For example, create a Card content by openning http://cubicweb_example.org/add/Card and add the following content ::

    49 

    50         Blog entries with rql-table

    51         -----------------------------

    52 

    53         .. rql-table::

    54            :vid: table

    55            :headers: Title with link, who wrote it, at what date

    56            :colvids: 1=sameetypelist

    57 

    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

    59 

    60 All fields but the RQL string are optionnal. The ``:headers:`` option can

    61 contain empty column names.

    62 

    63 .. image:: ../../images/example-card-with-rql-table-directive.png

    64 

    65 Use in python projects and CLI

    66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    67 

    68 `cwclientlib <https://pypi.org/project/cwclientlib/>` enables you to use RQL

    69 in your python projects using only web requests. This project also provides a

    70 remote command line interface (CLI) you can use to replace a server side

    71 `cubicweb-ctl shell`.

    72 

    73 Use in JavaScript/React components

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

    75 

    76 `cwclientelements <https://forge.extranet.logilab.fr/open-source/cwclientelements>`

    77 is a library of reusable React components for building web application with

    78 cubicweb and RQL.