From 87d79315ac85af6611dfc466031725ff122d3c81 Mon Sep 17 00:00:00 2001
From: Alice Poggioli <alice.poggioli@paca.happy-dev.fr>
Date: Tue, 28 Jul 2020 09:53:38 +0200
Subject: [PATCH] add a tuto component
---
.../Components/SiB-Map.rst | 4 +
.../How-to-make-components.rst | 317 +++++++++++++++++-
source/index.rst | 1 +
3 files changed, 311 insertions(+), 11 deletions(-)
diff --git a/source/import_documentation/Components/SiB-Map.rst b/source/import_documentation/Components/SiB-Map.rst
index abd39d8..3b5fbaa 100644
--- a/source/import_documentation/Components/SiB-Map.rst
+++ b/source/import_documentation/Components/SiB-Map.rst
@@ -53,3 +53,7 @@ Events
``resourceSelect``
~~~~~~~~~~~~~~~~~~~
Triggered when a marker is clicked on the map
+
+Usefull links :
+---------------
+ To find latitude and longitude : https://www.latlong.net/
\ No newline at end of file
diff --git a/source/import_documentation/How-to-make-components.rst b/source/import_documentation/How-to-make-components.rst
index b9075c7..8f93542 100644
--- a/source/import_documentation/How-to-make-components.rst
+++ b/source/import_documentation/How-to-make-components.rst
@@ -1,18 +1,313 @@
-How-to make components
-----------------------
+How to make components
+######################
-We’ve made `a sib-tutorial
-component <https://git.startinblox.com/components/sib-tutorial>`__. It’s
-very simple exemple to provide you a template to start easily you own.
+When you should make a component
+=================================
-It’s a skeleton which use ``SIBTemplateElement``. For educational
-purposes, we would like to make a more detail example without our
-template.
+A component = a functionality (*through human eyes*)
-It will come soon :)
+Sometime you should wonder if it's relevant to make a component. "It's so simple to code, why make a component ?"
-If with this example, you have some questions left, please `open an
-issue <https://git.startinblox.com/components/sib-tutorial/issues>`__ ou
+Keep it in your mind : Component aren't justify by technical optimization issue but by human functional brick identification.
+
+**You share more than code, you share ideas for collaborative tools.**
+
+When you are coding an app, think twice : Is there any functionality that could be useful for other organizations?
+
+Example :
+---------
+An FAQ is just a sib-display and maybe a sib-form to make it collaborative. It's not usefull to encapsulate it according to technical considerations.
+But FAQ is an excellent onbaording and knowledge management tools. Creating a component is about creating inspiration.
+
+Let's code
+============
+
+1. Create a folder named "Solid-Faq"
+2. Open a terminal in the folder and type those following commands:
+
+.. code:: bash
+
+ #Init a npm management
+ npm init -y
+
+ #Install a server in a developpement environement
+ npm i -D http-server
+
+ #Create your index.html
+ touch index.html
+
+3. Go to your `package.json` and add the following script :
+
+.. code:: json
+
+ serve: http-server
+
+Your `package.json` should look like this :
+
+.. code:: json
+
+ {
+ "name": "frontAppTest",
+ "version": "1.0.0",
+ "description": "",
+ "main": "index.js",
+ "scripts": {
+ "serve": "http-server"
+ },
+ "keywords": [],
+ "author": "",
+ "license": "ISC",
+ "dependencies": {},
+ "devDependencies": {
+ "http-server": "^0.12.3"
+ }
+ }
+
+4. Create your `solid-faq.js`
+
+.. code:: bash
+
+ touch solid-faq.js
+
+Two methods
+=============
+
+1. SiBTemplateElement method
+--------------------------------
+
+When you should use this method :
+ * to encapsulate simple code
+ * if you don't have a lot of knowledge with SiB technology
+
+What do SiBTemplateElement :
+ * provide a web component modele
+ * make a rendu of the template you give
+ * dectect automatically change of attributs
+
+What you cannot do with SiBTemplateElement :
+ * Use mixin
+
+**How to use :**
+
+.. code:: js
+
+ //Firt import the Sib template.
+ import {SolidTemplateElement} from 'https://unpkg.com/@startinblox/core@0.10';
+
+
+ //Now start writing our component
+ export class SolidFAQ extends SolidTemplateElement {
+
+ //This method help you to definie the attributes you want
+ static get propsDefinition() {
+ return {
+ dataSrc: 'data-src',
+ attributeCustom: 'xyz',
+ }
+ }
+
+ //Finally, set the template of your component.
+ template({dataSrc, attributeCustom}) {
+ if (!dataSrc) return '';
+ let yourTemplate = ``;
+ return yourTemplate
+ }
+ }
+
+ customElements.define('solid-faq', SolidFAQ);
+
+5. Set them in the propsDefinition method.
+For example, in this faq we want to custom the title and the email of a moderator.
+
+.. code:: js
+
+ static get propsDefinition() {
+ return {
+ dataSrc: 'data-src',
+ title: 'title',
+ moderator: 'moderator'
+ }
+ }
+
+6. Create your template.
+
+.. code:: js
+
+ template({dataSrc, moderator, title}) {
+ console.log(dataSrc, moderator, title);
+ if (!dataSrc) return '';
+ let tmpl = `
+ <h3>${title}</h3>
+ </sib-widget>
+ <sib-display
+ data-src="${dataSrc}"
+ fields= "question, answer"
+ ></sib-display>
+ `;
+ if(moderator) {
+ tmpl += `
+ <a href='mailto:p.${moderator}?subject=A%20new%20question%20for%20the%20FAQ&body=Hi!'>Your question question not here ?</a>
+ `;
+ }
+ return tmpl
+ }
+
+7. To get straight to the point, you can use a static jsonld data set like below:
+
+.. 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"
+ }
+
+Call this file `data-faq.jsonld`
+
+8. Put the component in your index.html
+
+.. code:: json
+
+ <!DOCTYPE html>
+ <html lang="en">
+ <head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <script src="solid-faq.js" type="module"></script>
+ <title>Youpi !</title>
+ </head>
+ <body>
+ <solid-faq
+ data-src= "./questions.jsonld"
+ title = "Super FAQ">
+ moderator ="alice@startinblox.com"
+ </solid-faq>
+ </body>
+ </html>
+
+8. Test your component :
+
+.. code:: bash
+
+ npm run serve
+
+9. Add some css and js
+
+.. code:: css
+
+ /* In /css/main.css */
+ .accordion {
+ background-color: #eee;
+ color: #444;
+ cursor: pointer;
+ padding: 18px;
+ text-align: left;
+ border: none;
+ outline: none;
+ transition: 0.4s;
+ display : block;
+ }
+
+ .active, .accordion:hover {
+ background-color: #ccc;
+ }
+
+ .panel {
+ padding: 0 18px;
+ background-color: white;
+ max-height: 0;
+ overflow: hidden;
+ transition: max-height 0.2s ease-out;
+ display : block;
+ }
+
+ .accordion:after {
+ content: '\02795'; /* Unicode character for "plus" sign (+) */
+ font-size: 13px;
+ color: #777;
+ float: right;
+ margin-left: 5px;
+ }
+
+ .active:after {
+ content: "\2796"; /* Unicode character for "minus" sign (-) */
+ }
+
+.. code:: js
+
+ var component = document.getElementById("test");
+ component.addEventListener("populate",
+ (event) => {
+ var acc = document.getElementsByClassName("accordion");
+ var i;
+
+ for (i = 0; i < acc.length; i++) {
+ console.log(acc[i]);
+ acc[i].addEventListener("click", function () {
+ console.log("we click")
+ this.classList.toggle("active");
+ var panel = this.nextElementSibling;
+ console.log(panel)
+ if (panel.style.maxHeight) {
+ panel.style.maxHeight = null;
+ } else {
+ panel.style.maxHeight = panel.scrollHeight + "px";
+ }
+ });
+ }
+ })
+
+
+
+9. Import Css and your Js in your component.
+Helper fonctions can be import from the framework.
+
+.. code:: js
+
+ import {SolidTemplateElement, Helpers} from 'https://unpkg.com/@startinblox/core@0.10';
+
+ export class SolidFAQ extends SolidTemplateElement {
+
+ Helpers.importCSS(`/css/main.css`);
+ Helpers.importJS(`/js/main.js`);
+
+ static get propsDefinition() {
+ return {
+ dataSrc: 'data-src',
+ title: 'title',
+ moderator: 'moderator'
+ }
+ }
+
+ [...]
+
+ }
+
+ customElements.define('solid-faq', SolidFAQ);
+
+
+10. Done!
+
+
+We’ve also made `a sib-tutorial component <https://git.startinblox.com/components/sib-tutorial>`__. It’s
+very simple exemple to provide you an other template to start easily you own. Be thoughtful with the documentation of your readme :)
+
+If you have some questions left, please `mail us <'mailto:alice@startinblox.com?subject=A%20feedback%20from%20the%20doc>`__ ou
ask us on the `community chat <https://community.startinblox.com>`__.
Thanks!
diff --git a/source/index.rst b/source/index.rst
index 151908a..754025a 100644
--- a/source/index.rst
+++ b/source/index.rst
@@ -21,6 +21,7 @@ Welcome to Startinblox's documentation!
import_documentation/install-sib-server
import_documentation/develop-sib-ldp-packages
import_documentation/server-architecture
+ import_documentation/How-to-make-components
.. import_documentation/core-framework-architecture
--
GitLab