Skip to content
Snippets Groups Projects
Commit bfd828e2 authored by Alice Poggioli's avatar Alice Poggioli
Browse files

Merge branch 'update/component-doc-improvements' into 'master' 

update: component doc improvements

See merge request !13
parents dcb3538f 6f229291
No related branches found
No related tags found
2 merge requests!19Enum dropdown radio solid-form-search,!13update: component doc improvements
Pipeline #7121 passed
Hide whitespace changes
Inline Side-by-side
source/import_documentation/Developping-with-SibTemplateElement.rst
+ 120
− 48
View file @ bfd828e2
......@@ -2,37 +2,37 @@ Developping a comoponent with SiBTemplateElement
================================================
.. warning::
To start this tutorial, you should I've followed `this first part <https://docs.startinblox.com/import_documentation/How-to-make-components.html>`__ .
To start this tutorial, you should have followed `this first part <https://docs.startinblox.com/import_documentation/How-to-make-components.html>`__ .
For the example, we are gonna make a FAQ component like this :
For the example, we are gonna make a FAQ component like this:
.. image:: ./../../_static/images/import_documentation/faq.gif
:alt: A FAQ component as example
1. Create a component that extend SolidTemplateElement
1. Create a component that extends SolidTemplateElement
-----------------------------------------------------
Here is the minimum code your component must contain that extends SolidTemplateElement.
Here is the minimum code your component must contain that extends ``SolidTemplateElement``.
.. code:: js
//Firt import the Sib template.
import {SolidTemplateElement} from 'https://unpkg.com/@startinblox/core@0.10';
// First import SolidTemplateElement
import SolidTemplateElement from 'https://unpkg.com/@startinblox/core@0.10/dist/solid-template-element.js';
//Name your component and extend it with SolidTemplateElement
// Name your component and extend SolidTemplateElement
export class SolidFAQ extends SolidTemplateElement {
//This method help you to definie the attributes you want
static get propsDefinition() {
return {
dataSrc: 'data-src',
attributeCustom: 'xyz',
dataSrc: 'data-src',
attributeCustom: 'xyz',
}
}
//Finally, set the template of your component.
template({dataSrc, attributeCustom}) {
// Finally, create the template of your component.
template( { dataSrc, attributeCustom } ) {
if (!dataSrc) return '';
let yourTemplate = ``;
return yourTemplate
......@@ -43,70 +43,71 @@ Here is the minimum code your component must contain that extends SolidTemplateE
2. Define the attribut you want for your component
2. Define the attributes you want for your component
---------------------------------------------------
**What custom setting do you want for your component?**
Let's assume we want to custom the title and the mail of the moderateur.
**What custom settings do you want for your component?**
Let's assume we want to customize the title and the email of the moderator.
It's in your `static get propsDefinition()` method that it take place.
It's in your ``static get propsDefinition()`` method that it takes place.
.. code:: js
static get propsDefinition() {
return {
dataSrc: 'data-src',
title: 'title',
moderatorEmail: 'moderator-email'
dataSrc: 'data-src',
title: 'title',
moderatorEmail: 'moderator-email'
}
}
.. note::
All the SiB components have the attribute `data-src'. It's the attribute that recieve the data-sources for the component.
All the SiB components have the attribute ``data-src``, which receives the data sources for the component.
3. Create your template
-----------------------
Pass your attributes to your template and write it.
Pass your attributes to your template and write it.
.. code:: js
//Pass attribute to your template
template({dataSrc, title, moderatorEmail}) {
template( { dataSrc, title, moderatorEmail } ) {
//Write your template
if (!dataSrc) return '';
let tmpl = `
<h3>${title}</h3>
<solid-display
data-src="${dataSrc}"
fields= "question, answer"
class-question = "accordion"
class-answer = "panel"
id="test"
></solid-display>
<h3>${title}</h3>
<solid-display
data-src="${dataSrc}"
fields="question, answer"
class-question="accordion"
class-answer="panel"
id="test"
></solid-display>
`;
if(moderatorEmail) {
tmpl += `
<a href='mailto:p.${moderatorEmail}?subject=A%20new%20question%20for%20the%20FAQ&body=Hi!'>Your question question not here ?</a>
<a href='mailto:p.${moderatorEmail}?subject=A%20new%20question%20for%20the%20FAQ&body=Hi!'>
Your question question not here ?
</a>
`;
}
return tmpl
}
As you can see, we've set classes to the question's and answer's fields to help us managing the accordion.
As you can see, we've set classes to the question and answer fields to help us managing the accordion.
4. Implement JS and CSS in your component
---------------------------------
Create a js file, like "/js/main.js".
Create a js file, like ``/js/main.js``.
Add the JS you need to make your accordion work, like this :
Add the JS you need to make your accordion work, like this:
.. code:: js
// /js/main.js
var component = document.getElementById("test");
component.addEventListener("populate",
(event) => {
component.addEventListener("populate", (event) => {
var acc = document.getElementsByClassName("accordion");
var i;
......@@ -125,7 +126,7 @@ Add the JS you need to make your accordion work, like this :
}
})
Here is the CSS used for the demo :
Here is the CSS used for the demo:
.. code:: css
......@@ -170,12 +171,12 @@ Here is the CSS used for the demo :
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 a Helpers functions :
Add at the begin of your ``solid-faq.js``, import your JS and CSS with those functions:
.. code:: js
//Import Helpers functions from the core
import {SolidTemplateElement, Helpers} from 'https://unpkg.com/@startinblox/core@0.10';
import { importCSS, importJS, uniqID } from 'https://unpkg.com/@startinblox/core@0.10/dist/libs/helpers.js';
//Use the Helpers functions
Helpers.importJS(`/js/main.js`);
......@@ -184,14 +185,14 @@ Add at the begin of your solid-faq.js, import your JS and CSS with a Helpers fun
export class SolidFAQ extends SolidTemplateElement {
....
4. Set fake datas
4. Set fake datas
---------------
Creating data sources is quite another matter. For the example, we will use static data in `JsonLD <https://fr.wikipedia.org/wiki/JSON-LD>`__.
Create a file named "datas-faq.jsonLD" at the root of your project and put these datas :
Create a file named ``datas-faq.jsonld`` at the root of your project and put these datas:
.. code:: json
......@@ -220,7 +221,8 @@ Create a file named "datas-faq.jsonLD" at the root of your project and put these
5. Implement your component
-----------------------------
Put the component in your index.html
Use the component in your ``index.html``.
If your component uses some core component like ``solid-display``, don't forget to import it in the ``<head>`` of your file.
.. code:: html
......@@ -229,6 +231,7 @@ Put the component in your index.html
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script type="module" src="https://unpkg.com/@startinblox/core@0.10"></script>
<script src="solid-faq.js" type="module"></script>
<title>Youpi !</title>
</head>
......@@ -238,28 +241,97 @@ Put the component in your index.html
fields="question, answer"
moderator-email="alice@startinblox.com"
title="Super faq"
>
</solid-faq>
></solid-faq>
</body>
</html>
6. Test your component :
6. Test your component:
-----------------------
.. code:: bash
npm run serve
7. Does it work well ?
7. Translate your component
---------------------------
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
{
"title": "Solid FAQ",
"label.question": "Your question is not here ?"
}
- In the constructor of your component, define the path of your folder:
.. code:: js
const base_url = "https://unpkg.com/@startinblox/solid-faq"; // url of 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, title, moderatorEmail } ) {
if (!dataSrc) return '';
let tmpl = `
...
<a href='mailto:p.${moderatorEmail}?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
<sib-conversation
data-src="./data/conversations.jsonld"
extra-translations-path="http://my_app/locales"
></sib-conversation>
8. 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>`__ :)
Go Deeper
Go Deeper
==========
Discover other functionalities of the framework playing with `the demo on the website <https://startinblox.com/fr/technology#demo>`__.
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