From 98fa392d0d9977fa0f50938392e1ad2ea5beab46 Mon Sep 17 00:00:00 2001
From: ClmntBcqt <129279765+ClmntBcqt@users.noreply.github.com>
Date: Fri, 12 Jul 2024 16:11:21 +0200
Subject: [PATCH] Add exemple and doc for widgets and blocks (#32)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Add example and doc for widgets and blocks

---------

Co-authored-by: Clément <clement.becquet@algoo.fr>
Co-authored-by: Damien Accorsi <damien.accorsi@algoo.fr>
---
 EXAMPLES.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md   |  15 ++++++++
 2 files changed, 116 insertions(+)
 create mode 100644 EXAMPLES.md

diff --git a/EXAMPLES.md b/EXAMPLES.md
new file mode 100644
index 0000000..6a12a8a
--- /dev/null
+++ b/EXAMPLES.md
@@ -0,0 +1,101 @@
+# Examples of blocks usage :
+## With language as version  
+For instance, you could have different version of a widget `jinja2/widgets/navbar.html` :
+```jinja
+{% macro navbar(
+      LINK1 = "", TEXT1 = "",
+      LINK2 = "", TEXT2 = "",
+      LINK3 = "", TEXT3 = "",
+)
+%}
+<nav>
+    <a href="{{ LINK1 }}">{{ TEXT1 }}</a> |
+    <a href="{{ LINK2 }}">{{ TEXT2 }}</a> |
+    <a href="{{ LINK3 }}">{{ TEXT3 }}</a>
+</nav>
+{% endmacro %}
+```
+
+A block `jinja2/blocks/en/navbar.html` :
+```jinja
+{% from "widgets/navbar.html" import navbar %}
+
+{{ navbar(
+      LINK1 = "/index.html", TEXT1 = "Home",
+      LINK2 = "/contact.html", TEXT2 = "Contact us",
+      LINK3 = "/login/connect.html", TEXT3 = "Connexion",
+  ) }}
+```
+A block `jinja2/blocks/fr/navbar.html` :
+```jinja
+{% from "widgets/navbar.html" import navbar %}
+
+{{ navbar(
+      LINK1 = "/index.html", TEXT1 = "Accueil",
+      LINK2 = "/contact.html", TEXT2 = "Contactez-nous",
+      LINK3 = "/login/connect.html", TEXT3 = "Connexion",
+  ) }}
+```
+
+In `base.html`, we can include a navbar which depends of each page language by :
+```jinja
+{% from "blocks/block.html" import block %}
+
+{{ block(
+    NAME = "navbar",
+    VERSION = object.metadata.lang|default(""),
+    DEFAULT_NAME = "en/navbar.html"
+) }}
+```
+For all pages, if the page contains the metadata `lang` then the block will be searched as `blocks/<lang>/navbar.html`, and will be `blocks/en/navbar.html` if not found.\
+Else, the `default("")` filter allow to overpass the error and the block will be searched as `blocks/navbar.html`, and will be `blocks/en/navbar.html` if not found.\
+
+## With a product as version :
+For this example, we have a widget that prints information about a product in `jinja2/widgets/product.html` :
+```jinja
+{% macro product(
+      PRODUCT = {"name": "", "description": "", "price":""}, 
+)
+%}
+<div>
+    <h2>{{ PODUCT.name }}</h2>
+    <p>{{ PRODUCT.description }}</p>
+    <p>Buy it for {{ PRODUCT.price }}$ !</p>
+</div>
+{% endmacro %}
+```
+With two version of blocks `jinja2/blocks/prod1/product.html` and `jinja2/blocks/prod2/product.html` :
+```jinja
+{% from "widgets/product.html" import product %}
+{{ product(
+    PRODUCT = 
+        {
+            "name": "product1"
+            "description": "..."
+            "price": "12"
+        }
+) }}
+```
+```jinja
+{% from "widgets/product.html" import product %}
+{{ product(
+    PRODUCT = 
+        {
+            "name": "product2"
+            "description": "..."
+            "price": "36"
+        }
+) }}
+```
+And finally we can use this blocks with :
+```jinja
+{% from "blocks/block.html" import block %}
+{{ block(
+    NAME = "product"
+    VERSION = "prod1"
+)}}
+{{ block(
+    NAME = "product"
+    VERSION = "prod2"
+)}}
+```
diff --git a/README.md b/README.md
index 9bd08df..805e57a 100644
--- a/README.md
+++ b/README.md
@@ -102,6 +102,21 @@ This directory is for the static content, like images, CSS and JavaScript files
 It is accessible in templates by the Jinja or Django `static` function. \
 See the [Django doc](https://docs.djangoproject.com/en/5.0/howto/static-files/#configuring-static-files) for static files, or the [Jinja2 version](https://docs.djangoproject.com/en/5.0/topics/templates/#module-django.template.backends.django).
 
+### Blocks or widgets
+Widgets are reusable templates used to factor some content in pages. Widgets will be searched in the templates directories, in `<django|jinja2>/widgets/`
+
+Blocks are parts of content that can have multiple versions.
+They have no parameter as they use widgets when necessary.
+It is possible to use the macro `block(NAME, [VERSION], [DEFAULT_NAME])`, to include a bloc and specify its version. In this case, the block will be searched in the templates directories, in `<django|jinja2>/blocks/<block-version>/` .
+
+The `VERSION` and `DEFAULT_NAME` arguments of `block()` are optionnal.\
+If no `VERSION` is given, the block will be searched directly in `blocks/`.
+
+For `VERSION`, you can use page metadata, jinja variables, or just strings.
+
+For examples, see `EXAMPLES.md`.
+
+
 ## Others
 
 JFM-Engine is a friendly fork of [JSSG](https://github.com/jtremesay/jssg/) made in agreement with the JSSG developer because of different goals. \