.. _widget-mixin:
widget-mixin
============

The widget mixin allows to create a widget in the DOM for each properties of a resource, and set its value.

Used by:
--------

    * :ref:`solid-display <solid-display>`
    * :ref:`solid-form <solid-form>`
    * :ref:`solid-map <solid-map>`


Attributes
----------

``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.
    ``<solid-display fields />)``

    By default, all displayed fields are inserted into a ``<div>``

    **Sets**

    To group fields within a ``<div>`` tag, enclose some fields in parenthesis.

    In this example, a ``<div name="fullName">`` will be created, and it will contain
    the widgets of the first name and the last name of the user.

    .. code:: html

        <solid-display
            data-src="http://server/users/1/"
            fields="fullName(first_name, last_name), email"
        ></solid-display>

    You can customize the group widget, see the `Sets widgets <https://docs.startinblox.com/import_documentation/Widgets/Reference.html>`__
    page for more info.

    **Strings**

    To display static strings in the fields list, put it inside quotes.

    .. code:: html

        <solid-display
            data-src="http://server/users/1/"
            fields=" 'Email: ', email "
        ></solid-display>

    It will create a ``<span>`` element filled with the text ``Email: ``.


``value-[field]``
~~~~~~~~~~~~~~~~~
   To display a string not contained within the data.

    .. code:: html

        <solid-display
            fields="title"
            value-title="My custom and static title"
        ></solid-display>


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

``widget-[field]``
~~~~~~~~~~~~~~~~~~
   The widget to be used to display the ``[field]``. This widget can be:

   - A core widget. More informations on the `widget reference <https://docs.startinblox.com/import_documentation/Widgets/Reference.html>`__ page
   - A custom widget. More informations on the `solid-widget <https://docs.startinblox.com/import_documentation/Components/SiB-Widget.html>`__ page
   - A native HTML tag (ie: ``h1``). The value will be inserted as text content of the tag.

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

``default-widget-[field]``
~~~~~~~~~~~~~~~~~~~~~~~~~~
   The widget displayed by default if the ``[field]`` is empty.

``action-[field]``
~~~~~~~~~~~~~~~~~~
    Displays a link with a ``<solid-link>`` tag with the current resource as ``data-src`` and the value of the attribute as ``next``.

``src-[field]``
~~~~~~~~~~~~~~~
    Defines the ``data-src`` in the solid-link created by the ``action-[field]`` attribute.

``label-[field]``
~~~~~~~~~~~~~~~~~
   Set the label for the ``[field]``.

``placeholder-[field]``
~~~~~~~~~~~~~~~~~~~~~~~
    Set the placeholder for the ``[field]``.

``class-[field]``
~~~~~~~~~~~~~~~~~
    Set the class applied to the widget of the ``[field]`` or the set.

``editable-[field]``
~~~~~~~~~~~~~~~~~~~~
    *Works only with display widgets*

    Add an “edit” button next to the ``[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 templates:

    - ``display-div``
    - ``display-link``
    
    .. code:: html

        <solid-display
            data-src="http://server/users/1/"
            fields="name"
            widget-name="solid-display-div"
            editable-name
        ></solid-display>

``alt-[field]``
~~~~~~~~~~~~~~~
    *Works only with solid-display-img*

    Set the alt for the field ``[field]``.

``empty-[set]``
~~~~~~~~~~~~~~~
    *Available from version 0.17*

    Name of the widget to display when all the fields in ``[set]`` are empty.

``empty-[set]-value``
~~~~~~~~~~~~~~~~~~~~~
     *Available from version 0.17*
     
    Value to pass to the empty widget if all fields in ``[set]`` are empty. It is accessible in ``${value}``

    .. code:: html

        <solid-display
            data-src="http://server/users/"
            fields="fullname(first_name, last_name)"
            empty-fullname="no-name-widget"
            empty-fullname-value="add-name"
        ></solid-display>

        <solid-widget name="no-name-widget">
            <template>
                <small>No fullname filled in. <solid-link next="${value}">click here to add one</solid-link></small>
            </template>
        </solid-widget>

``multiple-[field]``
~~~~~~~~~~~~~~~~~~~~
    Allows to display the container ``[field]`` nested in the current resource.

    It takes a container URI as a value, fetch all the resources
    of this container and display them.

    Multiple widget can be specified, example:
    ``multiple-skills="my-custom-multiple-widget"``. If argument is used
    without value, default multiple widget is used.


    It can be used in :

    - ``solid-display``: a nested ``solid-display`` will be created with the container URI as
    data-src.
    All attributes of the form ``multiple-[field]-[attribute]`` are transfered
    on the nested ``solid-display`` as ``[attribute]``.
    For example, to choose the fields you want to display, you can set:
    ``multiple-[field]-fields="name, @id"``

    .. code:: html

        <solid-display
            data-src="http://server/users/1/"
            fields="skills"
            multiple-skills
            multiple-skills-fields="name"
        ></solid-display>

    - ``solid-form`` : all the resources of the container are displayed in a text widget.
    Buttons are automatically created to add and remove elements.

    For ``solid-form`` only:

    ``multiple-[field]-add-label``
    ++++++++++++++++++++++++++++++

        Text of the “+” button used to add an element

    ``multiple-[field]-remove-label``
    +++++++++++++++++++++++++++++++++

        Text of the “x” button used to remove an element