From 103cd0d732070ff1774c1959a2fc22e179a0f31a Mon Sep 17 00:00:00 2001
From: Benoit Alessandroni <benoit@startinblox.com>
Date: Tue, 30 Jul 2024 15:18:25 +0200
Subject: [PATCH] Update: master and clean some typos.
---
.../Components/Solid-Form.rst | 230 ++++++++++--------
1 file changed, 129 insertions(+), 101 deletions(-)
diff --git a/source/import_documentation/Components/Solid-Form.rst b/source/import_documentation/Components/Solid-Form.rst
index 90bc1fe..40938c0 100644
--- a/source/import_documentation/Components/Solid-Form.rst
+++ b/source/import_documentation/Components/Solid-Form.rst
@@ -2,14 +2,30 @@
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.
+The `solid-form` component serves dual purposes: editing existing resources
+and creating new resources within a container.
+
+
+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://server/todos/"></solid-form>
+ <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
------
@@ -20,64 +36,44 @@ This component uses the following mixins:
* :ref:`validation-mixin <validation-mixin>`
* :ref:`widget-mixin <widget-mixin>`
-Please check their documentation to know more about their capabilities.
+Please refer to their documentation for more details about their capabilities.
Specific attributes
-------------------
-``fields``
-~~~~~~~~~~
- List of the fields used to create the form (by default, all of them are used).
+.. _autocomplete-field-sf:
+``autocomplete-[field]``
+~~~~~~~~~~~~~~~~~~~~~~~~
+ *Available from version 0.15*
- More details on its use below (in **widget-mixin attributes**).
+ 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``.
-.. _label-field-sf:
-``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:
-``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.
+.. _autosave:
+``autosave``
+~~~~~~~~~~~~
+ *Available from version 0.16*
-.. _upload-url-field:
-``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.
+ 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.
-.. _submit-button-sf:
-``submit-button``
-~~~~~~~~~~~~~~~~~
- Text of the submit button of the form.
.. _class-submit-button-sf:
``class-submit-button``
~~~~~~~~~~~~~~~~~~~~~~~
Define the ``class`` of the ``div`` containing the submit button.
-
-.. _range-field-sf:
-``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-sf:
``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.
+ 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
@@ -86,95 +82,127 @@ Define the ``class`` of the ``div`` containing the submit button.
* ``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]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Name of the field used to order the range list ``[field]``.
+ Specifies the field used to order the range list ``[field]``.
i.e. ``order-asc-users="username"``
+
.. _partial:
``partial``
~~~~~~~~~~~
- Add this attribute when the form does not include
- all the fields of the resource to update.
-
-
-.. _required-field:
-``required-[field]``
-~~~~~~~~~~~~~~~~~~~~
- Add this attribute to make the ``[field]`` required by adding the ``required`` attribute to the input.
+ 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.
-.. _min-field:
-``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:
-``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:
``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.
+ ASpecifies a regular expression to validate the input's value for the specified ``[field]``.
+ This attribute works only with a ``solid-form-text`` widget.
-.. _title-field:
-``title-[field]``
+
+.. _range-field-sf:
+``range-[field]``
~~~~~~~~~~~~~~~~~
- *Available from version 0.13*
+ Specifies the URL of a container that lists the accepted values for the specified ``[field]``.
+ This is particularly useful with a dropdown field.
- Add this attribute for the field ``[field]`` to precise extra information about an element.
- It works only with a ``solid-form-text`` widget.
-.. _autocomplete-field-sf:
-``autocomplete-[field]``
-~~~~~~~~~~~~~~~~~~~~~~~~
- *Available from version 0.15*
+.. _required-field:
+``required-[field]``
+~~~~~~~~~~~~~~~~~~~~
+ Makes the specified ``[field]`` required by adding the ``required`` attribute to the input.
- 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:
-``autosave``
-~~~~~~~~~~~~
+.. _step-field:
+``step-[field]``
+~~~~~~~~~~~~~~~~
*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.
+ 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.
-.. _maxlength-field:
-``maxlength-[field]``
-~~~~~~~~~~~~~~~~~~~~~
- *Available from version 0.16*
+.. _submit-button-sf:
+``submit-button``
+~~~~~~~~~~~~~~~~~
+ Specifies the text of the form's submit button.
- 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:
-``minlength-[field]``
-~~~~~~~~~~~~~~~~~~~~~
- *Available from version 0.16*
+.. _title-field:
+``title-[field]``
+~~~~~~~~~~~~~~~~~
+ *Available from version 0.13*
- 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.
+ Adds extra information about the specified ``[field]``.
+ This attribute works only with a ``solid-form-text`` widget.
-.. _step-field:
-``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.
+.. _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
--
GitLab