Newer
Older
Widgets are tools that allow to choose, precise how to display data.
They are created at the moment you ask for it for the first time.
The name of the widget is analyzed to build a widget which uses the features and template you want.
.. figure:: ../../_static/images/import_documentation/Widgets-API-Developers.png
``solid-[type]-[template]-[features]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Its name must begin by "**solid-**", followed by at least a ``type`` (except for ``default`` type) and a ``template``, and eventually one or several ``features``.
*All the keywords must be separated by an hyphen``-``, it is recommended to keep that order (to harmonise widget names writing).*
It refers to the "kind" of data to display :
- ``display`` refers to a display formatting,
- ``form`` to display a form element (``<input>``, ``<textarea>``, ``<select>``, etc),
- ``set`` to precise how to display values of fields in :ref:`sets <widget-mixin>`.
It will select the directory of template to use.
Name of the template to use.
Each type has several templates. They specify how to use or display the value(s) and/or to indicate the HTML tag to use.
Available templates :
- ``display`` directory
- ``value``: displays ``value`` directly in the widget tag.
- ``div``: displays ``value`` inside a ``<div>`` tag.
- ``link``: displays ``value`` as an ``href`` attribute in a ``<a>`` tag.
- ``img``: displays ``value`` as a ``src`` attribute in a ``<img>`` tag.
- ``boolean``: displays label (or name) in a ``<label>`` tag if ``value == true``.
- ``form`` directory
- ``text``: set ``value`` in an ``<input>`` of type ``text``.
- ``textarea``: set ``value`` in a ``<textarea>``.
- ``richtext``: set ``value`` in an ``<div>`` and initialize a light rich text editor by using ``Quill``.
- ``checkbox``: create a checkbox, which is checked if ``value == true``.
- ``email``: set ``value`` in an ``<input>`` of type ``email``.
- ``date``: set ``value`` in an ``<input>`` of type ``date``.
- ``rangedate``: set 2 values in 2 ``<input>`` of type ``date``. Used for filtering with min and max.
Possible to add ``start-value-[field]`` and ``end-value-[field]`` attributes to set min and max values. Date format to follow : "YYYY-MM-DD". Each attribute accepts ``today`` as value.
- ``number``: set ``value`` in an ``<input>`` of type ``number``.
- ``rangenumber``: set 2 values in 2 ``<input>`` of type ``number``. Used for filtering with min and max.
Possible to add ``start-value-[field]`` and ``end-value-[field]`` attributes to set min and max values.
- ``hidden``: set ``value`` in an ``<input>`` of type ``hidden``. If you need to use a boolean or numeric value you can add a ``bool`` or
``num`` mixin (ie: ``solid-form-hidden-bool``).
- ``dropdown``: set ``value`` in a ``<select>``. The list is provided via the ``range`` attribute, which expects a container’s URL, or via the ``enum`` attribute, which takes a list of the values separated by commas.
- ``radio``: set ``value`` in a list of radio buttons. The list is provided via the ``range`` attribute, which expects a container’s URL, or via the ``enum`` attribute, which takes a list of the values separated by commas.
- ``multiple``: Accept a container URI as a ``value``, and inserts one widget per resource with a “remove” button for each widget, and an “add” button.
- ``multipleselect``: Accept a container URI as a ``value``, and inserts a dropdown widget with the ``multiple`` attribute.
- ``checkboxes``: Accept a container URI as a ``value``, allow to select multiple values with in a list of checkbox inputs. The list is provided via the ``range`` attribute, which expects a container’s URL, or via the ``enum`` attribute, which takes a list of the values separated by commas.
- ``file``: Inserts an ``<input/>`` and an ``<input type="file"/>``.
When a file is selected it’s uploaded, URL of file is returned by request and set as the ``<input/>`` value.
The upload URL is provided via the ``upload-url`` attribute.
- ``image``: Works like ``file`` but allow only images in the input, and create a preview of the image when selected by the user.
- ``color``: set ``value`` in an ``<input>`` of type ``color``.
- ``password``: set ``value`` in an ``<input>`` of type ``password``.
- ``time``: set ``value`` in an ``<input>`` of type ``time``. The format value is ``hh:mm``.
- ``set``
- ``default``: inserts widgets directly in the set tag.
- ``div``: inserts widgets in a ``<div>`` tag.
- ``ul``: inserts widgets in a ``<ul>`` tag.
- **default** (no type keyword defined)
- ``action``: Displays a link inside a ``<solid-link>`` tag with ``src`` for the ``data-src`` attribute,
``value`` for the ``next`` attribute and ``link-text`` as text content.
- ``multiple``: insert a ``solid-display`` with the ``@id`` of a container as ``data-src``.
The fields to display are chosen with the ``multiple-[field name]-fields`` attribute.
They allows to modify the behavior or the display of the widget. It is possible to add one or several features to the widget's name :
- ``label``: adds a ``label`` before the template. Uses the attribute ``name`` if ``label`` is not defined.
- ``labellast``: adds a ``label`` after the template. Uses the attribute ``name`` if ``label`` is not defined.
- ``autocompletion``: initializes the ``SlimSelect`` plugin. Works only with ``dropdown`` and ``multipleselect`` templates.
- ``autolink``: analyzes widget content, and transforms all links in anchor.
- ``mailto``: adds ``mailto:`` at the beginning of an ``href`` attribute. Works only with links.
- ``tel``: adds ``tel:`` at the beginning of an ``href`` attribute. Works only with links.
- ``blank``: adds an attribute ``target="_blank"``. Works only with links.
- ``placeholder``: adds a placeholder in the input. Uses the attribute ``name`` or ``label`` if ``placeholder`` is not defined. Works only with input widgets.
- ``date``: transforms the value in a date, in the browser’s default locale format.
- ``datetime``: transforms the value in a date and time, in the browser’s default locale format.
- ``multiline``: shows a value on multiple lines (replace ``\n`` by ``<br>``).
- ``markdown``: takes markdown code and displays formatted text. Works only with a display template (value, div, link).
- ``addable``: adds a ``<solid-form>`` that allows to add data on the field concerned.
It accepts attributes from :ref:`solid-form <solid-form>` by using ``addable-[field]-[attribute]="value"`` format.
If ``addable-data-src`` is not provided, the solid-form will use the URI in ``range-[field]`` as data-src, if declared.
- ``oembed``: displays the video content of an oEmbed link filled with the associated ``value-[field]`` attribute.