Commit 4f79db97 authored by Manon Bourgognon's avatar Manon Bourgognon
Browse files

update doc after review

parent 1f66d0e3
.. _about-our-components:
About our components
######################
####################
**When you should create a component**
......
......@@ -96,7 +96,7 @@ Some packages may require some configuration to work properly. It is a good prac
Here you have :
* `a list of all the package available <https://git.startinblox.com/djangoldp-packages/>`__
* `Explanation on how to make one <develop-sib-ldp-packages.html>`__
* `Explanation on how to make one <https://docs.startinblox.com/import_documentation/develop-sib-ldp-packages.html>`__
If the description of the available packages is unclear, open an issue to ask for more description.
......
.. _djangoldp-guide-intro:
Get started with the DjangoLDP server
#####################################
......
......@@ -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
......
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 that inspires us.
......@@ -18,7 +18,9 @@ It is a set of standards on which we agree internationally to enable our applica
.. 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,7 +95,7 @@ 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.
......
......@@ -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
.. _podcast-tutorial:
Getting Started : Startin'blox Podcast Tutorial
***********************************************
......@@ -5,7 +7,7 @@ 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 (to learn more `about Startin’blox components <about-our-components>`__). 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,7 +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
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
......@@ -136,7 +138,7 @@ cases. To display images from their url, use the ``solid-display-img`` widget :
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
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
......@@ -156,7 +158,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 +180,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:: html
[name="itunes:category.text"]{
display: inline-block;
......@@ -194,7 +196,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
.. code:: html
<style>
.bordered {
......@@ -218,7 +220,7 @@ But sometimes it's easier and cleaner to use classes. ``class-[field]`` tags let
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"
......@@ -239,7 +241,7 @@ 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
.. code:: html
<solid-display
data-src="http://radiofrance-podcast.net/podcast09/rss_20856.xml"
......@@ -263,7 +265,7 @@ 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
.. code:: html
<solid-widget name="podcast-episode">
<template>
......@@ -298,7 +300,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,7 +315,7 @@ 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
.. code:: html
<solid-widget name="audio-player">
<template>
......@@ -347,4 +349,4 @@ check this is working with other podcasts (provided that CORS headers are set on
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 `Framework guide <framework-guide-intro>`__.
To learn more about the Startin'blox components and features, they are detailed in the :ref:`Framework guide <framework-guide-intro>`.
......@@ -39,7 +39,7 @@ 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 `Framework guide <framework-guide-intro>`__.
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.
......@@ -58,7 +58,7 @@ Each component treats a specific shape of data. The validation of this shape is
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.
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.
......@@ -79,19 +79,17 @@ The solution can be summarized as follows:
Overview of the Framework
~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
The section should be improve
Here is a brief presentation:
.. 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 ?
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment