sib-display
===========

Receives the URL of a resource or of a container of resources via its
``data-src`` attribute, and displays it. 

Each field of the displayed
resources can be rendered by a specific widget, either custom or chosen
from the default ones. Filters and searching capabilities can be easily
added to interact with the list of data being displayed.

.. code:: html

   <sib-display
     id="list"
     data-src="http://localhost:8000/todos/"
     value-created="Created by:"
     fields="image, status(state), author(created, name), info(task, date), deadline"
     widget-image="sib-display-img"
     search-fields="name, author"
     next="detail"
   ></sib-display>

Attributes
----------

data-src
~~~~~~~~
   The uri of the LDP resource you want to display. 
   
   If this resource is a container, ``<sib-display>`` will create a child
   ``<sib-display>`` for each resource it contains, and ``<sib-form>``
   will display a blank form with appropriate fields to create a new
   resource.

value-xyz
~~~~~~~~
   To display a string not contained within the data.

fields
~~~~~~~~
   The ordered list of fields to be displayed, separated
   by commas.

   By default, all the fields of the resource are displayed.

   To not show any fields, put an empty fields (eg.
   ``<sib-display fields />)``

   To group fields within a ``<div>`` tag that will have the ``name``
   attribute set up to ``xyz``, enclose some fields in parenthesis. For
   example: ``fields="xyz(first_name, last_name), email"``. You can
   customize the group widget, see the `sets widgets <#set-widgets>`__
   section below for more info.

   By default, all displayed fields are direct children of
   ``<sib-display>``. Make sure you don’t give your set the same name as
   a field as it would result in an infinite loop.

widget-xyz
~~~~~~~~
   The widget to be used to display the ``xyz``
   field. By default, the widget used is ``<sib-display-div>``. Cf the
   `Display widgets <#display-widgets>`__ section below for more info.

default-widget
~~~~~~~~~~~~~~~~
   The widget to use for all the fields, except
   if a specific one is defined for a field.

multiple-xyz
~~~~~~~~~~~~~~~~
   Show field ``xyz`` as multiple field containing
   one widget for each child. Multiple widget can be specified, example:
   ``multiple-skills="my-custom-multiple-widget"``. If argument is used
   without value, default multiple widget is used. Cf the `Multiple
   widgets <#multiple-widgets>`__ section below for more info.

   each-label-xyz
   ++++++++++++++
      Used with ``multiple-xyz``, label of each
      child of multiple widget

   each-class-xyz
   ++++++++++++++
      Used with ``multiple-xyz``, class of each
      child of multiple widget

   each-range-xyz
   ++++++++++++++
      Used with ``multiple-xyz``, range value of
      each child of multiple widget

   multiple-xyz-add-label
   +++++++++++++
      Used with ``multiple-xyz``, text
      of the “+” button

   multiple-xyz-remove-label
   ++++++++++++++++++++++++++++
      Used with ``multiple-xyz``,
      text of the “×” button

search-fields
~~~~~~~~~~~~~~~~
   It is possible to search/filter your list by
   choosing the fields you want to filter it with. To be able to filter
   my users by ``name`` for instance, I can set
   ``search-fields="name"``. This will display a form with the
   appropriate inputs to filter the list.

   -  **``search-value-xyz``**: The default value of the search field
      ``xyz``
   -  **``search-label-xyz``**: Set the label for the search field
      ``xyz``
   -  **``search-widget-xyz``**: The form widget of the search field
      ``xyz``
   -  **``search-range-xyz``**: The range of values of the search field
      ``xyz``

paginate-by
~~~~~~~~~~~~~~~~
   The list can also be split in pages, for example
   set ``paginate-by="5"`` to display pages of 5 elements, the prev/next
   buttons and the counter will be added automatically

order-by
~~~~~~~~~~~~~~~~
   The name of the field you want to use to order the
   list. For example, ``order-by="username"`` will order the users list
   alphabetically based on the username.

highlight-xyz
~~~~~~~~~~~~~~~~
   The resources to put at the top of the list.
   For example, ``highlight-date="2019-05-20"`` will display first all
   the resources which have a field date equal to “2019-05-20”.

group by
~~~~~~~~~~~~~~~~
   The resources will be grouped by the field you give
   as a parameter. For example, ``group-by="date"`` will render one
   ``<div>`` by date, and put the corresponding resources inside.

next
~~~~~~~~~~~~~~~~
   ``name`` attribute of the ``<sib-route>`` that should
   be accessed when a ``<sib-display>`` element is clicked. See the
   documentation of ``<sib-router>`` for more details.

action-xyz
~~~~~~~~~~~~~~~~

label-xyz
~~~~~~~~~~~~~~~~
   Set the label for the field ``xyz``

editable-xyz
~~~~~~~~~~~~~~~~
   Add an “edit” button next to the ``xyz`` field
   to let the user edit it. The changes are saved as soon as the field
   loses focus. The editable attribute works with the following widgets:
   ``sib-display-div``, ``sib-display-labelled-div``,
   ``sib-display-mailto`` and ``sib-display-tel``

counter-template
~~~~~~~~~~~~~~~~
   To display the number of resources fetched
   by the ``sib-display``. It takes a string in which you can use HTML
   tags, and the ``counter`` variable to add the number.
   i.e. ``"<strong>${counter} results</strong>"``

extra-context
~~~~~~~~~~~~~~~~
   The id of the ``<script>`` tag which contains
   the context you want to add for this component. An extra context
   looks like this:

   .. code:: html

      <script id="custom-context" type="application/ld+json">
        { "user": "https://api.test-paris.happy-dev.fr/users/" }
      </script>

   If your ``<script>`` tag has the attribute ``data-default-context``,
   this extra context will be applied on all the components which
   doesn’t have an ``extra-context`` attribute.

loader-id
~~~~~~~~~~~~~~~~
   Id of the loader element you want to display
   during the loading time.

class-xyz
~~~~~~~~~~~~~~~~
   Class attribute added to the fields ``xyz``.

child-xyz
~~~~~~~~~~~~~~~~
   add attribute ``xyz`` to all children.

nested-field
~~~~~~~~~~~~~~~~
   Name of the field of the requested resource to
   display. Useful when the source url is auto-generated (for instance,
   with the attribute ``bind-resources``) but you need to display
   another field of this source.

default-xyz
~~~~~~~~~~~~~~~~
   Value displayed for field ``xyz`` when it’s
   empty or not defined

empty-widget
~~~~~~~~~~~~~~~~
   Widget to display when there is no element in
   the container

empty-value
~~~~~~~~~~~~~~~~
   To display a value in the empty widget. It can
   be accessed in the widget like this: ``${value}``

**API:** In Javascript, you have access to different variables and
methods on a ``sib-display`` element: - ``sibDisplay.resource``: returns
the Proxy of the current resource - ``sibDisplay.resource.clearCache()``
(async): clears the cache of the store for this resource -
``sibDisplay.resourceId``: returns the id of the current resource