Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • documentation/doc
  • PhilH/doc
  • louis.csn/doc
  • fabien4vo/doc
  • rngadam/doc
  • anastasia/doc
6 results
Show changes
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 908 additions and 967 deletions
source/import_documentation/server-architecture.rst → source/import_documentation/djangoldp_guide/server-architecture.rst
View file @ 405339e9
......@@ -2,7 +2,7 @@ Server Architecture
###################
DjangoLDP server
===============
================
Before deploying any SIB applications you will need SIB servers able to provide all capabilities your application relies on.
......@@ -18,7 +18,7 @@ DjangoLDP come with packages developed and maintained by the Startin'Blox team.
LDP packages
===========
============
Once you have your server DjangoLDP installed, you can plug to it DLP packages which are extention to treat a specific shape of data.
Each component has its own datas shapes. The server that will manage datas of a specific component has to get the specfic package related.
......@@ -33,7 +33,7 @@ You'll find the right package in the documentation of each component.
A request in detail
===================
.. figure:: ../_static/images/servers-of-the-future.png
.. figure:: ../../_static/images/servers-of-the-future.png
:alt: How we imagine the servers of the future
......
source/import_documentation/Solid-introduction.rst → source/import_documentation/first_step/Solid-introduction.rst
View file @ 405339e9
Our SOLID introduction
======================
`SOLID <https://solid.mit.edu/>`__, for SOcial LInked Data, is a project started in 2015 and led
in the 3WC by `Tim Berners Lee <https://fr.wikipedia.org/wiki/Tim_Berners-Lee>`__, the inventor of
in the W3C by `Tim Berners Lee <https://en.wikipedia.org/wiki/Tim_Berners-Lee>`__, the inventor of
the web who aims to rethink the way we build application in order to give back the power back to the final user.
For us SOLID project is above all a philosophy, a goal to reach and which inspires us.
For us SOLID project is above all a philosophy, a goal to reach and that inspires us.
Solid is built on top of existing Web standards. The core Solid specification relies on LDP and WAC (WAC draft, both being based on HTTP and RDF vocabularies. Solid also uses a subset of SPARQL UPDATE through HTTP PATCH queries. Identification in Solid is based on WebID-TLS and/or OIDC.
To know more on how does Solid relate to other Web standards, how a look to this `SOLID Faq <https://solidproject.org/faqs#how-does-solid-relate-to-other-web-standards>`__.
To know more on how does Solid relate to other Web standards, have a look to this `SOLID Faq <https://solidproject.org/faqs#how-does-solid-relate-to-other-web-standards>`__.
Let's have an overview on how we implement `SOLID specifications <https://github.com/solid/solid-spec>`__.
What is SOLID ?
---------------
It is a set of standards on which we agree internationally to communicate our applications between them. It is about the standardization of APIs.
It is a set of standards on which we agree internationally to enable our applications to communicate with each other. It is about the standardization of APIs.
.. warning::
This page should be improved. `Any feedbacks is welcome <https://mailto:alice@startinblox.com>`__
This page should be improved. `Any feedback is welcome`__.
.. _Any feedback is welcome: alice@startinblox.com
Our API
-------
......@@ -93,17 +95,17 @@ Did you notice the presence of a context ?
]
}
It is a way to go from the Json to `JsonLD <https://fr.wikipedia.org/wiki/JSON-LD>`__
It is a way to go from the Json to `JsonLD <https://fr.wikipedia.org/wiki/JSON-LD>`__.
That’s mean that we encode `Linked
Data <https://en.wikipedia.org/wiki/Linked_data>`__ using Json.
Data <https://en.wikipedia.org/wiki/Linked_data>`__ using JSON.
JsonLD is an `RDF <https://en.wikipedia.org/wiki/RDF>`__ implementation,
which is its-selft the basic language of `semantic
which is itself the basic language of `semantic
web <https://en.wikipedia.org/wiki/Semantic_Web>`__.
.. warning::
We use for our API JsonLD but you can imagine use other implementation like Turtle or XML.
We use for our API JsonLD but you can imagine using other implementations like Turtle or XML.
This context allows you to link object properties in a JSON document to
concepts in an `ontology <https://en.wikipedia.org/wiki/Web_Ontology_Language>`__.
......@@ -139,7 +141,7 @@ Here is the context referred :
}
The type we use is ``foaf``. That means that we use the FOAF ontology
which is done to describe people.
which is designed to describe people.
If you go to the `foaf ontology <http://xmlns.com/foaf/0.1/>`__, you’ll
see that the properties which we can use are :
......@@ -157,7 +159,7 @@ status \| surname \| theme \| thumbnail \| tipjar \| title \| topic \|
topic_interest \| weblog \| workInfoHomepage \| workplaceHomepage \|
yahooChatID \|
Now we can describe a user for every machines in the world using a
Now we can describe a user for every machine in the world using a
universal language :)
Why JsonLD is awesome ?
......@@ -182,7 +184,7 @@ JsonLD allow us to us Linked Datas in a very intuitive way.
Let's speak about containers
----------------------------
So how JsonLD manage to tiny the datas ?
So how JsonLD manage to simplify the datas ?
Let’s have a look on this part :
......
source/import_documentation/faq.rst → source/import_documentation/first_step/faq.rst
View file @ 405339e9
......@@ -20,7 +20,7 @@ If you want to add/change something on this documentation, `here are the instruc
* **What is Solid?**
We're working to make some popularizations for differents audiences. In the meanwhile, `have a look on the official presentation <solid.mit.edu//>`__.
We're working to make some popularizations for differents audiences. In the meanwhile, `have a look on the official presentation <https://solid.mit.edu//>`__.
* **This is open source?**
......@@ -29,11 +29,11 @@ The whole project is under `MIT licence <https://git.startinblox.com/framework/s
* **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.
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.
* **You cannot find the question you have?**
`Send your question <https://mailto:alice@startinblox.com>`__ to the the maintainer of the doc or
`Send your question`__ to the maintainer of the doc or
`open an issue on the doc <https://git.startinblox.com/documentation/doc/-/boards/>`__.
.. _Send your question: alice@startinblox.com
\ No newline at end of file
source/import_documentation/tutorial-podcast.rst → source/import_documentation/first_step/get-started.rst
View file @ 405339e9
Startin'blox Podcast Tutorial
#############################
.. _podcast-tutorial:
Getting Started : 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
manage data from various SOLID-compatible sources (to learn more :ref:`about Startin’blox components <about-our-components>`). 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.
......@@ -47,7 +49,7 @@ Setup the environment and display data
To use the Startin'blox framework, just embed it in the head of your html :
.. code-block:: html
.. code:: html
<!DOCTYPE html>
<html>
......@@ -74,7 +76,7 @@ We can now use our first blox : ``<solid-display>``. Startin'blox use the `HTML
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
.. code:: html
<solid-display data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml" no-render/>
......@@ -92,7 +94,7 @@ Organize and format data
To put data in order, we use the ``fields`` tag :
.. code-block:: html
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
......@@ -104,7 +106,7 @@ To put data in order, we use the ``fields`` tag :
We can also use a **widget** to specify how each field must be shown :
.. code-block:: html
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
......@@ -123,6 +125,7 @@ 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
......@@ -138,14 +141,15 @@ nested. The word before the opening bracket is the group name and can be used to
.. 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
/>
<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
......@@ -156,7 +160,7 @@ 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
.. code:: html
<style>
solid-display {
......@@ -178,7 +182,7 @@ Apply CSS to have your own look-and-feel
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
.. code:: css
[name="itunes:category.text"]{
display: inline-block;
......@@ -194,6 +198,7 @@ You can also target specific field with an attribute selector because ``<solid-d
But sometimes it's easier and cleaner to use classes. ``class-[field]`` tags let's you specify a class name.
.. code-block:: html
<style>
......@@ -216,15 +221,17 @@ But sometimes it's easier and cleaner to use classes. ``class-[field]`` tags let
no-render
/>
You can also use arbitrary text (enclosed by single quotes) in the fields list to display a text node :
.. code-block:: html
.. code:: 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"
[...]
/>
<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
......@@ -239,20 +246,22 @@ a list we have to tell the framework that it should be treated as multiple value
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
/>
<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
......@@ -265,23 +274,24 @@ To go further, we need to create our own widget template using the ``solid-widge
.. 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-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-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
......@@ -298,7 +308,7 @@ When a custom widget template is used, it gets a javascript variable called ``va
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
.. code:: html
<solid-widget name="format-date">
<template>
......@@ -313,26 +323,28 @@ Now if I use ``widget-pubDate="format-date"`` in ``<solid-widget name="podcast-e
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>
.. code:: 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>
<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
......@@ -344,4 +356,7 @@ 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
You can find the code on `this repository <https://git.startinblox.com/fabien4vo/solid-podcast>`__.
To learn more about the Startin'blox components and features, they are detailed in the :ref:`Framework guide <framework-guide-intro>`.
source/import_documentation/what-is-sib.rst → source/import_documentation/first_step/sib-presentation.rst
View file @ 405339e9
What is Startin'blox?
***********************
.. _sib-presentation:
Startin'blox presentation
*************************
What is Startin'blox ?
======================
Synopsis
========
--------
Startin'blox is a set of tools based on `Web Components <https://www.webcomponents.org/>`__ and `Linked Data conventions <https://www.w3.org/standards/semanticweb/data>`__ to create applications compatibles with the `SOLID specifications <https://github.com/solid/solid-spec/>`__.
Those tools are developed by the cooperative of the same name.
We are all, as users, captive to the digital platforms we use, attached to them by the network effect over which they have a monopoly.
Thanks to W3C and `the work of Tim Berners-Lee <https://solid.mit.edu/>`__, an alternative is possible. The new web standards allow the network effect to be shared between the different digital tools and give us back total control over our personal data.
Thanks to W3C and `the work of Tim Berners-Lee <https://solid.mit.edu/>`__, an alternative is possible.
The new web standards allow the network effect to be shared between the different digital tools and give us back total control over our personal data.
**Startin'blox has set itself the mission of precipitating the advent of this new type of digital platform.**
We've built a solution to make the creation of federated and interoperable applications as accessible as possible.
.. figure:: ../_static/images/import_documentation/federation.png
.. figure:: ../../_static/images/import_documentation/federation.png
:alt: Federation concept
=> To know more about Startin'blox, have a look to `our website <https://startinblox.com/>`__.
Explanation
===========
-----------
Global overview
---------------
~~~~~~~~~~~~~~~
Startin'blox is composed of:
A front framework
..................
**Startin'blox mainly develops a solution for creating web applications based on front-end development.**
It can be imported by a simple script in a html file and provides you basics functionalities like making a form, displaying data, a map, a calendar etc..
To learn more about the framework components and features, they are detailed in the :ref:`Framework guide <framework-guide-intro>`.
In the Startin'blox philosophy, the logic of the data processing is done on the front side.
In the Startin'blox philosophy, the logic of the data processing is done on the front side.
Extended features components
............................
Components are web components that correspond to functionalities that you can easily add to existing applications. Startin'blox creates components according to its uses but in the future we encourage the development of community components.
Components are web components that correspond to functionalities that you can easily add to existing applications.
Startin'blox creates components according to its uses but in the future we encourage the development of community components.
For example, Sib-Directory provides you with a user directory that includes user skills.
.. figure:: ../_static/images/import_documentation/Components.png
.. figure:: ../../_static/images/import_documentation/Components.png
:alt: Component example
Each component treats a specific shape of data. The validation of this shape is made on the server side.
A server solution
.................
We offer a server solution based on the `Django framework <https://www.djangoproject.com/>`__ and adapted to be compatible with the Linked datas platform conventions, named DjangoLDP.
We offer a server solution based on the `Django framework <https://www.djangoproject.com/>`__ and adapted to be compatible with
the Linked datas platform conventions, named :ref:`DjangoLDP <djangoldp-guide-intro>`.
It is a simple architecture on which we can add LDP packages, corresponding to the different components used. Those are the ones that will do the work of validating the application data.
It is a simple architecture on which we can add LDP packages, corresponding to the different components used.
Those are the ones that will do the work of validating the application data.
.. figure:: ../_static/images/import_documentation/Overview-server.png
.. figure:: ../../_static/images/import_documentation/Overview-server.png
:alt: Server overview
.. note::
......@@ -60,20 +72,77 @@ It is a simple architecture on which we can add LDP packages, corresponding to t
The solution can be summarized as follows:
.. figure:: ../_static/images/import_documentation/Overview-of-SiB.png
.. figure:: ../../_static/images/import_documentation/Overview-of-SiB.png
:alt: SiB overview
Overview of the Framework
--------------------------
.. warning::
The section should be improve
Overview of the Framework
~~~~~~~~~~~~~~~~~~~~~~~~~
Here is a brief presentation:
.. figure:: ../_static/images/import_documentation/Framework-Overview.png
.. figure:: ../../_static/images/import_documentation/Framework-Overview.png
:alt: Framework Overview
`To go deeper <https://git.happy-dev.fr/startinblox/framework/sib-core/>`__.
The framework is composed of **base components** that allow data to be displayed, modified, searched ... These functionalities are defined by attributes, specific to the components themselves or proposed by the framework **mixins**.
Finally, the **store** is responsible for managing the data.
To go deeper in the framework discovery and understanding, go to consult :ref:`framework guide introduction <framework-guide-intro>`, or take a look at `source code <https://git.startinblox.com/framework/sib-core>`__.
Follow the :ref:`Startin'blox podcast tutorial <podcast-tutorial>` offers a step-by-step introduction to the framework.
Why use Startin'blox ?
======================
Fast and Easy
-------------
Startin’blox technology is aimed at enabling **anyone with little
development skills** to create their own web application easily and
quicky respecting both the `web components
standards <https://developer.mozilla.org/fr/docs/Web/Web_Components>`__
and the `Linked Data Platform
convention <https://en.wikipedia.org/wiki/Linked_Data_Platform>`__.
Moreover, it allows today to connect communities and make federated applcation.
Effortlessly, you can compose your app with ready-made HTML components, each of which provides an entire feature.
Add HTML tags with the right attributes and watch your application build itself.
Decentralized
-------------
Today’s applications have their own database. A back depends on a front
and screw and vice versa. In a decentralized web, there are data sources
and client applications that use these datas.
This is made possible by the fact that **the data
is** `interoperable <https://en.wikipedia.org/wiki/Interoperability>`__
because it is written in `RDF <https://www.w3.org/RDF/>`__, the basic
language of the `semantic
web <https://en.wikipedia.org/wiki/Semantic_Web>`__.
Starin’blox is a front-end framework composed of `web
components <https://en.wikipedia.org/wiki/Web_Components>`__ that can
receive federated data sources in RDF. This means that you can only use
a component using data sources already available on the web.
.. figure:: ../../_static/images/import_documentation/federation.png
:alt: Federation
Startin’Blox is designed to interconnect applications and their users. Our components can plug into an unlimited number of data sources, so your application connects you to the ecosystem of your choice.
Our work is based on an international project: `The Solid
Project <https://solid.mit.edu/>`__.
Natively modular
----------------
Startin'blox was designed to be modular. It uses the latest standards of linked data and web components. Most modern browsers support them without even a polyfill. You can integrate only one component to an existing application or build an entire application in SiB.
.. note::
We should add more draw and uses cases. It's the theory page.
\ No newline at end of file
source/import_documentation/attributes-list.rst → source/import_documentation/framework_guide/attributes-list.rst
View file @ 405339e9
List of attributes (core framework)
===================================
Below are listed all the attributes of the core framework.
They allow to add, to specify functionalities for base components.
Attributes are specific to base components or they depend on mixins (they can be used by several components).
``action-[field]``
~~~~~~~~~~~~~~~~~~
* :ref:`widget-mixin <action-field>`
``addable-[field]``
~~~~~~~~~~~~~~~~~~
* :ref:`widget API reference <reference>`
``alt-[field]``
~~~~~~~~~~~~~~~
* :ref:`widget-mixin <alt-field>`
......@@ -71,9 +79,14 @@ List of attributes (core framework)
~~~~~~~~~~~~~~~~~~~~
* :ref:`counter-mixin <counter-mixin>`
``data-holder``
~~~~~~~~~~~~~~~
* :ref:`solid-widget <solid-widget>`
``data-src``
~~~~~~~~~~~~
* :ref:`store-mixin <data-src>`
* :ref:`solid-widget <solid-widget>`
``data-label``
~~~~~~~~~~~~~~
......@@ -164,6 +177,10 @@ List of attributes (core framework)
~~~~~~~~
* :ref:`solid-lang <solid-lang>`
``limit``
~~~~~~~~~~~~~~~
* :ref:`server-pagination-mixin <server-pagination-mixin>`
``loader-id``
~~~~~~~~~~~~~
* :ref:`store-mixin <loader-id>`
......@@ -212,6 +229,10 @@ List of attributes (core framework)
~~~~~~~~~~~~~
* :ref:`store-mixin <no-render>`
``offset``
~~~~~~~~~~~~~~~
* :ref:`server-pagination-mixin <server-pagination-mixin>`
``order-asc``
~~~~~~~~~~~~~
* :ref:`sorter-mixin <sorter-mixin>`
......
source/import_documentation/framework_guide/how-to-use-SIB.rst 0 → 100644
View file @ 405339e9
.. _framework-guide-frequent-questions:
Examples of Startin'blox use cases
==================================
This page contains frequently asked questions about the use of the framework,
with a link to the appropriate page or the presentation of an example with the html code and the rendering.
How to display data
-------------------
The :ref:`podcast tutorial <podcast-tutorial>` illustrates with details how to display data.
To present it really simply, a ``solid-display`` component with a ``data-src`` attribute whose value is jsonld file with dataset to work on (the ``fields`` attribute precise the fields to display):
.. code-block:: html
<solid-display
data-src="data/documentation/users.jsonld"
fields="first_name, last_name"
></solid-display>
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name"
></solid-display>
The first solid-display displays data for a **container** (several resources), the second from a **resource**.
.. figure:: ../../_static/images/import_documentation/framework-basic-use/display-data.png
:alt: 2 examples of solid-display use
Here is the jsonld data structure used for the example (container and resource):
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-container.png
:alt: Example of jsonld data container
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-resource.png
:alt: Example of jsonld data resource
How to display nested data
--------------------------
Nested data is a data linked to another but not stored in the same place.
They are related by a "call" from the first data to the stored place of the second one.
Startin'blox proposes 2 ways to display it:
* **period** syntax
* ``nested-field`` attribute
.. code-block:: html
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="profile.address, profile.birthdate"
widget-profile.address="solid-display-div-multiline"
widget-profile.birthdate="solid-display-div-date"
></solid-display>
<solid-display
data-src="data/documentation/user-1.jsonld"
nested-field="profile"
fields="address, birthdate"
widget-address="solid-display-div-multiline"
widget-birthdate="solid-display-div-date"
></solid-display>
The widgets are used to specify how data is displayed. Their use is detailed in :ref:`widgets API <reference>` and :ref:`examples <widgets-examples>` of use are presented.
.. figure:: ../../_static/images/import_documentation/framework-basic-use/nested-data.png
:alt: nested-data
How to add and edit data
------------------------
To create a form, indicate in ``data-src`` attribute the data model to which it corresponds. If the data model is a **resource**, the form will be used to edit data. If it's a **container**, the form will create a new resource.
The solid-form component is automatically linked to the data, it takes care of adding or editing them.
Then, add attributes and widgets to change label values, precise inputs type, etc.
.. code-block:: html
<solid-form
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name, email"
label-first_name="First name:"
label-last_name="Last name:"
label-email="Email:"
></solid-form>
<solid-form
data-src="data/documentation/concerts.jsonld"
fields="date, artist, start_time, end_time, scene, gauge"
label-date="Date:"
label-artist="Artist:"
label-start_time="Start time:"
label-end_time="End time:"
label-scene="Scene:"
label-gauge="Gauge:"
widget-date="solid-form-date-label"
widget-start_time="solid-form-time-label"
widget-end_time="solid-form-time-label"
widget-gauge="solid-form-number-label"
></solid-form>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form.png
:alt: Example of solid-form use
How to add new values in a form
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The feature ``addable`` adds a solid-form to add a value to a field. Here, hobbies is concerned:
.. code-block:: html
<solid-form
data-src="data/documentation/users.jsonld"
fields="first_name, last_name, hobbies"
label-first_name="First name:"
label-last_name="Last name:"
label-hobbies="Hobbies:"
submit-button="Send form"
widget-hobbies="solid-form-dropdown-addable-label"
range-hobbies="data/documentation/hobbies.jsonld"
addable-hobbies-fields="name"
addable-hobbies-widget-name="solid-form-text-label"
addable-hobbies-label-name="Add a new hobby:"
addable-hobbies-submit-button="Add hobby"
></solid-form>
The red frame represents the widget tag ``solid-form-dropdown-addable-label``,
the blue frame represents the ``<solid-form>`` created by ``addable`` attribute:
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form-addable.png
:alt: Example of solid-form with addable feature
Specific case - how to add and edit nested data
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To modify or add data including data linked, adding a second solid-form is necessary, with ``data-holder`` and ``data-src=${value}`` attributes. It can be done thanks to a custom solid-widget. The second-form can also contain attributes:
.. code-block:: html
<solid-form
data-src="data/documentation/users.jsonld"
fields="first_name, last_name, email, profile"
label-first_name="First name:"
label-last_name="Last name:"
label-email="Email:"
widget-profile="profile-form"
></solid-form>
<solid-widget name="profile-form">
<template>
<b>Profile form</b>
<solid-form
data-holder
data-src="${value}"
naked
fields="birthdate, address, phone"
label-birthdate="Birthdate:"
label-address="Address:"
label-phone="Phone number:"
></solid-form>
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form-nested.png
:alt: Example of solid-form nested
For more informations, ``data-holder``, ``data-src="${value}"`` attributes are detailed in :ref:`solid-widget<solid-widget>`
and ``naked`` attribute in :ref:`solid-form<solid-form>`.
How to display data in a table
------------------------------
To display data in a table, instead of a ``solid-display``, use a ``solid-table``, specific attributes are detailed on its :ref:`presentation page <solid-table>`.
The ``order-asc`` attribute allows to sort data elements by date. It is presented on :ref:`sorter-mixin page <sorter-mixin>`.
.. code-block:: html
<solid-table
data-src="data/documentation/concerts.jsonld"
fields="artist, date, start_time, end_time, scene"
></solid-table>
<solid-table
data-src="data/documentation/concerts.jsonld"
fields="artist, date, start_time, end_time, scene"
widget-date="solid-display-div-date"
widget-start_time="solid-display-div-time"
widget-end="solid-display-div-time"
header
label-artist="Artist"
label-date="Date"
label-start_time="Start time"
label-end_time="End time"
label-scene="Scene"
order-asc="date"
></solid-table>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-table.png
:alt: 2 examples of solid-table use
Jsonld data structure used for the example:
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-solid-table.png
:alt: Example of jsonld data container
How to filter displayed data
----------------------------
From the example above, by adding ``filtered-by`` attribute reffering to a ``solid-form-search`` component, data displayed can be filtered:
.. code-block:: html
<solid-form-search
id="test"
fields="artist"
label-artist="Search by artist :"
></solid-form-search>
<solid-table
data-src="data/documentation/concerts.jsonld"
fields="artist, date, start_time, end_time, scene"
widget-date="solid-display-div-date"
widget-start_time="solid-display-div-time"
widget-end="solid-display-div-time"
header
label-artist="Artist"
label-date="Date"
label-start_time="Start time"
label-end_time="End time"
label-scene="Scene"
order-asc="date"
filtered-by="test"
></solid-table>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/solid-form-search.png
:alt: Solid-form-search example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/data-filtered.png
:alt: Data filtered example
How to display a list of nested data - ``multiple`` attribute use
-----------------------------------------------------------------
To display a list of data, they have to be in a container.
If the data to be listed are nested, add ``multiple-[field]`` attribute from :ref:`widget-mixin <widget-mixin>` to precise which field to display.
.. code-block:: html
<solid-display
data-src="data/documentation/user-5.jsonld"
fields="first_name, last_name, email, hobbies"
></solid-display>
<solid-display
data-src="data/documentation/user-5.jsonld"
fields="first_name, last_name, email, hobbies"
multiple-hobbies
multiple-hobbies-fields="name"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/nested-data-list.png
:alt: List of nested data in a container
.. figure:: ../../_static/images/import_documentation/framework-basic-use/jsonld-nested-data-list.png
:alt: Jsonld file used for nested data list
File hobby-1.jsonld content:
.. code-block:: json
{
"@id": "/examples/data/documentation/hobby-1.jsonld",
"name": "Comics",
"@context": "https://cdn.happy-dev.fr/owl/hdcontext.jsonld"
}
How to use default and empty attributes
---------------------------------------
* **default-widget** defines the widget used by default for all the fields if none is specified:
Here, default-widget is applied to ``email`` and ``last_name`` (``first_name`` has its own one).
.. code-block:: html
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name, email"
></solid-display>
<solid-display
data-src="data/documentation/user-1.jsonld"
fields="first_name, last_name, email"
widget-first_name="b"
default-widget="solid-display-link"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/default-widget.png
:alt: default-widget example
* **default-[field]** defines the ``value`` by default, **default-widget-[field]** defines a widget by default for an empty or undefined ``[field]``:
.. code-block:: html
<solid-display
data-src="data/documentation/profile-2.jsonld"
fields="birthdate, phone"
default-phone="No phone number"
></solid-display>
<solid-display
data-src="data/documentation/profile-2.jsonld"
fields="birthdate, phone"
default-widget-phone="default-widget-phone"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/default-(widget)-field.png
:alt: default-[field] and default-widget-[field] example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/default-field-data.png
:alt: data for default-[field] example
* **empty-widget** and **empty-value** allow to display a widget with a value if there is no data in a container :
.. code-block:: html
<solid-display
data-src="data/documentation/user-3-hobbies.jsonld"
fields="name"
empty-value="No hobby"
empty-widget="no-hobby"
></solid-display>
<solid-widget name="no-hobby">
<template>
<b>Empty container</b>
${value}
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-widget.png
:alt: empty-widget and empty-value example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-widget-data.png
:alt: data for empty-widget example
* **empty-[set]** and **empty-[set]-value** allow to display a widget with a value if all fields in a :ref:`set<widget-mixin>` are empty:
.. code-block:: html
<solid-display
data-src="data/documentation/profile-4.jsonld"
fields="fullname, contact(address, phone)"
empty-contact="empty-set"
empty-contact-value="No contact information"
></solid-display>
<solid-widget name="empty-set">
<template>
<b>Contact :</b>
<p>${value}</p>
</template>
</solid-widget>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-set.png
:alt: empty-[set] and empty-[set]-value example
.. figure:: ../../_static/images/import_documentation/framework-basic-use/empty-set-data.png
:alt: data for empty-[set] example
How to use special attributes, values
-------------------------------------
store://...
~~~~~~~~~~~
It allows to fetch from the :ref:`store <store-mixin>` and display any value from any data resource, for any concerned attribute.
*Here, without it, the field's name is displayed by default.*
.. code-block:: html
<solid-display
data-src="data/documentation/users.jsonld"
fields="full_name"
action-full_name="user-details"
></solid-display>
<solid-display
data-src="data/documentation/users.jsonld"
fields="full_name"
action-full_name="user-details"
link-text-full_name="store://resource.full_name"
></solid-display>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/store-use.png
:alt: Example of store://... value use
bind-resources
~~~~~~~~~~~~~~
It allows to keep and pass the resource data-src between views when a :ref:`solid-router <solid-router>` is used.
*Here, it ensures the personal informations of user clicked are displayed.*
.. code-block:: html
<solid-router use-hash>
<solid-route
hidden
use-id
name="user-details"
></solid-route>
</solid-router>
<solid-display
data-src="data/documentation/users.jsonld"
fields="full_name"
action-full_name="user-details"
link-text-full_name="store://resource.full_name"
></solid-display>
<div data-view="user-details" hidden>
<solid-display
bind-resources
fields="first_name, last_name, email, profile.birthdate, profile.address, profile.phone"
label-first_name="First name :"
label-last_name="Last name :"
label-email="Email :"
label-profile.birthdate="Birthdate :"
label-profile.address="Address :"
label-profile.phone="Phone number :"
default-widget="solid-display-value-label"
></solid-display>
</div>
.. figure:: ../../_static/images/import_documentation/framework-basic-use/bind-resources.png
:alt: Example of bind-resources use
source/import_documentation/introduction-framework-documentation.rst → source/import_documentation/framework_guide/how-to-use-the-documentation.rst
View file @ 405339e9
Introduction of the framework documentation
============================================
.. _framework-guide-intro:
How to use the documentation
============================
In the following sections, the framework's components are detailed.
......
source/import_documentation/framework_guide/javascript-API.rst 0 → 100644
View file @ 405339e9
Javascript API
**************
This section presents how you can use Javascript API with sib-core.
.. toctree::
:maxdepth: 1
/import_documentation/javascript_API/Events
/import_documentation/javascript_API/Helpers-functions
/import_documentation/javascript_API/Store-doc
\ No newline at end of file
source/import_documentation/framework_guide/list-base-components.rst 0 → 100644
View file @ 405339e9
Base components
***************
These components offer basic functionalities used in
an simple web application like display data, create data, search data, etc.
- ``Solid-Ac-Checker`` : to manage permissions
- ``Solid-Calendar`` : to display and manage data on a calendar
- ``Solid-Delete`` : to delete data
- ``Solid-Display`` : to display data
- ``Solid-Form`` : to create forms and modify data
- ``Solid-Form-Search`` : to search data
- ``Solid-Lang`` : to manage language
- ``Solid-Map`` : to display and manage data on a map
- ``Solid-Table`` : to manage data on a table
- ``Solid-Widget`` : to create custom elements (pattern) to display data
To find out how to use them :
.. toctree::
:maxdepth: 1
/import_documentation/Components/Solid-Ac-Checker
/import_documentation/Components/Solid-Calendar
/import_documentation/Components/Solid-Delete
/import_documentation/Components/Solid-Display
/import_documentation/Components/Solid-Form
/import_documentation/Components/Solid-Form-Search
/import_documentation/Components/Solid-Lang
/import_documentation/Components/Solid-Map
/import_documentation/Components/Solid-Table
/import_documentation/Components/Solid-Widget
source/import_documentation/framework_guide/list-external-components.rst 0 → 100644
View file @ 405339e9
External components
*******************
The external components are not required for an application to be functional,
however they can be used to add useful features :
- ``Solid-Auth`` : to manage user authentication
- ``Solid-Router`` : to create menu and navigate between pages
For more information on their use :
.. toctree::
:maxdepth: 1
/import_documentation/Components/Solid-Auth
/import_documentation/Components/Solid-Router
source/import_documentation/framework_guide/list-external-components2.rst 0 → 100644
View file @ 405339e9
External components
*******************
The external components are not required for an application to be functional,
however they can be used to add useful features :
- ``Solid-Auth`` : to manage user authentication
- ``Solid-Router`` : to create menu and navigate between pages
For more information on their use :
test 1
.. toctree::
:maxdepth: 1
/import_documentation/Components/Solid-Auth
/import_documentation/Components/Solid-Router
test 2
.. toctree::
:maxdepth: 1
Solid-Auth to manage user authentication </import_documentation/Components/Solid-Auth>
Solid-Router : to create menu and navigate between pages </import_documentation/Components/Solid-Router>
test 3
.. toctree::
:maxdepth: 1
**Solid-Auth** : to manage user authentication <sib-auth>
``Solid-Router`` : to create menu and navigate between pages <solid-router>
source/import_documentation/framework_guide/list-mixins.rst 0 → 100644
View file @ 405339e9
Mixins
******
Mixins are sets of features that can be used and added in
the base components to best render the content of the application :
.. toctree::
:maxdepth: 1
/import_documentation/Mixins/counter-mixin
/import_documentation/Mixins/federation-mixin
/import_documentation/Mixins/filter-mixin
/import_documentation/Mixins/grouper-mixin
/import_documentation/Mixins/highlighter-mixin
/import_documentation/Mixins/list-mixin
/import_documentation/Mixins/next-mixin
/import_documentation/Mixins/paginate-mixin
/import_documentation/Mixins/required-mixin
/import_documentation/Mixins/server-pagination-mixin
/import_documentation/Mixins/sorter-mixin
/import_documentation/Mixins/store-mixin
/import_documentation/Mixins/validation-mixin
/import_documentation/Mixins/widget-mixin
\ No newline at end of file
source/import_documentation/framework_guide/list-widgets.rst 0 → 100644
View file @ 405339e9
Widgets
*******
Widgets are little tools for specifying how to display data in components.
How to create them and how to use them are precised :
.. toctree::
:maxdepth: 1
/import_documentation/Widgets/Reference
/import_documentation/Widgets/Examples
\ No newline at end of file
source/import_documentation/frequent-errors.rst → source/import_documentation/frequent_errors/frequent-errors.rst
View file @ 405339e9
Frequent Errors
######################
###############
JSON problem
~~~~~~~~~~~~
......@@ -37,10 +37,11 @@ This is because the core is imported into each component and each of them could
Check the compatibility of the component you want to use with the version of the core you are working with. You should find this information in the documentation of the component. If it's not, you should mail the maintainer.
**Special note to maintainer**:
If you're coding a component, do not forget :
* to tell in its documentation with which version of the core it could be compatible
* to let your email in the doc
* to update your component when a new version is released
If you're coding a component, do not forget :
* to tell in its documentation with which version of the core it could be compatible
* to let your email in the doc
* to update your component when a new version is released
.. note::
......
source/import_documentation/get-started.rst deleted 100644 → 0
View file @ 2c2bf80a
This diff is collapsed.
source/import_documentation/Events.rst → source/import_documentation/javascript_API/Events.rst
View file @ 405339e9
.. _events:
Events
------
======
Our objective is to use the minimum of javascript.
......@@ -28,7 +30,7 @@ But for now, here are some events that will be useful to you.
+------+---------+------------------------+---------------------------+
Examples
~~~~~~~~
--------
``populate``
^^^^^^^^^^^^
......
source/import_documentation/Helpers-functions.rst → source/import_documentation/javascript_API/Helpers-functions.rst
View file @ 405339e9
.. _javascript-helpers:
Javascript Helpers
=====================
==================
Helpers fonctions
-----------------
......
source/import_documentation/Store-doc.rst → source/import_documentation/javascript_API/Store-doc.rst
View file @ 405339e9
.. _store-documentation:
Store documentation
====================
......@@ -142,4 +144,17 @@ The store is reactive. It means that any change you make on a resource in your a
However, there are some limitations:
* If you make some changes on a resource which is in a virtual container, other virtual containers including this resource may not be updated. (ie: POST on ``circles/1/members`` does not update ``users/admin/circles/``)
* If a resource a multi nested field is displayed in a component, it may not be updated. (ie: in a ``sib-display``, I display ``nestedResource.user.name`` from ``resource``, changing ``user`` will not update the display)
\ No newline at end of file
* If a resource having a multi nested field is displayed in a component, it may not be updated. (ie: in a ``sib-display``, I display ``nestedResource.user.name`` from ``resource``, changing ``user`` will not update the display)
In response to these two cases, the store method ``subscribeVirtualContainerTo(arg1, arg2)`` allows changes in one resource to be passed on to another reactively:
- ``arg1`` is the resource to be updated according to ``arg2``,
- ``arg2`` is the starting resource, the model to copy.
The following example illustrates the reactivity of a component displaying job offers.
A container is providing a list of job offers (``http://localhost/job-offers/active/``), another endpoint is used to create new job offers (``http://localhost/job-offers/``). Each time a job offer is created (added to ``http://localhost/job-offers/``), the displayed list of job offers (``http://localhost/job-offers/active/``) requires an update:
.. code:: javascript
core.store.subscribeVirtualContainerTo(http://localhost/job-offers/active/, http://localhost/job-offers/);
\ No newline at end of file
source/import_documentation/why-use-sib.rst deleted 100644 → 0
View file @ 2c2bf80a
This diff is collapsed.