From c1ffe1483ffb835dc5f91dd73ac784947d5b8b9b Mon Sep 17 00:00:00 2001
From: Alice Poggioli <alice.poggioli@paca.happy-dev.fr>
Date: Fri, 4 Sep 2020 08:20:49 +0200
Subject: [PATCH] update tuto
---
...iB-Ac-Checker.rst => Solid-Ac-Checker.rst} | 0
.../{Sib-Calendar.rst => Solid-Calendar.rst} | 0
.../{SiB-Delete.rst => Solid-Delete.rst} | 0
.../{SiB-Display.rst => Solid-Display.rst} | 0
...-Form-Search.rst => Solid-Form-Search.rst} | 0
.../{SiB-Form.rst => Solid-Form.rst} | 0
.../Components/{SiB-Map.rst => Solid-Map.rst} | 0
.../{SiB-Router.rst => Solid-Router.rst} | 0
.../{SiB-Widget.rst => Solid-Widget.rst} | 0
.../Developping-with-SibTemplateElement.rst | 361 ++++++++++--------
.../How-to-make-components.rst | 3 +-
source/index.rst | 20 +-
12 files changed, 216 insertions(+), 168 deletions(-)
rename source/import_documentation/Components/{SiB-Ac-Checker.rst => Solid-Ac-Checker.rst} (100%)
rename source/import_documentation/Components/{Sib-Calendar.rst => Solid-Calendar.rst} (100%)
rename source/import_documentation/Components/{SiB-Delete.rst => Solid-Delete.rst} (100%)
rename source/import_documentation/Components/{SiB-Display.rst => Solid-Display.rst} (100%)
rename source/import_documentation/Components/{SiB-Form-Search.rst => Solid-Form-Search.rst} (100%)
rename source/import_documentation/Components/{SiB-Form.rst => Solid-Form.rst} (100%)
rename source/import_documentation/Components/{SiB-Map.rst => Solid-Map.rst} (100%)
rename source/import_documentation/Components/{SiB-Router.rst => Solid-Router.rst} (100%)
rename source/import_documentation/Components/{SiB-Widget.rst => Solid-Widget.rst} (100%)
diff --git a/source/import_documentation/Components/SiB-Ac-Checker.rst b/source/import_documentation/Components/Solid-Ac-Checker.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Ac-Checker.rst
rename to source/import_documentation/Components/Solid-Ac-Checker.rst
diff --git a/source/import_documentation/Components/Sib-Calendar.rst b/source/import_documentation/Components/Solid-Calendar.rst
similarity index 100%
rename from source/import_documentation/Components/Sib-Calendar.rst
rename to source/import_documentation/Components/Solid-Calendar.rst
diff --git a/source/import_documentation/Components/SiB-Delete.rst b/source/import_documentation/Components/Solid-Delete.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Delete.rst
rename to source/import_documentation/Components/Solid-Delete.rst
diff --git a/source/import_documentation/Components/SiB-Display.rst b/source/import_documentation/Components/Solid-Display.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Display.rst
rename to source/import_documentation/Components/Solid-Display.rst
diff --git a/source/import_documentation/Components/SiB-Form-Search.rst b/source/import_documentation/Components/Solid-Form-Search.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Form-Search.rst
rename to source/import_documentation/Components/Solid-Form-Search.rst
diff --git a/source/import_documentation/Components/SiB-Form.rst b/source/import_documentation/Components/Solid-Form.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Form.rst
rename to source/import_documentation/Components/Solid-Form.rst
diff --git a/source/import_documentation/Components/SiB-Map.rst b/source/import_documentation/Components/Solid-Map.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Map.rst
rename to source/import_documentation/Components/Solid-Map.rst
diff --git a/source/import_documentation/Components/SiB-Router.rst b/source/import_documentation/Components/Solid-Router.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Router.rst
rename to source/import_documentation/Components/Solid-Router.rst
diff --git a/source/import_documentation/Components/SiB-Widget.rst b/source/import_documentation/Components/Solid-Widget.rst
similarity index 100%
rename from source/import_documentation/Components/SiB-Widget.rst
rename to source/import_documentation/Components/Solid-Widget.rst
diff --git a/source/import_documentation/Developping-with-SibTemplateElement.rst b/source/import_documentation/Developping-with-SibTemplateElement.rst
index 0e461c4..cffc65a 100644
--- a/source/import_documentation/Developping-with-SibTemplateElement.rst
+++ b/source/import_documentation/Developping-with-SibTemplateElement.rst
@@ -11,7 +11,7 @@ It is a class that can extend your component in order to relieve you of some com
What are we going to do ?
-------------------------
For the example, we are gonna make a simple FAQ component.
-It just display questions and answers in an accordion. If somebody doesn't find its question, we want him to send an email to a moderation we decide.
+It just displays questions and answers in an accordion and allows the user to submit a new question.
Something like this :
@@ -19,115 +19,200 @@ Something like this :
:alt: A FAQ component as example
-Let's suppose we want to make the moderator's title and email customizable.
-To get this render, we will just have to implement the component to our html page with like this :
+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="./datas-faq.jsonLD"
- fields="question, answer"
- moderator-email="alice@startinblox.com"
- title="Super faq"
+ data-src="https://api.startinblox.com/faqs/"
+ recipient-email="alice@startinblox.com"
></solid-faq>
.. note::
- To learn more about web components, we recommend this `introduction <https://www.webcomponents.org/introduction>`__.
+ **Remember the data-src attribute ?**
+ This attribute that 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 :)**
1. Set the base of you component in a solid-faq.js file
-----------------------------------------------------
- .. note::
- Remember to rename your folder with Solid-FAQ !
-
Create a component that extends SolidTemplateElement.
Here is the minimum code your component must contain that extends ``SolidTemplateElement``.
.. code:: js
- // solid-faq.js
- // First import SolidTemplateElement
- import SolidTemplateElement from 'https://unpkg.com/@startinblox/core@0.10/dist/solid-template-element.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 {
- //This method help you to definie the attributes you want
+ // Define the attributes you want
static get propsDefinition() {
return {
- dataSrc: 'data-src',
- attributeCustom: 'attribute-custom',
- }
+ dataSrc: "data-src",
+ recipientEmail: "recipient-email",
+ };
}
- // Finally, create the template of your component.
- template( { dataSrc, attributeCustom } ) {
- if (!dataSrc) return '';
- let yourTemplate = ``;
- return yourTemplate
+ // 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);
+ customElements.define("solid-faq", SolidFAQ);
-
-2. Define the attributes you want for your component
+2. Pay attention to propsDefinition method
---------------------------------------------------
-You are going to set these attribute in your ``static get propsDefinition()`` method.
+You are going to set your attribute in this method.
.. code:: js
static get propsDefinition() {
return {
dataSrc: 'data-src',
- title: 'title',
- moderatorEmail: 'moderator-email'
+ recipientEmail: 'recipient-email'
}
}
.. note::
- Note the syntaxe convention => moderatorEmail: 'moderator-email'
+ Note the syntaxe convention => recipientEmail: 'recipient-email'
-3. Create your template
+3. Let's focus on the template
-----------------------
-The template contain the HTML you want to render.
-To display the questions and answers, we are going to use `Solid-display <https://docs.startinblox.com/import_documentation/Components/SiB-Display.html>`__.
-If a moderator's email is filled in then we display the possibility to send him an email.
+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 `solid-display <https://docs.startinblox.com/import_documentation/Components/Solid-Display.html>`__.
+The attributes fields is used to define which datas you want to display from your data source.
-Pass your attributes to your template and write it.
+We add a conditional rendering : if no email is filled in, the possibility to submit a question is not displayed.
.. code:: js
- //Pass attribute to your template
- 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="faq"
- ></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>
- `;
+ // 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;
}
- return tmpl
+
+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 ``data-faq.jsonld`` at the root of your project and put these datas:
+
+.. 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"
}
-As you can see, we've set classes to the question and answer fields to help us managing the accordion.
+.. note::
+ If you want to know more about how look our API, have a look to `our SOLID introduction <https://docs.startinblox.com/import_documentation/Solid-introduction.html>`__.
+
+5. 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
+
+Now you should be able to see your fake datas like this :
+
+ .. image:: ./../../_static/images/import_documentation/raw-faq.png
+ :alt: The raw FAQ
+
+At the moment it's a bit ugly. Let's add some style.
4. Implement JS and CSS in your component
---------------------------------
@@ -137,27 +222,35 @@ Add the JS you need to make your accordion work, like this:
.. code:: js
- // /js/main.js
- //We select the component
+ /**
+ * js/main.js
+ */
+ // Select the component
var component = document.getElementById("faq");
- //When the component is generated, we set the event
+
+ // We use populate event to detect when the component is generated
component.addEventListener("populate", (event) => {
- //Manage the accordion
- var acc = document.getElementsByClassName("accordion");
+
+ // Seclect each question
+ var acc = document.querySelectorAll("solid-display-value[name='question']");
var i;
for (i = 0; i < acc.length; i++) {
- acc[i].addEventListener("click", function () {
+ //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";
}
- });
+ });
}
})
@@ -169,10 +262,23 @@ Here is the CSS used for the demo:
.. code:: css
- /* /css/main.css */
- .accordion {
- background-color: black;
+ /**
+ * 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;
@@ -180,32 +286,36 @@ Here is the CSS used for the demo:
outline: none;
transition: 0.4s;
display : block;
+ background-color: white;
+ color : #4475B8;
}
- .active, .accordion:hover {
- background-color: blue;
- }
-
- .panel {
- padding: 0 18px;
- background-color: white;
+ 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;
}
- .accordion:after {
- content: '\02795'; /* Unicode character for "plus" sign (+) */
+ solid-display-value[name='question']:after {
+ content: '\02795';
font-size: 13px;
- color: white;
float: right;
margin-left: 5px;
}
- .active:after {
- content: "\2796"; /* Unicode character for "minus" sign (-) */
- color: white;
+ solid-display-value[name='question'].active:after {
+ content: "\2796";
+ }
+
+ solid-faq solid-display+a{
+ color : white;
+ line-height : 50px ;
}
**Use Helper functions**
@@ -215,82 +325,23 @@ Add at the begin of your ``solid-faq.js``, import your JS and CSS with those fun
.. code:: js
- //Import Helpers functions from the core
- 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`);
- Helpers.importCSS(`/css/main.css`);
-
- export class SolidFAQ extends SolidTemplateElement {
-
- ....
-
-
-
-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:
-
-.. code:: json
-
- {
- "@id": "",
- "@type": "ldp:Container",
- "ldp:contains": [
- {
- "question": "How to plant cabbages?",
- "answer": "Start seeds indoors 4 to 6 weeks before the last frost in spring. Sow seed outdoors when the soil can be worked in spring. Place transplants in the garden when they are 3 to 4 inches tall as early as 3 to 4 weeks before the last frost in spring. In cool-summer regions, plant cabbage in late spring for a fall harvest.",
- "@id": "questions-1",
- "permissions": []
- },
- {
- "question": "How deep do you plant carrots?",
- "answer": "Seeds should be planted about a ½ inch deep and 1 to 2 inches (2.5 to 5 cm.) apart. When growing carrots in the garden, you'll wait for your carrot plants to appear. When the plants are 4 inches (10 cm.)",
- "@id": "questions-2",
- "permissions": []
- }
- ],
- "permissions": [],
- "@context": "https://cdn.happy-dev.fr/owl/hdcontext.jsonld"
- }
-
-.. note::
- If you want to know more about how look our API, have a look to `our SOLID introduction <https://docs.startinblox.com/import_documentation/Solid-introduction.html>`__.
-
-5. Implement your component
------------------------------
-Import your script and set the component in your ``index.html``.
+ ...
-.. code:: html
+ // Import Helper functions
+ import {
+ importCSS,
+ importJS,
+ } from "https://unpkg.com/@startinblox/core@0.10/dist/libs/helpers.js";
- <!DOCTYPE html>
- <html lang="en">
- <head>
- <meta charset="UTF-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <!-- import your component -->
- <script src="solid-faq.js" type="module"></script>
- <title>Youpi !</title>
- </head>
- <body>
- <solid-faq
- data-src="./datas-faq.jsonLD"
- fields="question, answer"
- moderator-email="alice@startinblox.com"
- title="Super faq"
- ></solid-faq>
- </body>
- </html>
+ // Use the Helpers functions
+ importJS(`./js/main.js`);
+ importCSS(`/css/main.css`);
-6. Test your component:
------------------------
+ // Name your component and extend SolidTemplateElement
+ export class SolidFAQ extends SolidTemplateElement {
-.. code:: bash
+ ...
- npm run serve
7. Translate your component
---------------------------
@@ -354,10 +405,10 @@ Like for the component, this folder should contain one file per language:
.. code:: html
- <sib-conversation
+ <solid-conversation
data-src="./data/conversations.jsonld"
extra-translations-path="http://my_app/locales"
- ></sib-conversation>
+ ></solid-conversation>
8. Does it work well?
diff --git a/source/import_documentation/How-to-make-components.rst b/source/import_documentation/How-to-make-components.rst
index 7bebb2b..4599997 100644
--- a/source/import_documentation/How-to-make-components.rst
+++ b/source/import_documentation/How-to-make-components.rst
@@ -3,6 +3,7 @@ How to create components
.. note::
**When you should create a component**
+
*A component is a feature*
A component is an application service that can be re-used by multiple organizations. You can think about it as an atomic functionality that can be picked and added by people with no technical skills.
@@ -15,7 +16,6 @@ How to create components
Developing with Startin'Blox is an opportunity to shift your perspective regarding who you program for. Instead of thinking just about your own requirements, you're invited to deliver features useful to both your own project and a much broader ecosystem of organizations.
**Example with a FAQ component**
- ---------------------------
For instance, implementing a collaborative FAQ could be done with little code. Encapsulating them within an FAQ component wouldn't make your code more concise. But it permit you to share the *idea* of a FAQ as a tool of onboarding or knowledge management.
@@ -24,7 +24,6 @@ How to create components
So, when you develop a new feature, think about who could use it. If it can be useful to others and there's no similar component already available, make a component so that your work will be easily accessed and used by many!
**Other example :**
- ---------------
* An interactive map
* An agenda
* A job board
diff --git a/source/index.rst b/source/index.rst
index 3a24dc8..8359cd8 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -1,4 +1,4 @@
-Welcome to Startinblox's documentation!
+Welcome to Startinblox's documentation
========================================
.. toctree::
@@ -10,8 +10,6 @@ Welcome to Startinblox's documentation!
import_documentation/get-started
import_documentation/Solid-introduction
import_documentation/faq
-
-.. import_documentation/get-involved
.. toctree::
:maxdepth: 2
@@ -27,13 +25,13 @@ Welcome to Startinblox's documentation!
:maxdepth: 2
:caption: Base components:
- import_documentation/Components/SiB-Display
- import_documentation/Components/SiB-Form
- import_documentation/Components/SiB-Delete
- import_documentation/Components/Sib-Calendar
- import_documentation/Components/SiB-Map
- import_documentation/Components/SiB-Ac-Checker
- import_documentation/Components/SiB-Widget
+ import_documentation/Components/Solid-Display
+ import_documentation/Components/Solid-Form
+ import_documentation/Components/Solid-Delete
+ import_documentation/Components/Solid-Calendar
+ import_documentation/Components/Solid-Map
+ import_documentation/Components/Solid-Ac-Checker
+ import_documentation/Components/Solid-Widget
.. toctree::
:maxdepth: 2
@@ -64,7 +62,7 @@ Welcome to Startinblox's documentation!
import_documentation/Widgets/Reference
import_documentation/Widgets/Examples
-Å“
+
.. toctree::
:maxdepth: 2
:caption: Javascript Api:
--
GitLab