diff --git a/source/_static/images/import_documentation/podcast_tutorial/Mockup-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Mockup-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..2bebe7ff0ad43fe0eb10c6951d11f595e230a3c1
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Mockup-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render1-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render1-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..c081a8d4be5aa7bba03f03a83db1d09b9f43687b
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render1-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render10-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render10-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..3672ad5151edd72ef96d1b1d8819242f66be8bbe
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render10-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render2-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render2-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..5240f63b1044a688fdb81b001d46bf630f22260d
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render2-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render3-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render3-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..2d53cc4fb420f34df35d370785da5530591b1c93
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render3-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render4-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render4-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..593e034d834a8f1538ee843fe05211839cc06e29
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render4-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render5-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render5-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..ed8c7907f1d3919bb50ec2586608f70ba3588a0e
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render5-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render6-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render6-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..a46dbee74d4937651e70a8d99492fee51cf18dde
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render6-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render7-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render7-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..a961af8f3e76b0fd7f9cd489eb83ccf363a52a4b
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render7-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render8-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render8-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..6dc4d09c4aa99dffddb478634d5abe3912ff7ab3
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render8-Podcast-Tutorial.png differ
diff --git a/source/_static/images/import_documentation/podcast_tutorial/Render9-Podcast-Tutorial.png b/source/_static/images/import_documentation/podcast_tutorial/Render9-Podcast-Tutorial.png
new file mode 100644
index 0000000000000000000000000000000000000000..be456e7e694a4bd8270229cca6ade0c3a19e6a0b
Binary files /dev/null and b/source/_static/images/import_documentation/podcast_tutorial/Render9-Podcast-Tutorial.png differ
diff --git a/source/import_documentation/Components/Solid-Delete.rst b/source/import_documentation/Components/Solid-Delete.rst
index 44c8733b8bf8ff28f29182c91b37b23355f0e901..043e6d295c504323569b5c19445db1a6cf5f9b4d 100644
--- a/source/import_documentation/Components/Solid-Delete.rst
+++ b/source/import_documentation/Components/Solid-Delete.rst
@@ -34,12 +34,7 @@ Attributes
``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 button of the solid-delete.
- Its value matches the message displayed in the dialog box.
-
+ **Migrated to the :ref:`validation-mixin <validation-mixin>` page in version 0.16**
Events
-------
diff --git a/source/import_documentation/Components/Solid-Form-Search.rst b/source/import_documentation/Components/Solid-Form-Search.rst
index 5265770dda181c0aaf0c7d8f8f175a0f34e1e6ff..1fe1e9bba588a3cf20157c671e40c1235f99383f 100644
--- a/source/import_documentation/Components/Solid-Form-Search.rst
+++ b/source/import_documentation/Components/Solid-Form-Search.rst
@@ -51,11 +51,16 @@ Attributes
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.
+.. _class-submit-button-sfs:
+``class-submit-button``
+~~~~~~~~~~~~~~~~~~~~~~~
+ Define the ``class`` of the ``div`` containing the submit button.
+
.. _range-field-sfs:
``range-[field]``
~~~~~~~~~~~~~~~~~
URL of a container which list the accepted values
- for the field ``[field]``. It’s particularly useful with a dropdown
+ for the field ``[field]``. It’s particularly useful with a dropdown or multipleselect
field.
.. _enum-field-sfs:
@@ -100,6 +105,68 @@ Attributes
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``.
+.. _search-placeholder-field:
+``search-placeholder-[field]``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ *Available from version 0.17*
+
+ Allows to modify "searchPlaceholder" displayed in the search bar (from SlimSelect plugin).
+ Its value by default is "Search" in English, "Rechercher" in French.
+ **It works only with the ``autocompletion`` feature.**
+
+.. _search-text-field:
+``search-text-[field]``
+~~~~~~~~~~~~~~~~~~~~~~~
+ *Available from version 0.17*
+
+ Allows to modify "searchText" displayed when no value is found (from SlimSelect plugin).
+ Its value by default is "No result" in English, "Aucun résultat" in French.
+ **It works only with the ``autocompletion`` feature.**
+
+ .. code:: html
+
+ <solid-form-search
+ id="filter-multiselectautocomp"
+ fields="skills"
+ widget-skills="solid-form-multipleselect-autocompletion-placeholder"
+ placeholder-skills="Please, pick a value"
+ search-text-skills="Nothing found"
+ search-placeholder-skills="Searching..."
+ ></solid-form-search>
+ <solid-display
+ data-src="data/list/users.jsonld"
+ fields="username, skills"
+ multiple-skills
+ filtered-by="filter-multiselectautocomp"
+ ></solid-display>
+
+
+.. _auto-range-field:
+``auto-range-[field]``
+~~~~~~~~~~~~~~~~~~~~~~~
+ *Available from version 0.17*
+
+ Dynamically populates a dropdown based on the values of the ``solid-display``(s) associated.
+ For each ``solid-display``, it will look for its ``field`` values, and add them to the dropdown.
+ Each value is displayed only once.
+ ``field`` can target a ``container`` or a ``resource``.
+
+ In this example below, ``auto-range-skills ``attribute catches all skill values for all users in the ``data-src`` `data/list/users` and displays in the dropdown all skills once :
+ .. code:: html
+
+ <solid-form-search
+ id="filter-autorange"
+ fields="skills"
+ auto-range-skills
+ ></solid-form-search>
+ <solid-display
+ data-src="data/list/users.jsonld"
+ fields="username, skills"
+ multiple-skills
+ filtered-by="filter-autorange"
+ ></solid-display>
+
+
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 44bc4057d852d05f146c8ebb258ae4c34535a9cb..498a2bb60125f39f9e8dc791b38ae9c3f32d2bb5 100644
--- a/source/import_documentation/Components/Solid-Form.rst
+++ b/source/import_documentation/Components/Solid-Form.rst
@@ -55,6 +55,11 @@ Attributes
~~~~~~~~~~~~~~~~~
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]``
~~~~~~~~~~~~~~~~~
@@ -83,6 +88,7 @@ Attributes
``order-asc-[field]`` or ``order-desc-[field]``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Name of the field used to order the range list ``[field]``.
+ i.e. ``order-asc-users="username"``
.. _partial:
``partial``
@@ -127,11 +133,7 @@ Attributes
``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.
+ **Migrated to the :ref:`validation-mixin <validation-mixin>` page in version 0.16**
.. _autocomplete-field-sf:
``autocomplete-[field]``
diff --git a/source/import_documentation/Mixins/translation-mixin.rst b/source/import_documentation/Mixins/translation-mixin.rst
new file mode 100644
index 0000000000000000000000000000000000000000..5404058ea634eec13a0976d84b2b1599fc3f630a
--- /dev/null
+++ b/source/import_documentation/Mixins/translation-mixin.rst
@@ -0,0 +1,19 @@
+.. _translation-mixin:
+translation-mixin
+=================
+*Available from version 0.17*
+
+The translation mixin provides an automatic translation in elements, depending on the browser language (English and French). Translations are default values, visible if no value is given by an attribute.
+
+The concerned elements are :
+ - the submit-button in :ref:`solid-form <solid-form>`,
+ - the button in :ref:`solid-delete <solid-delete>`,
+ - the confirmation message from :ref:`validation-mixin <validation-mixin>`,
+ - the text in modal dialog's buttons from :ref:`validation-mixin <validation-mixin>`,
+ - :ref:`search-placeholder-[field] <search-placeholder-[field]>` and :ref:`search-text-[field] <search-text-[field]>` attributes available with ``autocompletion`` feature (SlimSelect plugin) from :ref:`widget API reference <reference>`.
+
+Used by:
+--------
+
+ * :ref:`store-mixin <store-mixin>`
+ * :ref:`validation-mixin <validation-mixin>`
\ No newline at end of file
diff --git a/source/import_documentation/Mixins/validation-mixin.rst b/source/import_documentation/Mixins/validation-mixin.rst
index 43269d2b2999c2a99d16eaab0c00dcc20af70dfd..33ed5dd3aca6894a7ab29fcfc28c98d4c76d82a5 100644
--- a/source/import_documentation/Mixins/validation-mixin.rst
+++ b/source/import_documentation/Mixins/validation-mixin.rst
@@ -26,7 +26,8 @@ Attributes
``confirmation-message``
~~~~~~~~~~~~~~~~~~~~~~~~
Message displayed in the modal dialog (``confirm`` or ``dialog`` type).
- The message by default is "Please, confirm your choice".
+ The message by default is "Please, confirm your choice" in English, "Merci de confirmer votre choix" in French.
+
**The attributes below only concern ``dialog`` type.**
@@ -34,12 +35,12 @@ Attributes
.. _confirmation-submit-text:
``confirmation-submit-text``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Text displayed on the submit button ("Ok" by default).
+ Text displayed on the submit button (by default, "Ok" in English, "Oui" in French).
.. _confirmation-cancel-text:
``confirmation-cancel-text``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Text displayed on the cancel button ("Cancel" by default).
+ Text displayed on the cancel button (by default "Cancel" in English, "Annuler" in French).
.. _confirmation-submit-class:
``confirmation-submit-class``
@@ -69,4 +70,30 @@ Attributes
confirmation-submit-text="Yes, I am"
confirmation-submit-class="submit-button"
confirmation-cancel-class="cancel-button"
- ></solid-form>
\ No newline at end of file
+ ></solid-form>
+
+.. _confirmation-widget:
+``confirmation-widget``
+~~~~~~~~~~~~~~~~~~~~~~~
+ *Available from version 0.17*
+
+ Allows to insert a widget in the modal dialog, instead of ``confirmation-message`` (confirmation-widget prevails over confirmation-message).
+ The widget can contain a ``<solid-display>`` to display data from the resource concerned.
+
+ Example of confirmation-widget attribute use :
+
+ .. code:: html
+
+ <solid-widget name="confirm-delete-widget">
+ <template>
+ <div>
+ <p>Are you sure to delete <strong><solid-display fields="name" data-src="${value}" style="display:inline-block"></solid-display></strong> ? </p>
+ </div>
+ </template>
+ ></solid-widget>
+
+ <solid-delete
+ data-src="http://server/user/"
+ confirmation-type="dialog"
+ confirmation-widget="confirm-delete-widget"
+ ></solid-delete>
diff --git a/source/import_documentation/Mixins/widget-mixin.rst b/source/import_documentation/Mixins/widget-mixin.rst
index 9593647672fbc0f6114dd92d9c1ba0e3a0bf42a2..1f0d745ccb47acebe2e2525ecf6790b5feddce53 100644
--- a/source/import_documentation/Mixins/widget-mixin.rst
+++ b/source/import_documentation/Mixins/widget-mixin.rst
@@ -192,8 +192,7 @@ Attributes
It can be used in :
- - ``solid-display``: a nested ``solid-display`` will be created with the container URI as
- data-src.
+ - ``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:
diff --git a/source/import_documentation/Widgets/Reference.rst b/source/import_documentation/Widgets/Reference.rst
index 634040aa8dcb51a0407f03463c9b434dbd9ef417..5f10c22dab6ff0888010b281d3a9fa7560f102bd 100644
--- a/source/import_documentation/Widgets/Reference.rst
+++ b/source/import_documentation/Widgets/Reference.rst
@@ -82,7 +82,7 @@ Features to add to the widget. You can choose as many as you want
- ``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 dropdowns.
+- ``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.
diff --git a/source/import_documentation/attributes-list.rst b/source/import_documentation/attributes-list.rst
index 41f754709d4780e907ffb694898151801ac5eb95..6f6adf03b00084bc11fe74cf101ce512e846aedc 100644
--- a/source/import_documentation/attributes-list.rst
+++ b/source/import_documentation/attributes-list.rst
@@ -14,6 +14,10 @@ List of attributes (core framework)
* :ref:`solid-form <autocomplete-field-sf>`
* :ref:`solid-form-search <autocomplete-field-sfs>`
+``auto-range-[field]``
+~~~~~~~~~~~~~~~~~~~~~~
+ * :ref:`solid-form-search <auto-range-field>`
+
``autosave``
~~~~~~~~~~~~
* :ref:`solid-form <autosave>`
@@ -26,6 +30,11 @@ List of attributes (core framework)
~~~~~~~~~~~~~~~~~
* :ref:`widget-mixin <class-field>`
+``class-submit-button``
+~~~~~~~~~~~~~~~~~~~~~~~
+ * :ref:`solid-form <class-submit-button-sf>`
+ * :ref:`solid-form-search <class-submit-button-sfs>`
+
``clustering``
~~~~~~~~~~~~~~
* :ref:`solid-map <solid-map>`
@@ -54,6 +63,10 @@ List of attributes (core framework)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`validation-mixin <confirmation-submit-text>`
+``confirmation-widget``
+~~~~~~~~~~~~~~~~~~~~~~~
+ * :ref:`validation-mixin <confirmation-widget>`
+
``counter-template``
~~~~~~~~~~~~~~~~~~~~
* :ref:`counter-mixin <counter-mixin>`
@@ -273,6 +286,14 @@ List of attributes (core framework)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`filter-mixin <filter-mixin>`
+``search-placeholder-[field]``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ * :ref:`solid-form-search <search-placeholder-field>`
+
+``search-text-[field]``
+~~~~~~~~~~~~~~~~~~~~~~~
+ * :ref:`solid-form-search <search-text-field>`
+
``src-[field]``
~~~~~~~~~~~~~~~
* :ref:`widget-mixin <src-field>`
diff --git a/source/import_documentation/build-full-application.rst b/source/import_documentation/build-full-application.rst
index 8b5fb1bbd0e390ea6ea7f43cdf5bf007e3312d01..fb6abf6f5f33f35e25c2233c7c822f225b934bb4 100644
--- a/source/import_documentation/build-full-application.rst
+++ b/source/import_documentation/build-full-application.rst
@@ -8,7 +8,8 @@ With the core of the framework and some offical components, we'll be able to bui
To start, simply import the core in your HTML file:
-.. code:: html
+.. code-block:: html
+
<!-- ... Import the core ... -->
<script type="module" src="https://unpkg.com/@startinblox/core"></script>
</head>
@@ -21,7 +22,8 @@ You can now freely use all the component included in the core.
For the example we are going to build a directory.
-.. code:: html
+.. code-block:: html
+
<!-- ... Add a form ... -->
<sib-form
data-src="https://api.startinblox.com/users/"
@@ -49,7 +51,8 @@ The form and the display are connected to the same data sources. When you add pe
Let's assume we want to add a menu to our app. We're gonna add the router component ``sib-router``
-.. code:: html
+.. code-block:: html
+
<!-- ... Import the core ... -->
<script type="module" src="https://unpkg.com/@startinblox/core"></script>
<!-- ... Import SiB Router ... -->
diff --git a/source/import_documentation/djangoldp-references.rst b/source/import_documentation/djangoldp-references.rst
index cf577ad9751ca268d92389882c732d4483331acc..ea4787495626f29033ac1448e723a8891d19eefe 100644
--- a/source/import_documentation/djangoldp-references.rst
+++ b/source/import_documentation/djangoldp-references.rst
@@ -4,7 +4,8 @@ DjangoLDP reference guide
The DjangoLDP commands
======================
-.. code-block:: bash
+.. code-block:: bash
+
$ djangoldp --help
Usage: djangoldp [OPTIONS] COMMAND [ARGS]...
@@ -21,7 +22,7 @@ The DjangoLDP commands
runserver Run the Django embeded webserver.
startpackage Start a DjangoLDP package.
-The `djangoldp` server is built ontop of `django` framework. The `django` core commands are also available. Check `python manage.py --help` and [the official Django documentation](https://docs.djangoproject.com/en/2.2/)
+The `djangoldp` server is built ontop of `django` framework. The `django` core commands are also available. Check `python manage.py --help` and `the official Django documentation <https://docs.djangoproject.com/en/2.2/>`__.
The Initserver command
----------------------
@@ -117,15 +118,15 @@ The DjangoLDP packages capabilities
Among other things, the package has a special file allowing a package to load settings when the djangoldp server starts. The `djangoldp_settings.py` file can reference custom variables and load extra middlewares (they are added to the ones loaded by the djangoldp server itself).
-```
-# cat mypkg/mypkg/djangoldp_settings.py
-MIDDLEWARE = []
-MYPACKAGE_VAR = 'MY_DEFAULT_VAR'
-```
+.. code-block:: python
+
+ # cat mypkg/mypkg/djangoldp_settings.py
+ MIDDLEWARE = []
+ MYPACKAGE_VAR = 'MY_DEFAULT_VAR'
As any other packages, local packages needs to be referenced in the project `settings.yml`:
-```
-ldppackages:
- - mypkg
-```
+.. code-block:: yml
+
+ ldppackages:
+ - mypkg
diff --git a/source/import_documentation/faq.rst b/source/import_documentation/faq.rst
index 44b6987913822b013e97c345f8d903fedf69013b..6237d2875dd73151905c7405fb84373f9bd355a0 100644
--- a/source/import_documentation/faq.rst
+++ b/source/import_documentation/faq.rst
@@ -27,7 +27,7 @@ We're working to make some popularizations for differents audiences. In the mean
The whole project is under `MIT licence <https://git.startinblox.com/framework/sib-core/blob/master/LICENSE/>`__.
-* **Why the documentation is not in makdown?**
+* **Why the documentation is not in markdown?**
This documentation in is `Restructured Text <https://docutils.sourceforge.io/rst.html>`__. `Have a look to this article <https://www.ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/>`__ if you want to understand our choice.
diff --git a/source/import_documentation/install-djangoldp-server.rst b/source/import_documentation/install-djangoldp-server.rst
index 0c22d268f068fdd32310a876f954b3e3cad981d2..d7e0335f403e9475be1a3181eab6bb6b5b89911c 100644
--- a/source/import_documentation/install-djangoldp-server.rst
+++ b/source/import_documentation/install-djangoldp-server.rst
@@ -7,7 +7,7 @@ Our solution is based on `Django <https://www.djangoproject.com/>`__ and named `
Go to `Server Architecture <server-architecture.html>`_ to know more about it.
-And check the `References guide <djangoldp_references.html>`__ to know all the details.
+And check the `References guide <djangoldp-references.html>`__ to know all the details.
Requirements
============
diff --git a/source/import_documentation/introduction-framework-documentation.rst b/source/import_documentation/introduction-framework-documentation.rst
index 66cc1d70ae7611764983d3ecf265491165bc4821..2bda150a15bbec67f5a6e1a8c55957009574249d 100644
--- a/source/import_documentation/introduction-framework-documentation.rst
+++ b/source/import_documentation/introduction-framework-documentation.rst
@@ -4,6 +4,7 @@ Introduction of the framework documentation
In the following sections, the framework's components are detailed.
**Base components** belong to the core of the framework.
+
For each component, you will find:
* a minimal example of usage (and related examples),
* a list of mixins used by the component,
diff --git a/source/import_documentation/tutorial-podcast.rst b/source/import_documentation/tutorial-podcast.rst
new file mode 100644
index 0000000000000000000000000000000000000000..b3bd9bab07fe29d662b1012db6defed873c2a3ea
--- /dev/null
+++ b/source/import_documentation/tutorial-podcast.rst
@@ -0,0 +1,347 @@
+Startin'blox Podcast Tutorial
+#############################
+
+Presentation and Objectives
+===========================
+
+Startin'blox provides SOLID components called "blox" to build-up a website or a webapp that can consume and
+manage data from various SOLID-compatible sources. This tutorial shows the various front-end blox available
+in the framework and describe step-by-step how to use it to make a podcast reader and sharing application.
+This application is build as a blox itself and can be embeded in a website by just dropping a
+``<solid-podcast>`` tag in the page.
+
+Here is the simple mockup that shows what the component will look like :
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Mockup-Podcast-Tutorial.png
+ :alt: Mockup Podcast
+
+In this tutorial, we will use some `Radio France podcasts <https://www.franceinter.fr/podcasts-originaux>`__.
+Feel free to use your own if you like.
+
+
+Teaching Objectives
+-------------------
+
+* Learn what a data source is
+* Use ``solid-display`` blox and understand the basic concepts about the consumed data
+* Organise the listed items and use widgets to customize the display (fields, field sets, img, ...)
+* Apply css to have your own look-and-feel
+* Create custom widgets
+* Plug js to have your own behavior
+
+
+Semantic data source
+====================
+
+Before begining our journey, we need a semantic data source formatted in a way that the framework can
+understand. The only supported format today in Startin'blox JSON Linked Data (`JSON-LD <https://json-ld.org/>`__).
+
+But a vast majority of podcast feeds are provided in RSS format. So let's use a simple conversion tool
+that will take a podcast RSS feed and format it to JSON-LD. You can find this little helper called
+``rss2jsonld`` on `this git repository <https://git.startinblox.com/fabien4vo/rss2jsonld/>`__ or use directly the
+bundled source from https://cdn.startinblox.com/tuto/rss2jsonld.js.
+
+
+Setup the environment and display data
+======================================
+
+To use the Startin'blox framework, just embed it in the head of your html :
+
+.. code-block:: html
+
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <meta charset="utf-8"/>
+ <title>SiB tutorial - Podcast</title>
+ <script type="module" src="https://cdn.skypack.dev/@startinblox/core@0.15"></script>
+ <script src="https://cdn.startinblox.com/tuto/rss2jsonld.js"></script>
+ </head>
+ <body>
+ </body>
+ </html>
+
+``core`` is the "heart" of the framework, and contains all the needed parts to get started. The current version
+of the core is ``0.15.6`` at the time of writing. The third number will increase with each published improvement
+and bugfix. Using ``@0.15`` at the end of the url will make it point to the latest bugfix available. The second
+number ``15`` will increase when new feature or breaking change are introduced. If you remove the @15 from the
+url, your application will get the next release as soon as it is published, but you probably have to change some
+part of it to make it work with this new version. So specifying the version is safer.
+
+The ``rss2jsonld`` script is here to automatically convert RSS data source to JSON-LD format.
+
+We can now use our first blox : ``<solid-display>``. Startin'blox use the `HTML Custom Element specification <https://html.spec.whatwg.org/multipage/custom-elements.html#custom-elements>`__
+which is part of the webcomponents standard, to create those blox. So you can use it as any other HTML tag,
+like ``<video>`` or ``<select>``. This blox simply displays the data provided by the linked data source :
+
+.. code-block:: html
+
+ <solid-display data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml" no-render/>
+
+I use the ``no-render`` attribute so that the RSS XML feed is not loaded by startin'blox until it was converted
+by ``rss2jsonld``.
+
+The result is not very pretty : all fields are displayed in plain text without formatting :
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render1-Podcast-Tutorial.png
+ :alt: Data displayed without formatting
+
+
+Organize and format data
+========================
+
+To put data in order, we use the ``fields`` tag :
+
+.. code-block:: html
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ no-render
+ fields="title, description"
+ />
+
+``fields`` take an ordered list of field names (found in the data source) and make the component to display only those fields in the provided order.
+
+We can also use a **widget** to specify how each field must be shown :
+
+.. code-block:: html
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ fields="title, description"
+ widget-title="h1"
+ no-render
+ />
+
+``widget-[field]`` take a HTML tag name and make the component use it to display this field.
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render2-Podcast-Tutorial.png
+ :alt: Data displayed with H1
+
+It starts to look better !
+
+Any HTML element can be used as widget, but Startin'blox also provide **built-in widgets** to easily manage specific
+cases. To display images from their url, use the ``solid-display-img`` widget :
+
+.. code-block:: html
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ fields="title, image.url, description"
+ widget-title="h1"
+ widget-image.url="solid-display-img"
+ no-render
+ />
+
+Fields can also be grouped in **sets** using brackets : each bracket opens or closes a group, and groups can be
+nested. The word before the opening bracket is the group name and can be used to have a specific widget to display this group.
+
+.. code-block:: html
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ fields="title, image.url, meta(itunes:author, itunes:category.text), description"
+ widget-title="h1"
+ widget-image.url="solid-display-img"
+ widget-meta="p"
+ no-render
+ />
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render3-Podcast-Tutorial.png
+ :alt: Data displayed with image
+
+
+Apply CSS to have your own look-and-feel
+========================================
+
+``solid-display`` uses standard HTML to display the data, and that HTML can be styled with CSS.
+
+.. code-block:: html
+
+ <style>
+ solid-display {
+ max-width: 800px;
+ display: block;
+ margin: auto;
+ }
+ solid-display img {
+ width: 200px;
+ float: left;
+ margin-right: 20px;
+ }
+ </style>
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render4-Podcast-Tutorial.png
+ :alt: Data displayed, CSS added
+
+
+You can also target specific field with an attribute selector because ``<solid-display>`` component adds a
+``name="[field]"`` attribute to the displayed data.
+
+.. code-block:: html
+
+ [name="itunes:category.text"]{
+ display: inline-block;
+ border: solid thin;
+ padding: 0.2em 0.5em;
+ margin: 0 1em;
+ border-radius: 0.5em;
+ }
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render5-Podcast-Tutorial.png
+ :alt: Data displayed, CSS added next
+
+
+But sometimes it's easier and cleaner to use classes. ``class-[field]`` tags let's you specify a class name.
+
+.. code-block:: html
+
+ <style>
+ .bordered {
+ display: inline-block;
+ border: solid thin;
+ padding: 0.2em 0.5em;
+ margin: 0 1em;
+ border-radius: 0.5em;
+ }
+ </style>
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ fields="title, image.url, meta(itunes:author, itunes:category.text), description"
+ widget-title="h1"
+ widget-image.url="solid-display-img"
+ widget-meta="p"
+ class-itunes:category.text="bordered"
+ no-render
+ />
+
+You can also use arbitrary text (enclosed by single quotes) in the fields list to display a text node :
+
+.. code-block:: html
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ fields="title, image.url, meta('By: ', itunes:author, itunes:category.text), description"
+ [...]
+ />
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render6-Podcast-Tutorial.png
+ :alt: Data displayed, CSS and text enclosed by sigle quotes
+
+
+Display nested list fields
+==========================
+
+Let's now display the informations about podcast episodes. They are listed in the ``item`` field, and as soon as it's
+a list we have to tell the framework that it should be treated as multiple values.
+
+This is achieved with the ``multiple-[field]`` attributes. This tag creates a nested ``<solid-display>`` for each entry in
+``item``. ``multiple-[field]-fields`` attribute is used to control which nested fields are displayed for each item.
+
+.. code-block:: html
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ fields="title, header(image.url, info( meta('By: ', itunes:author, itunes:category.text), description)), item"
+ widget-title="h1"
+ widget-image.url="solid-display-img"
+ widget-meta="p"
+ class-itunes:category.text="bordered"
+ widget-header="header"
+ multiple-item
+ multiple-item-fields="title"
+ no-render
+ />
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render7-Podcast-Tutorial.png
+ :alt: Add item in data displayed
+
+
+Custom template
+===============
+
+To go further, we need to create our own widget template using the ``solid-widget`` tag. Let's show other episode data:
+
+.. code-block:: html
+
+ <solid-widget name="podcast-episode">
+ <template>
+ <solid-display
+ data-src="${value}"
+ fields="title, meta(pubDate, itunes:duration), description"
+ widget-title="h2"
+ widget-description="p"
+ />
+ </template>
+ </solid-widget>
+
+ <solid-display
+ data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
+ [...]
+ multiple-item="podcast-episode"
+ no render
+ />
+
+``solid-widget`` tag must be used with ``template`` to avoid its content to be rendered during the first page display.
+The code included in the template is then used by Startin'blox to render each item. And you can use here again all the
+attributes we juste learned, such as ``fields`` and ``widget-[field]``.
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render8-Podcast-Tutorial.png
+ :alt: Add custom template for item
+
+
+Plug a bit of Javascript
+========================
+
+When a custom widget template is used, it gets a javascript variable called ``value`` that contains the resource. It can be
+displayed directly in the template using ``${value}`` or you can apply some Javascript to it before. For example, here is how
+to format the date using the browser locale settings :
+
+.. code-block:: html
+
+ <solid-widget name="format-date">
+ <template>
+ <time datetime="${value}">${new Date(value).toLocaleDateString(undefined, {weekday: 'long', year: 'numeric', month: 'long', day: 'numeric'})}</time>
+ </template>
+ </solid-widget>
+
+Now if I use ``widget-pubDate="format-date"`` in ``<solid-widget name="podcast-episode">``, I get a nice formatted date :
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render9-Podcast-Tutorial.png
+ :alt: Plug JS in a solid-widget
+
+And this template mechanism plays also nicely with other HTML5 standard tags, such as ``audio`` :
+
+.. code-block:: html
+
+ <solid-widget name="audio-player">
+ <template>
+ <audio src="${value}" controls/>
+ </template>
+ </solid-widget>
+
+ <solid-widget name="podcast-episode">
+ <template>
+ <solid-display
+ data-src="${value}"
+ fields="title, meta('Épisode du ', pubDate, ' - ', itunes:duration), description, enclosure.url"
+ widget-title="h2"
+ widget-description="p"
+ widget-pubDate="format-date"
+ widget-enclosure.url="audio-player"
+ />
+ </template>
+ </solid-widget>
+
+.. figure:: ../../_static/images/import_documentation/podcast_tutorial/Render10-Podcast-Tutorial.png
+ :alt: Add audio player solid-widget
+
+
+Conclusion
+==========
+
+This short tutorial has showed how to display the data from a podcast RSS feed using startin'blox framework. You can now
+check this is working with other podcasts (provided that CORS headers are set on the server).
+
+You can find the code on `this repository <https://git.startinblox.com/fabien4vo/solid-podcast>`__.
\ No newline at end of file
diff --git a/source/index.rst b/source/index.rst
index 153bce23dfde11d47595afa12f378ef88bc38eda..73bb06d71d61b46fcc7579f7cb9ab005ac1d9dc5 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -26,6 +26,7 @@ Welcome to Startinblox's documentation
:caption: Get started with sib-core
import_documentation/introduction-framework-documentation
+ import_documentation/tutorial-podcast
import_documentation/attributes-list
.. toctree::