diff --git a/source/import_documentation/Components/Solid-Display.rst b/source/import_documentation/Components/Solid-Display.rst index b327fa1c885352adfef43eb48428c83ed637a933..5a600373c286257a45b5349e95cbc39c87bd12ac 100644 --- a/source/import_documentation/Components/Solid-Display.rst +++ b/source/import_documentation/Components/Solid-Display.rst @@ -22,6 +22,7 @@ Mixins ------ This component uses the following mixins: + * :ref:`required-mixin <required-mixin>` * :ref:`counter-mixin <counter-mixin>` * :ref:`federation-mixin <federation-mixin>` * :ref:`filter-mixin <filter-mixin>` diff --git a/source/import_documentation/Components/Solid-Form-Search.rst b/source/import_documentation/Components/Solid-Form-Search.rst index 4f0ffacf88639e136935810ee5fd2ba517ca2d4f..a27ad13e1ca1845747abb2093a3b8894279e2ae4 100644 --- a/source/import_documentation/Components/Solid-Form-Search.rst +++ b/source/import_documentation/Components/Solid-Form-Search.rst @@ -4,6 +4,7 @@ solid-form-search Allows you to filter the contents of a component that uses the ``filter-mixin`` such as ``solid-display`` or ``solid-map``. This must have a ``filtered-by`` attribute set to the id of the current ``solid-form-search``. + .. code:: html <solid-form-search @@ -41,12 +42,29 @@ Attributes If you want something fancier, you can set this attribute. i.e. ``label-username="Your name"`` +``submit-button`` +~~~~~~~~~~~~~ + Text of the submit button to create in the search form. If the attribute is not defined, + no button will be added and the form will trigger the search on change. + ``range-xyz`` ~~~~~~~~~~~~~ URL of a container which list the accepted values for the field ``xyz``. It’s particularly useful with a dropdown field. +``enum-xyz`` +~~~~~~~~~~~~~ + List of values of your choice for the field ``xyz``. + 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-xyz="value1, value2, value3"`` : each value will be displayed + and loaded in value attribute + * ``enum-xyz="value1 = a, value2 = b, value3 = c"``: each value will be displayed + and "a", "b", "c" will be loaded in value attribute. + Widgets ------- By default, the widget used is ``<solid-form-label-text>``. Cf the diff --git a/source/import_documentation/Components/Solid-Form.rst b/source/import_documentation/Components/Solid-Form.rst index d04f7ad62f34b751681509b7a9633a0446324b2b..f3d920ccf885e26887b702aa261f31ae61dec6b9 100644 --- a/source/import_documentation/Components/Solid-Form.rst +++ b/source/import_documentation/Components/Solid-Form.rst @@ -52,6 +52,18 @@ Attributes for the field ``xyz``. It’s particularly useful with a dropdown field. +``enum-xyz`` +~~~~~~~~~~~~~ + List of values of your choice for the field ``xyz``. + 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-xyz="value 1, value 2, value 3"`` : each value will be displayed + and loaded in value attribute + * ``enum-xyz="value1 = a, value2 = b, value3 = c"``: each value will be displayed + and "a", "b", "c" will be loaded in value attribute. + ``order-asc-xyz`` or ``order-desc-xyz`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Name of the field used to order the range list ``xyz``. @@ -71,6 +83,22 @@ Attributes Add this attribute for the field ``xyz`` to define its maximum value. It works only with a ``solid-form-number`` widget. +``pattern-xyz`` +~~~~~~~~~~~~~~~ + Add this attribute for the field ``xyz`` to define a regular expression to check the input's value. + It works only with a ``solid-form-text`` widget. + +``title-xyz`` +~~~~~~~~~~~~~~ + Add this attribute for the field ``xyz`` to precise extra information about an element. + It works only with a ``solid-form-text`` widget. + +``confirmation-message`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + 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. + + Widgets ------- By default, the widget used is ``<solid-form-label-text>``. Cf the diff --git a/source/import_documentation/Mixins/grouper-mixin.rst b/source/import_documentation/Mixins/grouper-mixin.rst index 047b670293f0622c728063caab4298fe2c2aa511..9b8270511b2b2b99bf4a080bf4ab738fd8ace98e 100644 --- a/source/import_documentation/Mixins/grouper-mixin.rst +++ b/source/import_documentation/Mixins/grouper-mixin.rst @@ -33,11 +33,23 @@ Attributes When used with the pagination, each group is paginated. -``group-by-widget`` +``group-widget`` ~~~~~~~~~~~~~~~~~~~ - default: ``solid-group-div`` + default: ``solid-group-default`` The name of the widget to use as a group widget. + It takes the name of the group as a ``value`` and put content in a ``div[data-content]``. + Here is an example of a custom group widget: + + .. code:: html + + <solid-widget name="custom-group"> + <template> + <h2>${value}</h2> + <section data-content></section> + </template> + </solid-widget> + ``group-class`` diff --git a/source/import_documentation/Mixins/next-mixin.rst b/source/import_documentation/Mixins/next-mixin.rst index 4dd2fa243969f32f710d219064b2ac1f88eedbb3..539b849fbff7fc8263497e6713a132d8c3bdfe30 100644 --- a/source/import_documentation/Mixins/next-mixin.rst +++ b/source/import_documentation/Mixins/next-mixin.rst @@ -20,11 +20,11 @@ Attributes ``next`` ~~~~~~~~ - `name` attribute of the `<solid-route>` that should be accessed when a `<solid-display>`, `<solid-map>` or `<solid-calendar>` element is clicked. + `name` attribute of the ``<solid-route>`` that should be accessed when a ``<solid-display>``, ``<solid-map>`` or ``<solid-calendar>`` element is clicked. - It can also be used to indicate the `name` attribute of the `<solid-route>` to reach after : - - * a click on a `<solid-delete>` button (only after the resource is correctly deleted); - * a click on the submit button in a `<solid-form>` (only after the resource is correctly saved). + It can also be used to indicate the ``name`` attribute of the ``<solid-route>`` to reach after : - See the documentation of `<solid-router>` for more details. + * a click on a ``<solid-delete>`` button (only after the resource is correctly deleted); + * a click on the submit button in a ``<solid-form>`` (only after the resource is correctly saved). + + See the documentation of ``<solid-router>`` for more details. diff --git a/source/import_documentation/Mixins/required-mixin.rst b/source/import_documentation/Mixins/required-mixin.rst new file mode 100644 index 0000000000000000000000000000000000000000..48cca54abe861df0abf36c1f30914b00f91a35a0 --- /dev/null +++ b/source/import_documentation/Mixins/required-mixin.rst @@ -0,0 +1,31 @@ +.. _required-mixin: +required-mixin +=============== + +The required mixin is a post-processor mixin, compatible with list-mixin. +It provides the ability to display a list of resources according to the property/-ies its possess. + +Used by: +-------- + + * :ref:`solid-display <solid-display>` + + +Attributes +---------- + +``required-xyz`` +~~~~~~~~~~~~~~~~ + The attribute takes no value. ``xyz`` represents the mandatory property of resources to be displayed. + + In this example, users must have email to be dislayed. + + .. code:: html + + <solid-display + data-src=http://server/users/" + fields="username" + required-email + ></solid-display> + + It is possible to combine this mixin twice, ``required-uvw`` and ``required-xyz``. \ No newline at end of file diff --git a/source/import_documentation/Mixins/store-mixin.rst b/source/import_documentation/Mixins/store-mixin.rst index d3b7c2b63a53c49f67ee4f28c128c92cd0cbac9f..30b86a071d2c8a4b824eaae1784887f341dfa57f 100644 --- a/source/import_documentation/Mixins/store-mixin.rst +++ b/source/import_documentation/Mixins/store-mixin.rst @@ -75,6 +75,42 @@ Attributes .. image:: ./../../_static/images/import_documentation/loader.gif :alt: Exemple of loader +``no-render`` +~~~~~~~~~~~~~ + While this attribute is present on a component, no data will be fetched. + This attribute is automatically removed by the router when the component + is in a view which has been activated. + This allow to lazy-load components. + + +``store://`` attribute values +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + This mixin decode all attribute values starting by ``store://resource`` or + ``store://user`` and replace them by the values fetched from the store. + + It can be a value fetched from the current resource or the current logged in user (works with ``sib-auth``). + + This example will create a text input filled with the username of the current user: + + .. code:: html + + <solid-form + data-src="https://api.startinblox.com/circles/" + fields="user" + value-user="store://user.username" + ></solid-form> + + + This example will write the name of the circle in the custom field: + + .. code:: html + + <solid-display + data-src="https://api.startinblox.com/circles/1/" + fields="custom-field" + value-custom-field="store://resource.name" + ></solid-display> + Events ------ diff --git a/source/import_documentation/Mixins/widget-mixin.rst b/source/import_documentation/Mixins/widget-mixin.rst index 9d088a8b08d3015f24421da89bb2718c36e4abca..83c8c52da7c7e5a8b8146212e4c33ca50fd1642e 100644 --- a/source/import_documentation/Mixins/widget-mixin.rst +++ b/source/import_documentation/Mixins/widget-mixin.rst @@ -99,7 +99,7 @@ Attributes ``class-[field]`` ~~~~~~~~~~~~~~~~~ - Set the class applied to the widget of the ``[field]`` + Set the class applied to the widget of the ``[field]`` or the set. ``editable-[field]`` ~~~~~~~~~~~~~~~~~~~~ @@ -125,19 +125,36 @@ Attributes ``multiple-[field]`` ~~~~~~~~~~~~~~~~~~~~ - Show ``[field]`` as multiple field containing - one widget for each child. + 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. - All attributes starting by ``each`` will be applied on each child, - without the prefix ``each``. - - ``each-label-[field]``: label of each child of multiple widget - - ``each-class-[field]``: class of each child of multiple widget - - ``each-range-[field]``: range value of each child of multiple widget + 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: diff --git a/source/import_documentation/Widgets/Reference.rst b/source/import_documentation/Widgets/Reference.rst index 57e200277ddde88a0ce6344b060d7c58e2044556..b617f45867aa6f91e4818ad485f91b546c3cb13f 100644 --- a/source/import_documentation/Widgets/Reference.rst +++ b/source/import_documentation/Widgets/Reference.rst @@ -1,5 +1,5 @@ Widgets API Reference -================== +====================== Widgets 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. @@ -35,22 +35,24 @@ A widget is built like this. - ``form`` directory - - ``text``: set ``value`` in an ``<input>`` of type ``text`` - - ``textarea``: set ``value`` in a ``<textarea>`` - - ``checkbox``: create a checkbox, which is checked if ``value == true`` - - ``date``: set ``value`` in an ``<input>`` of type ``date`` + - ``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``. + - ``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. - - ``number``: set ``value`` in an ``<input>`` of type ``number`` + - ``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. - - ``hidden``: set ``value`` in an ``<input>`` of type ``hidden`` - - ``dropdown``: set ``value`` in a ``<select>``. The list is provided via the ``range`` attribute, which expects a container’s URL. - - ``radio``: set ``value`` in a list of radio buttons. The list is provided via the ``range`` attribute, which expects a container’s URL. + - ``hidden``: set ``value`` in an ``<input>`` of type ``hidden``. + - ``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. - ``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 a ``<input>`` of type ``color``. - ``set`` @@ -81,4 +83,4 @@ A widget is built like this. - ``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). diff --git a/source/index.rst b/source/index.rst index 1a3880267b420ee852f426dfd50c9951f30ee6e3..23a1705b4aea782f28afb844498492f43b44c4a8 100644 --- a/source/index.rst +++ b/source/index.rst @@ -27,6 +27,7 @@ Welcome to Startinblox's documentation import_documentation/Components/Solid-Display import_documentation/Components/Solid-Form + import_documentation/Components/Solid-Form-Search import_documentation/Components/Solid-Delete import_documentation/Components/Solid-Calendar import_documentation/Components/Solid-Map @@ -56,6 +57,7 @@ Welcome to Startinblox's documentation import_documentation/Mixins/paginate-mixin import_documentation/Mixins/sorter-mixin import_documentation/Mixins/highlighter-mixin + import_documentation/Mixins/required-mixin import_documentation/Mixins/next-mixin .. toctree::