Skip to content
Snippets Groups Projects
Commit 4eb007b8 authored by Matthieu Fesselier's avatar Matthieu Fesselier
Browse files

Merge branch 'update-documentation' into 'dev' 

update documentation, files reorganization

See merge request !73
parents fa2114dd eddef3a7
No related branches found
No related tags found
2 merge requests!76Dev to Master,!73update documentation, files reorganization
Hide whitespace changes
Inline Side-by-side
Showing
with 309 additions and 830 deletions
source/TEST-index.rst 0 → 100644
+ 48
− 0
View file @ 4eb007b8
Welcome to Startinblox's documentation
========================================
.. toctree::
:maxdepth: 2
:caption: First Step
import_documentation/first_step/sib-presentation
import_documentation/first_step/get-started
import_documentation/first_step/Solid-introduction
import_documentation/first_step/faq
.. toctree::
:maxdepth: 2
:caption: DjangoLDP Guide
import_documentation/djangoldp_guide/install-djangoldp-server
import_documentation/djangoldp_guide/djangoldp-references
import_documentation/djangoldp_guide/server-architecture
.. toctree::
:maxdepth: 2
:caption: Framework Guide
import_documentation/framework_guide/how-to-use-the-documentation
import_documentation/framework_guide/list-base-components
import_documentation/framework_guide/list-external-components
import_documentation/framework_guide/list-mixins
import_documentation/framework_guide/attributes-list
import_documentation/framework_guide/list-widgets
import_documentation/framework_guide/javascript-API
.. toctree::
:maxdepth: 2
:caption: About
import_documentation/about/About-our-components
import_documentation/about/About-semantic-web
import_documentation/about/About-activity-pub
import_documentation/about/About-authentification-sso
import_documentation/about/About-the-cooperative
.. toctree::
:maxdepth: 2
:caption: Frequent Errors
import_documentation/frequent_errors/frequent-errors
source/import_documentation/Use-a-component-alone-in-an-existing-application.rst
+ 2
− 1
View file @ 4eb007b8
Add a component to a website
***************************
****************************
Use Startin'blox according to your needs.
Startin'blox was designed to be modular. You need to add a calendar or a map to your website?
......@@ -21,6 +21,7 @@ In the documentation of the component you’ve chosen, you’ll find the
script to import.
.. code:: html
<!-- ... Import the core ... -->
<script type="module" src="https://unpkg.com/@startinblox/core"></script>
<!-- ... Import your component ... -->
......
source/import_documentation/Widgets/Reference.rst
+ 2
− 1
View file @ 4eb007b8
.. _reference:
Widgets API Reference
======================
=====================
Widgets are created at the moment you ask for it for the first time.
The name of the widget is analyzed to build a widget which uses the features and template you want.
......
source/import_documentation/install-djangoldp-server.rst → source/import_documentation/djangoldp_guide/install-djangoldp-server.rst
+ 8
− 1
View file @ 4eb007b8
......@@ -3,7 +3,14 @@ Get started with the DjangoLDP server
What is behind the DjangoLDP server ?
=====================================
Our solution is based on `Django <https://www.djangoproject.com/>`__ and named `DjangoLDP <https://git.startinblox.com/djangoldp-packages/djangoldp/>`__, adapted to be compatible with Linked Datas convention.
Startin'Blox is a front framework, based on a server named `DjangoLDP <https://git.startinblox.com/djangoldp-packages/djangoldp/>`__ and based on `Django <https://www.djangoproject.com/>`__.The DjangoLDP server is adapted to be compatible with Linked Datas convention.
As a reminder and as specified in :ref:`Startin'Blox presentation <sib-presentation>`, Startin'Blox is data source agnostic,
i.e. it adapts to data sources that are compatible with the Linked Data Platform conventions.
DjangoLDP server, used in production, is the most operational solution today. However, it is currently still
in development, so there is no guarantee that it is complete.
Also, work in progress on compatibility of Startin'Blox with Virtual Assembly's `SemApps <https://www.virtual-assembly.org/semapps/>`__ and Inrupt's `Community server <https://inrupt.com/Solid-roadmap-preview>`__.
Go to `Server Architecture <server-architecture.html>`_ to know more about it.
......
source/import_documentation/server-architecture.rst → source/import_documentation/djangoldp_guide/server-architecture.rst
+ 2
− 2
View file @ 4eb007b8
......@@ -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.
......
source/import_documentation/tutorial-podcast.rst → source/import_documentation/first_step/get-started.rst
+ 7
− 4
View file @ 4eb007b8
Startin'blox 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 `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.
......@@ -344,4 +344,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 `Framework guide <framework-guide-intro>`__.
source/import_documentation/what-is-sib.rst → source/import_documentation/first_step/sib-presentation.rst
+ 150
− 0
View file @ 4eb007b8
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.**
......@@ -21,22 +27,26 @@ We've built a solution to make the creation of federated and interoperable appli
=> 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 `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.
......@@ -47,9 +57,11 @@ 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.
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.
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
:alt: Server overview
......@@ -62,9 +74,10 @@ The solution can be summarized as follows:
.. figure:: ../_static/images/import_documentation/Overview-of-SiB.png
:alt: SiB overview
Overview of the Framework
--------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
......@@ -77,3 +90,61 @@ Here is a brief presentation:
`To go deeper <https://git.happy-dev.fr/startinblox/framework/sib-core/>`__.
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
+ 4
− 0
View file @ 4eb007b8
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>`
......
source/import_documentation/introduction-framework-documentation.rst → source/import_documentation/framework_guide/how-to-use-the-documentation.rst
+ 4
− 2
View file @ 4eb007b8
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
+ 11
− 0
View file @ 4eb007b8
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
+ 21
− 0
View file @ 4eb007b8
Base components
***************
These components offer basic functionalities used in
an simple web application like display data, create data, search data, etc.
The base components are :
.. toctree::
:maxdepth: 1
import_documentation/Components/Solid-Ac-Checker
import_documentation/Components/Solid-Calendar
import_documentation/Components/Solid-Display
import_documentation/Components/Solid-Delete
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
\ No newline at end of file
source/import_documentation/framework_guide/list-external-components.rst 0 → 100644
+ 11
− 0
View file @ 4eb007b8
External components
*******************
The external components are not required for an application to be functional,
however they can be used to add useful features such as authentication and router:
.. toctree::
:maxdepth: 1
import_documentation/Components/Solid-Auth
import_documentation/Components/Solid-Router
source/import_documentation/framework_guide/list-mixins.rst 0 → 100644
+ 22
− 0
View file @ 4eb007b8
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/sorter-mixin
import_documentation/Mixins/store-mixin
import_documentation/Mixins/validation-mixin
import_documentation/Mixins/widget-mixin
source/import_documentation/framework_guide/list-widgets.rst 0 → 100644
+ 11
− 0
View file @ 4eb007b8
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
+ 6
− 5
View file @ 4eb007b8
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
+ 0
− 814
View file @ fa2114dd
Getting Started
****************
Fisrt of all, you have to keep in mind that your front and your back are decorrelated.
Let's begin by create your data source.
Make your data sources
======================
Before deploying any SIB applications you will need SIB servers able to provide all capabilities your application relies on.
Our SiB server is called DjangoLDP which is based on Django framework and adapted to be compatible with Linked Datas convention but you can use any servers exposing data as LDP containers.
DjangoLDP come with packages developed and maintained by the Startin'Blox team. You can pick up the ones you like or write your own.
Requirements
-------------
The SIB server requires:
* python 3.6
* postgresql database (for production)
.. warning:: if you using Windows, you may get some trouble. Please help us to improve reporting your problem on `this issue <https://git.startinblox.com/documentation/doc/issues/11/>`__
1. Install SIB Manager command
--------------------------
We have developed a command to facilitate the deployment of servers : ** Sib Manager**. It is not yet perfect and if you encounter a problem, help us to improve, `open a issue <https://git.startinblox.com/framework/sib-core/issues/new?issue%5Bassignee_id%5D=&issue%5Bmilestone_id%5D=>`__.
Install ``sib-manager`` that allow you to use the sib command.
.. code-block:: bash
python3 -m pip install -U sib-manager
2. Initiate the server
--------------------
Set up the server with SIB Manager where `sibserver` will be the name of your server.
.. code-block:: bash
sib startproject sibserver
cd sibserver
sib install server
.. notice:: For production, add the `--production` flag like this `sib startproject sibserver --production`
now your architecture should look like :
.. code-block:: bash
sibserver/
server/
__init__.py
settings.py
urls.py
wsgi.py
manage.py
packages.yml
You will find in your `package.yml` the configuration of your server.
On this server, you will add the package relative to the data shape you want to use in your component.
.. figure:: ../_static/images/import_documentation/Overview-server.png
:alt: Server overview
Let's now create a package.
3. Create a package
--------------------
We are going to make a very simply data source to start which will be composed by questions and its answers.
You use the SIB Manager to create a new project :
.. code-block:: bash
sib startpackage djangoldp_mypack
cd djangoldp_mypack
.. note:: All your package should respect this semantic. For example djangoldp_skills.
Go to your `models.py` and set the models of datas you need :
.. code-block:: python
from django.db import models
from djangoldp.models import Model
class FAQElement(Model):
question = models.CharField(max_length=128, verbose_name="Question", blank=True, null=True)
answer = models.CharField(max_length=128, verbose_name="Answer", blank=True, null=True)
class Meta:
anonymous_perms = ['']
authenticated_perms = ['view', 'edit', 'delete', 'add']
serializer_fields=["@id","question", "answer"]
4. Link your package to your developpement server
----------------------------------
At the root of you Sib sever, create a symbolic link to your package :
.. code-block:: bash
ln -s ../path/to/package/app/name-of-package
For example :
.. code-block:: bash
ln -s ../../djangoldp_mypack/djangoldp_mypack djangoldp_mypack
You can check if it's well done with the `ll` command :
.. figure:: ../_static/images/import_documentation/ll.png
:alt: You've done the symbolic link.
Tell your sever, you've add a new package in the packages.yml:
.. code-block:: yml
ldppackages:
djangoldp_mypack: djangoldp_mypack
5. Set up your server
-----------------------
.. warning:: If you want to configure a server with a package that already exist, you will need to make the "sib install sibserver" to update your server with it.
Go at the root of your developpement server at the level where reside your manage.py file.
Then run this command :
.. code-block:: bash
# Make the migration
python manage.py makemigrations
python manage.py migrate --run-syncdb
#Create a super user
python manage.py createsuperuser
#launch your server
python manage.py runserver
Now access to your Django administration `http://127.0.0.1:8000/admin/ <http://127.0.0.1:8000/admin/>`__.
You should see your model in the admin.
Fill one question and answer to test.
**Access your API**
To access to the jsonLD API, go to `http://127.0.0.1:8000/faqelements/ <http://127.0.0.1:8000/faqelements/>`__, where faqelement is the name of you model.
You should get something like this :
.. code-block:: json
{
"@id": "http://localhost:8000/faqelements/",
"@type": "ldp:Container",
"ldp:contains": [
{
"@id": "http://localhost:8000/faqelements/1/",
"question": "What is SOLID ?",
"answer": "SOLID is a set of standard to create interoperability.",
"permissions": [
{
"mode": {
"@type": "view"
}
},
{
"mode": {
"@type": "delete"
}
}
]
}
],
"permissions": [
{
"mode": {
"@type": "add"
}
},
{
"mode": {
"@type": "view"
}
}
],
"@context": "https://cdn.happy-dev.fr/owl/hdcontext.jsonld"
}
Concratulation ! You've made a data source.
.. note::
To see how our API is structured, have a look to our `SOLID Introduction <https://docs.startinblox.com/import_documentation/Solid-introduction>`__
Make a font app
===============
If you are familiar with React or VusJS, learning how to use Startin'blox is going to be easy for you. It's even easier.
So why using Startin'blox instead of React or VueJS?
-------------------------------------------
Because it allows you to easily grasp the SOLID standards and web components last standards. It is also lighter to install.
See more about it in :ref:`our FAQ <faq>`.
How to set up the technology ?
----------------------------
Fisrt set up a server for your front App using :
* NPM via http-server
* Python via `python3 -m http.server 8001`
To start, simply import the core in the head tag of a index.html file:
.. code-block:: html
<!-- ... Import the core ... -->
<script type="module" src="https://unpkg.com/@startinblox/core"></script>
Base Components
~~~~~~~~~~~~~~~
It enables you to use Startin’blox technology and all the base components from the core of the framework like `Solid-display <https://docs.startinblox.com/import_documentation/Components/SiB-Display.html>`__, that displays data or `Solid-form <https://docs.startinblox.com/import_documentation/Components/SiB-Form.html>`__ that offer a form to post data.
.. code-block:: html
<solid-display
data-src="https://apiprod.happy-dev.fr/collectives/"
fields="name, email"
></solid-display>
.. note::
**The ``data-src`` attribute**
You will find it in almost all Startin'blox components. It is the attribute that defines the data source you want to interact with in the component. You can see what the API looks like at (`https://apiprod.happy-dev.fr/collectives/ <https://apiprod.happy-dev.fr/collectives/>`__ ).
For our example, let's display your data sources by remplacing the data-source below by the one you created :
.. code-block:: html
<solid-display
data-src="http://127.0.0.1:8000/faqelements/"
fields="question, answer"
></solid-display>
.. note::
**Some public sources to play**
To make your tests with Startin'blox, here are some public readonly data sources:
* `The Happy Dev events <https://apiprod.happy-dev.fr/futureevents/>`__.
* `The Happy Dev collectives <https://apiprod.happy-dev.fr/collectives/>`__.
* `The Startin'blox features <https://api.startinblox.com/features/>`__.
External Components
~~~~~~~~~~~~~~~~~~~
Some useful components aren't in the core to keep it light and modular. It's the case for `Solid-Router <https://docs.startinblox.com/import_documentation/Components/SiB-Router.html>`__ or `Solid Auth <https://docs.startinblox.com/import_documentation/Components/Solid-Auth.html>`__ for example.
To use them, you have to import them independently.
.. code-block:: html
<!-- ... Import the core ... -->
<script type="module" src="https://unpkg.com/@startinblox/core"></script>
<script type="module" src="https://unpkg.com/@startinblox/router@latest"></script>
Create a component
====================
A component should be independent from your application, so you should create a new project to developpe it.
.. note::
If you want to know when it's relevant to create a component go to the :ref:`"About our Components" <About-our-components>` page.
Requirements
-------------
Be sur you have at least the version 6.14.5 of npm with :
.. code:: bash
npm -v
To update your npm version :
.. code:: bash
npm install -g npm@latest
.. warning::
You may need to prefix these commands with sudo, especially on Linux, or OS X if you installed Node using its default installer.
We will assume that you are at least comfortable with HTML, CSS and JavaScript. However, you don't really need to be an expert.
We recommend `this good guide <https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript>`__ to get you back on track with JS.
Steps
-----
Let's set up a local development environment for a FAQ component as example.
**1**. Set the file you need .
.. code:: bash
solid-faq
- index.html
- solid-faq.js
.. note::
By convention, we prefix Startin'blox components with "solid". Example: solid-faq, solid-agenda, solid-map..
**2**. Init npm and set your server
Open a terminal, go to your folder and type the following commands:
.. code:: bash
# Init a npm management
npm init -y
# Install a server in a developpement environement
npm i -D http-server
Go to your ``package.json`` and replace the 'test' script by the following :
.. code:: json
"serve": "http-server"
Your ``package.json`` should look like this :
.. code:: json
{
"name": "solid-faq",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"serve": "http-server"
},
"keywords": [],
"author": "",
"license": "ISC",
"dependencies": {},
"devDependencies": {
"http-server": "^0.12.3"
}
}
**3**. Start your component
We have create SolidTemplateElement that is a class that can extend your component in order to purify your code of all useless complexity so that you can concentrate on the essential: your functionality.
**What are we going to do?**
Let's just displays questions and answers in an accordion and allows the user to submit a new question.
Something like this:
.. image:: ./../../_static/images/import_documentation/faq.gif
:alt: A FAQ component as example
Let's suppose we want to make the recipient's email customizable.
To obtain this rendering, it would be enough to implement in our html page a component that looked like this:
.. code:: html
<solid-faq
data-src="https://api.startinblox.com/faqs/"
recipient-email="alice@startinblox.com"
></solid-faq>
.. note::
**Remember the ``data-src`` attribute ?**
This attribute hosts the data source you want to interact with in this component.
.. note::
**Want to learn more about web components ?**
We recommend this `introduction <https://www.webcomponents.org/introduction>`__.
**Let's start !**
Here is the minimum code your component must contain that extends ``SolidTemplateElement``.
.. code:: js
/**
* solid-faq.js
*/
// Import SolidTemplateElement
import SolidTemplateElement from "https://unpkg.com/@startinblox/core@0.10/dist/solid-template-element.js";
// Name your component and extend SolidTemplateElement
export class SolidFAQ extends SolidTemplateElement {
constructor() {
super();
}
// Define the attributes you want
static get propsDefinition() {
return {
dataSrc: "data-src",
recipientEmail: "recipient-email",
};
}
// Pass your attributes to your template
template({ dataSrc, recipientEmail }) {
// If we have no data sources, we display nothing
if (!dataSrc) return "";
let tmpl = `
<solid-display
data-src="${dataSrc}"
fields="question, answer"
id="faq"
></solid-display>
`;
// Otherwise, set the possibility to submit a question
if (recipientEmail) {
tmpl += `
<a href='mailto:${recipientEmail}?subject=A%20new%20question%20for%20the%20FAQ&body=Hi!'>
Your question question not here ?
</a>
`;
}
return tmpl;
}
}
customElements.define("solid-faq", SolidFAQ);
**4**. Pay attention to propsDefinition method
------------------------------------------
You are going to set your attribute in this method. `recipientEmail` is the parameter where we are going to fill in the email of our recipient.
.. code:: js
static get propsDefinition() {
return {
dataSrc: 'data-src',
recipientEmail: 'recipient-email'
}
}
.. note::
Note the syntaxe convention => recipientEmail: 'recipient-email'
5. Let's focus on the template
-------------------------------
The template contains the HTML you want to render. Pass your attributes to your template and write it.
To display the questions and answers, we are going to use :ref:`solid-display <solid-display>`.
The attributes fields is used to define which datas you want to display from your data source.
We add a conditional rendering: if no email is filled in, the possibility to submit a question is not displayed.
.. code:: js
// Pass your attributes to your template
template({ dataSrc, recipientEmail }) {
// If we have no data sources, we display nothing
if (!dataSrc) return "";
let tmpl = `
<solid-display
data-src="${dataSrc}"
fields="question, answer"
id="faq"
></solid-display>
`;
// Otherwise, set the possibility to submit a question
if (recipientEmail) {
tmpl += `
<a href='mailto:${recipientEmail}?subject=A%20new%20question%20for%20the%20FAQ&body=Hi!'>
Your question question not here ?
</a>
`;
}
return tmpl;
}
6. Set your datas
-----------------
You can you here the data source you've created. Or you can just set fake datas, with those static datas in `JSON-LD <https://fr.wikipedia.org/wiki/JSON-LD>`__ by create a file named ``data-faq.jsonld`` at the root of your project.
.. code:: json
{
"@id": "",
"@type": "ldp:Container",
"ldp:contains": [
{
"question": "What is Startin'blox ?",
"answer": "A cooperative and a technology to build the web of our dreams",
"@id": "questions-1",
"permissions": []
},
{
"question": "What is the SOLID project ?",
"answer": "A set of standards that allows web applications to all speak the same language and become interoperable.",
"@id": "questions-2",
"permissions": []
}
],
"permissions": [],
"@context": "https://cdn.happy-dev.fr/owl/hdcontext.jsonld"
}
.. note::
If you want to know more about how our API looks like, have a look to `our SOLID introduction <https://docs.startinblox.com/import_documentation/Solid-introduction.html>`__.
7. Implement your component
-----------------------------
Import the script of your component and set the component in your ``index.html``.
.. code:: html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<!--Import a custom font-->
<link href="https://fonts.googleapis.com/css2?family=Montserrat&display=swap" rel="stylesheet">
<!--Import the framework-->
<script type="module" src="https://unpkg.com/@startinblox/core"></script>
<!--Import the component-->
<script type="module" src="/solid-faq.js"></script>
<title>Solid FAQ Demo</title>
</head>
<body>
<h1>Solid FAQ Demo</h1>
<!--Import the component-->
<solid-faq
data-src="data-faq.jsonLD"
recipient-email="alice@startinblox.com"
></solid-faq>
</body>
</html>
6. Test your component
-----------------------
.. code:: bash
npm run serve
You should be able to display your datas but at the moment it's a bit ugly.
.. image:: ./../../_static/images/import_documentation/raw-faq.png
:alt: A FAQ component as example
You've almost done !
Let's now add some style.
7. Implement JS and CSS in your component
-----------------------------------------
For this example, we propose you to create a js file, like ``/js/main.js``.
Add the JS you need to make your accordion work, like this:
.. code:: js
/**
* js/main.js
*/
// Select the component
var component = document.getElementById("faq");
// We use populate event to detect when the component is generated
component.addEventListener("populate", (event) => {
// Seclect each question
var acc = document.querySelectorAll("solid-display-value[name='question']");
var i;
for (i = 0; i < acc.length; i++) {
//For each question, if we click..
acc[i].addEventListener("click", function () {
// Add or remove the "active" class
this.classList.toggle("active");
// Select the answer just below the question
var panel = this.nextElementSibling;
// If the answer is opened, then close it
if (panel.style.maxHeight) {
panel.style.maxHeight = null;
// Otherwise, open it.
} else {
panel.style.maxHeight = panel.scrollHeight + "px";
}
});
}
})
.. note::
**Did you notice the populate event?** It's an event that allows you to trigger javascript only after the component you want to manipulate has been generated.
See `the Event documentation <https://docs.startinblox.com/import_documentation/Events.html>`__ for more explanation.
Here is the CSS used for the demo:
.. code:: css
/**
* css/main.css
*/
body {
font-family: 'Montserrat', sans-serif;
background-color: #4475B8;
}
h1{
color : white;
}
solid-faq {
max-width : 700px;
}
solid-display-value[name='question'] {
cursor: pointer;
padding: 18px;
text-align: left;
border: none;
outline: none;
transition: 0.4s;
display : block;
background-color: white;
color : #4475B8;
}
solid-display-value[name='answer'] {
padding: 0 30px;
max-height: 0;
overflow: hidden;
transition: max-height 0.2s ease-out;
display : block;
background-color : #ECECEC;
color : #414141;
border : 1px #FDD17A solid;
line-height: 30px;
}
solid-display-value[name='question']:after {
content: '\02795';
font-size: 13px;
float: right;
margin-left: 5px;
}
solid-display-value[name='question'].active:after {
content: "\2796";
}
solid-faq solid-display+a{
color : white;
line-height : 50px ;
}
**Use Helper functions**
SiB framework provide you `Helpers function <https://docs.startinblox.com/import_documentation/Helpers-functions.html>`__ to add JS and CSS in your component.
Add at the begin of your ``solid-faq.js``, import your JS and CSS with those functions:
.. code:: js
...
// Import Helper functions
import {
importCSS,
importJS,
} from "https://unpkg.com/@startinblox/core@0.10/dist/libs/helpers.js";
// Use the Helpers functions
importJS(`./js/main.js`);
importCSS(`/css/main.css`);
export class SolidFAQ extends SolidTemplateElement {
...
**It should be better now, no ?**
.. image:: ./../../_static/images/import_documentation/faq.gif
:alt: A FAQ component as example
8. Translate your component
---------------------------
.. warning::
This part is not working and need improvement. You can jump to the step 8 :)
To translate the static strings of your components, follow these steps:
- In your component, create a folder which contains all the translation files. You can name it ``locales`` for example. Inside, create one file per language, with the structure ``[code_language].json``, for example: ``fr.json``.
- In each file, add one line per string to translate. Your file should look like this:
.. code:: json
{
"label.question": "Your question is not here ?"
}
- In the constructor of your component, define the path of your folder:
.. code:: js
// For the demo
const base_url = "./";
// The production url of your component =>
//const base_url = "https://path/to/your/component";
export class SolidFAQ extends SolidTemplateElement {
constructor() {
...
this.setTranslationsPath(`${base_url}/locales`);
}
...
}
- Use the ``localize`` method to show the translated strings in your template:
.. code:: js
const base_url = "https://unpkg.com/@startinblox/solid-faq"; // url of your component
export class SolidFAQ extends SolidTemplateElement {
...
template( { dataSrc, recipientEmail } ) {
if (!dataSrc) return '';
let tmpl = `
...
<a href='mailto:p.${recipientEmail}?subject=A%20new%20question%20for%20the%20FAQ&body=Hi!'>
${this.localize('label.question')}
</a>
`;
return tmpl
}
}
As a developer who uses a component, you can also add you own translation files by targeting you translation folder.
Like for the component, this folder should contain one file per language:
.. code:: html
<solid-conversation
data-src="./data/conversations.jsonld"
extra-translations-path="http://my_app/locales"
></solid-conversation>
9. Does it work well?
---------------------
.. image:: ./../../_static/images/import_documentation/faq.gif
:alt: A FAQ component as example
If you get any trouble (or any idea to improve!), please `mail me <'mailto:alice@startinblox.com?subject=A%20feedback%20from%20the%20doc>`__ :)
.. note::
**Document your component!**
Each time you create a component, remember to document it with a README.md, especially the version of the core with which it was developed. If you create a component by default you will be considered as the maintainer. This means that you are responsible for its future updates but also that you could get support contracts on this component in the future :)
Releases are posted `here <https://git.startinblox.com/framework/sib-core/-/releases>`__.
Subscribe to the newsletter not to miss the next ones!
.. warning::
This tutorial could be improved by adding accessibility.
Go Deeper
==========
Discover other features of the framework playing with `the demo on the website <https://startinblox.com/fr/technology#demo>`__.
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