.. _solid-form:
solid-form
==========

Receives the URL of a ressource via its ``data-src`` attribute, and
displays a form to edit the resource. If given the URL of a container of
ressources, and displays a creation form to add a resource to the
container.

.. code:: html

   <solid-form data-src="http://server/todos/"></solid-form>

Mixins
------

This component uses the following mixins:
   * :ref:`next-mixin <next-mixin>`
   * :ref:`store-mixin <store-mixin>`
   * :ref:`validation-mixin <validation-mixin>`
   * :ref:`widget-mixin <widget-mixin>`

Please check their documentation to know more about their capabilities.

Attributes
----------

``fields``
~~~~~~~~~~
   List of the fields used to create the form (by default, all of them are used).

``label-[field]``
~~~~~~~~~~~~~~~~~
   When displaying a form, the default labels are the fields names of the model.
   If you want something fancier, you can set this attribute.
   i.e. ``label-username="Your name"``

``naked``
~~~~~~~~~
   When the attribute is set, the submit button will be
   removed. It’s particularly useful to prevent the nested forms to
   display their own submit button.

``upload-url-[field]``
~~~~~~~~~~~~~~~~~~~~~~
   URL to upload file for field ``[field]``, it
   automatically set ``widget-[field]`` to ``solid-form-file`` if net defined.
   It’s particularly useful with a dropdown field.

``submit-button``
~~~~~~~~~~~~~~~~~
   Text of the submit button of the form.

``range-[field]``
~~~~~~~~~~~~~~~~~
   URL of a container which list the accepted values
   for the field ``[field]``. It’s particularly useful with a dropdown
   field.

``enum-[field]``
~~~~~~~~~~~~~~~~
   *Available from version 0.13*

   List of values of your choice for the field ``[field]``. 
   They have to be filled manually and must be separated by commas. 
   It’s particularly useful with a dropdown or radio field.

   Two formats are possible:
      * ``enum-[field]="value 1, value 2, value 3"`` : each value will be displayed 
      and loaded in value attribute
      
      * ``enum-[field]="value1 = a, value2 = b, value3 = c"``: each value will be displayed 
      and "a", "b", "c" will be loaded in value attribute.

``order-asc-[field]`` or ``order-desc-[field]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Name of the field used to order the range list ``[field]``.

``partial``
~~~~~~~~~~~
   Add this attribute when the form does not include
   all the fields of the resource to update.

``min-[field]``
~~~~~~~~~~~~~~~
   Add this attribute for the field ``[field]`` to define its minimum value.
   It works only with ``solid-form-number`` and ``solid-form-time`` widgets.

``max-[field]``
~~~~~~~~~~~~~~~
   Add this attribute for the field ``[field]`` to define its maximum value.
   It works only with ``solid-form-number`` and ``solid-form-time`` widgets.

``pattern-[field]``
~~~~~~~~~~~~~~~
   *Available from version 0.13*

   Add this attribute for the field ``[field]`` to define a regular expression to check the input's value.
   It works only with a ``solid-form-text`` widget.

``title-[field]``
~~~~~~~~~~~~~~~~~
   *Available from version 0.13*

   Add this attribute for the field ``[field]`` to precise extra information about an element.
   It works only with a ``solid-form-text`` widget.

``confirmation-message``
~~~~~~~~~~~~~~~~~~~~~~~~
   *Available from version 0.13*
   **Migrated to the validation mixin page in version 0.16**

   Add this attribute to create a dialog box linked with the submit button of the solid-form.
   Its value matches the message displayed in the dialog box.

``autocomplete-[field]``
~~~~~~~~~~~~~~~~~~~~~~~~
   *Available from version 0.15*

   Equal to the value ``off``, it cancels the automatic entry of values in the relevant ``[field]``.
   It can be added to ``inputs``, ``textarea`` and ``select``.

``autosave``
~~~~~~~~~~~~
   *Available from version 0.16*

   If the attribute is defined, each change in an input will trigger a request to update the resource.
   This attribute works only when editing resources, not creating them.


``maxlength-[field]``
~~~~~~~~~~~~~~~~~~~~~
   *Available from version 0.16*

   Add this attribute for the field ``[field]`` to define the maximum number of characters that can be typed.
   It works only with ``solid-form-text``, ``solid-form-email`` or ``solid-form-password`` and ``solid-form-textarea`` widgets.

``minlength-[field]``
~~~~~~~~~~~~~~~~~~~~~
   *Available from version 0.16*

   Add this attribute for the field ``[field]`` to define the minimum number of characters that can be typed.
   It works only with ``solid-form-text``, ``solid-form-email`` or ``solid-form-password`` and ``solid-form-textarea`` widgets.


``step-[field]``
~~~~~~~~~~~~~~~~
   *Available from version 0.16*

   Add this attribute for the field ``[field]`` to define the stepping interval number to use as constraint validation. Its based on the ``min-[field]`` value.
   It works with :
      -  ``solid-form-time`` widget : Its value is given in seconds (default value is 60).
      -  ``solid-form-number`` widget : Its default value is 1.

Widgets
-------
By default, the widget used is ``<solid-form-label-text>``. Cf the
`Widget <https://docs.startinblox.com/import_documentation/Widgets/Reference.html>`__ page for more info.


Events
-------

``formChange``
~~~~~~~~~~~~~~
   Triggered when the form values change

``save``
~~~~~~~~~~~~~~
   Triggered when the response of the submit has been received (successfull or not)