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

The `solid-form` component serves dual purposes: editing existing resources 
and creating new resources within a container.


## Functionality

### Editing a Resource

The `solid-form` component receives the URL of a resource via its `data-src` attribute 
and displays a form for editing the resource.

.. code:: html

   <solid-form data-src="http://example.com/resource/123"></solid-form>

### Creating a Resource

If provided with the URL of a container of resources, the `solid-form` component displays 
a form for creating a new resource and adding it to the container.

.. code:: html

   <solid-form data-src="http://example.com/container"></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 refer to their documentation for more details about their capabilities.


Specific attributes
-------------------

.. _autocomplete-field-sf:
``autocomplete-[field]``
~~~~~~~~~~~~~~~~~~~~~~~~
   *Available from version 0.15*

   When set to ``off``, it disables the automatic entry of values in the specified ``[field]``. 
   This attribute can be added to ``inputs``, ``textarea`` and ``select``.


.. _autosave:
``autosave``
~~~~~~~~~~~~
   *Available from version 0.16*

   If this 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.


.. _class-submit-button-sf:
``class-submit-button``
~~~~~~~~~~~~~~~~~~~~~~~
Define the ``class`` of the ``div`` containing the submit button.


.. _enum-field-sf:
``enum-[field]``
~~~~~~~~~~~~~~~~
   *Available from version 0.13*

   Specifies a list of values for the specified ``[field]``.
   These values must be be filled manually and separated by commas. 
   This is particularly useful for dropdown or radio fields.

   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.


``fields``
~~~~~~~~~~
   Specifies the list of fields used to create the form. By default, all fields are used. 
   More details can be found in the **widget-mixin attributes** section


.. _label-field-sf:
``label-[field]``
~~~~~~~~~~~~~~~~~
   When displaying a form, the default labels are the field names of the model.
   To customize a label, use this attribute, i.e. ``label-username="Your name"``


.. _max-field:
``max-[field]``
~~~~~~~~~~~~~~~
   Specifies the maximum value for the specified ``[field]``.
   This attribute works only with ``solid-form-number`` and ``solid-form-time`` widgets.


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

   Specifies the maximum number of characters that can be typed for the specified  ``[field]``.
   This attribute works only with ``solid-form-text``, ``solid-form-email`` or ``solid-form-password`` and ``solid-form-textarea`` widgets.


.. _min-field:
``min-[field]``
~~~~~~~~~~~~~~~
   Specifies the minimum value for the specified ``[field]``.
   This attribute works only with ``solid-form-number`` and ``solid-form-time`` widgets.


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

   Specifies the minimum number of characters that can be typed for the specified ``[field]``.
   This attribute works only with ``solid-form-text``, ``solid-form-email`` or ``solid-form-password`` and ``solid-form-textarea`` widgets.


.. _naked:
``naked``
~~~~~~~~~
   When set, this attribute removes the submit button. This is particularly useful to prevent the nested forms to
   display their own submit button.


.. _order-asc-field:
.. _order-desc-field:
``order-asc-[field]`` or ``order-desc-[field]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Specifies the field used to order the range list ``[field]``.
   i.e. ``order-asc-users="username"``


.. _partial:
``partial``
~~~~~~~~~~~
   Use this attribute when the form does not include all the fields of the resource that you want to update. 
   This indicates that only the provided fields should be updated, leaving the unspecified fields unchanged.


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

   ASpecifies a regular expression to validate the input's value for the specified ``[field]``.
   This attribute works only with a ``solid-form-text`` widget.


.. _range-field-sf:
``range-[field]``
~~~~~~~~~~~~~~~~~
   Specifies the URL of a container that lists the accepted values for the specified ``[field]``. 
   This is particularly useful with a dropdown field.


.. _required-field:
``required-[field]``
~~~~~~~~~~~~~~~~~~~~
   Makes the specified ``[field]`` required by adding the ``required`` attribute to the input.


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

   Specifies the stepping interval number for the specified  ``[field]`` based on the ``min-[field]`` value. This attribute works with:
      -  ``solid-form-time`` widget : The value is given in seconds (default value is 60).
      -  ``solid-form-number`` widget : The default value is 1.

.. _submit-button-sf:
``submit-button``
~~~~~~~~~~~~~~~~~
   Specifies the text of the form's submit button.


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

   Adds extra information about the specified ``[field]``.
   This attribute works only with a ``solid-form-text`` widget.


.. _upload-url-field:
``upload-url-[field]``
~~~~~~~~~~~~~~~~~~~~~~
   Specifies the URL to upload a file for the specified ``[field]``. This attribute automatically sets
   ``widget-[field]`` to ``solid-form-file`` if not defined.
   This is particularly useful with a dropdown field.
 


Mixin attributes
-----------------

**From next-mixin :**

.. include:: ../Mixins/next-mixin.rst
   :start-line: 21

**From store-mixin :**

.. include:: ../Mixins/store-mixin.rst
   :start-line: 21
   :end-before: Events

**From validation-mixin :**

.. include:: ../Mixins/validation-mixin.rst
   :start-line: 17

**From widget-mixin :**

.. include:: ../Mixins/widget-mixin.rst
   :start-line: 18


Widgets
-------
By default, the widget used is ``<solid-form-label-text>``. Cf the 
:ref:`Widget <reference>` page for more info.


Events
-------

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

``save``
~~~~~~~~~~~~~~
   Triggered when the response of the submit has been received successfully