Forem: Steeve

Cheat Sheet for Carbone

Steeve — Thu, 20 Nov 2025 09:00:00 +0000

Carbone is a templating engine designed to generate dynamic documents (PDFs, DOCX, XLSX, PPTX, etc.) by merging templates with JSON data:

The JSON Data-set coming from your application, database, or API.
The template must be designed using a Text Editor like Word, LibreOffice or Google Docs. To inject the content dynamically you must write Tags (a.k.a. placeholder), it will be replaced with the corresponding values from the JSON data.

Carbone’s tag syntax offers a lot of possibilities! This article focuses on the essentials, but if you want to dive deeper or see more examples, check out the official documentation.

Click to download the Cheat Sheet without image compression

Essential Carbone Templating Syntax

1. Basic Placeholder

The placeholder tag injects the value of a property from the root of the JSON data object (d). It is the simplest way to insert dynamic data into your template. For instance, if the JSON dataset is:

{ 
  "firstname": "John"
}

Insert the following tag in the template:

{d.firstname}

and it will be replaced with "John" in the generated document.

2. Nested Placeholder

This tag accesses nested properties in the JSON data. It allows you to traverse deeper into the JSON structure to retrieve specific values. There is no limit to access in depth of nested properties. For instance, If your JSON is:

{
  "user": {
    "name": "Alice"
  }
}

The tag in the template file:

{d.user.name}

will be replaced with "Alice".

3. Access Parent Property

The double dot (..) notation lets you access a property of the parent object from a nested context. To access the grandparent object’s property, use three dots (...). You can chain as many dots as needed to navigate up the object hierarchy. If your JSON is:

{
  "country": "France",
  "movie": {
    "name": "Inception", 
    "sub": {
      "a" : "test"
    }
  }
}

The tag in the template:

{d.movie.sub..name}
{d.movie.sub...country}

The first tag will be replaced with "Inception".
The second tag will be replaced with "France"

4. Array Access with Static Index

This tag accesses a specific element in an array by its index using the square bracket notation [index]. It is useful for retrieving a particular item from an array without looping. If your JSON is:

{
  "movies": [
    { "name": "Inception" },
    { "name": "Matrix" }
  ]
}

The tag in the template:

{d.movies[0].name}

will be replaced with "Inception".

5. Conditional Logic

This tag uses the :ifEQ formatter to check if a value meets a specific condition. If the condition is met, it prints the specified text. It exists many conditional formatters (e.g. :ifIN, :ifGT, etc...), and it can be chained (using :and, :or) for complex logic and used in inline conditions, or conditional sections. If your JSON is:

{
  "isActive": true
  "message": "Your subscription is disabled."
}

The tag in the template:

{d.isActive:ifEQ(true):show('Yes'):elseShow(.message)}

will be replaced with the static text "Yes" if the value is true, otherwise the value of the "message" field is printed.

6. Default Value

Still using conditional formatters, the :ifEM formatter checks if a value is empty (null, undefined, empty string, empty array, or empty object). If it is, it prints the specified default value. If your JSON is:

{
  "user": {
    "name": null
  }
}

The tag in the template:

{d.user.name:ifEM:show('Unknown')}

will be replaced with the static text "Unknown".

7. Loop (Array Iteration)

Use the square bracket notation [i] to iterate over arrays, The character i is the loop iterator (automatically managed by Carbone). Then insert the [i+1] tag, which signals the end of the pattern and is automatically removed during rendering.

This allows you to repeat content for each item in an array. If your JSON is:

{
  "users": [
    { "id": 1, "name": "Alice", "role": "Admin" },
    { "id": 2, "name": "Bob", "role": "Editor" },
    { "id": 3, "name": "Charlie", "role": "Viewer" }
  ]
}

The tag in the template:

{d.users[i].id} - {d.users[i].name}
<!-- End of loop pattern -->
{d.users[i+1]}

will print each user's id and name in a new line.

Note: You do not need to repeat each [i] tag with [i+1], just the one [i+1] is enough for Carbone to recognize the loop pattern.

8. Loop of Nested Arrays

Use the square bracket notation [i] and [i+1] (explained the previous point) to iterate over arrays, including nested ones. You can nest loops as deeply as needed. Finally, always use i as the loop iterator, even for nested arrays: Do not ever use "j" or other characters. If your JSON is:

[
  {
    "brand": "Toyota",
    "models": [
      { "size": "Prius 4", "power": 125 },
      { "size": "Prius 5", "power": 139 }
    ]
  },
  {
    "brand": "Kia",
    "models": [
      { "size": "EV4", "power": 450 },
      { "size": "EV6", "power": 500 }
    ]
  }
]

The tags loops in the template:

{d[i].brand}
Models
{d[i].models[i].size} - {d[i].models[i].power}
{d[i].models[i+1]}
{d[i+1]}

Will generate the following content:

Toyota
Models
Prius 4 - 125
Prius 5 - 139
Kia
Models
EV4 - 450
EV6 - 500

9. Filter a Loop

In a loop, it is possible to filters Arrays to only include items that meet a specific condition. Only matching items are printed in the loop. You can add as many conditions as you want, based on the attributes in your list. To filter an array, use the following syntax in your loop tag:

{d.array[i, condition1, condition2, ...]}

If you have the following JSON:

{
  "items": [
    {"name": "Strawberries", "price": 268, "category": "fruit"},
    {"name": "Apple", "price": 50, "category": "fruit"},
    {"name": "Banana", "price": 150, "category": "fruit"},
    {"name": "Carrot", "price": 80, "category": "vegetable"}
  ]
}

The tag in the template:

{d.items[i, price > 100, category="fruit"].name}
{d.items[i+1, price > 100, category="fruit"]}

will only print "Strawberries" and "Banana". The loop prints items where the price is greater than 100 and the category is "fruit".

10. Sort a Loop

In a loop, it is possible to sorts Array by a one or multiple attributes before iterating over it. The array will be sorted in ascending order based on the first attribute, then by the second attribute if values are equal, and so on. The syntax is:

{d.array[attribute1, attribute2, ..., i]}

If your JSON is:

{
  "items": [
    {"name": "Apple", "power": 2},
    {"name": "Banana", "power": 1}
  ]
}

The tag in the template:

{d.items[power, i].name}
{d.items[power+1, i+1].name}

will print "Banana" followed by "Apple". You can specify as many attributes as you want (e.g., power, name, etc.).

Important note: while sorting, the i iterator must always be the last element in the squared brackets.

11. Formatters

Formatters are functions appended to tags with a colon (:) that modify data before display. They can accept static or dynamic parameters.

11.1 Text Formatters

These formatters transform text in various ways, such as changing case, extracting substrings, replacing text, and more.

Formatter	Description	Example
:lowerCase()	Converts text to lowercase	{d.name:lowerCase()}
:upperCase()	Converts text to uppercase	{d.name:upperCase()}
:substr(start, length)	Extracts a substring	{d.text:substr(0, 5)}
:replace(search, replace)	Replaces text	{d.text:replace('old', 'new')}
:len()	Returns the length of a string or array	{d.text:len()}
:convCRLF()	Converts line breaks to `<br>`	{d.text:convCRLF()}
:preserveCharRef()	Preserves character references	{d.text:preserveCharRef()}
:t	Translates text (Learn more on the dedicated section below)	{d.greeting:t}

11.2 Number Formatters

These formatters format numbers, including setting precision, rounding, and performing arithmetic operations.

Formatter	Description	Example
:formatN(decimals)	Formats with the specified number of decimal places.	{d.price:formatN(2)}
:round(decimals)	Rounds with the specified number of decimal places.	{d.value:round(2)}
:floor()	Rounds down to the nearest integer.	{d.value:floor()}
:ceil()	Rounds up to the nearest integer.	{d.value:ceil()}
:add(value)	Adds a value	{d.value:add(10)}
:sub(value)	Subtracts a value	{d.value:sub(10)}
:mul(value)	Multiplies by a value	{d.value:mul(2)}
:div(value)	Divides by a value	{d.value:div(2)}
:mod(value)	Modulo operation	{d.value:mod(2)}
:abs()	Absolute value	{d.value:abs()}

11.3 Currency Formatters

These formatters format numbers as currency, including setting precision and converting between currencies.

Formatter	Description	Example
:formatC(precision, currency)	Formats a number as currency	{d.price:formatC(2, 'USD')}
:convCurr(source, target)	Converts currency	{d.price:convCurr('EUR', 'USD')}

11.4 Date Formatters

These formatters format dates according to specified patterns.

Formatter	Description	Example
:formatD(pattern)	Formats a date	{d.date:formatD('YYYY-MM-DD')}
:formatI(pattern)	Formats an interval	{d.interval:formatI('HH:mm')}

11.5 Array Formatters

These formatters manipulate arrays, such as joining elements, and mapping values, and performing aggregations (Process a set of values and returns a single aggregated result).

Formatter	Description	Example
:arrayJoin(separator)	Joins array elements	{d.array:arrayJoin(', ')}
:arrayMap(separator, keySeparator, key)	Maps array elements	{d.array:arrayMap(', ', ':', 'id')}
:aggStr(separator)	Aggregator to concatenate array elements	{d.array[].value:aggStr(', ')}
:aggSum()	Aggregator to sums array elements	{d.array[].value:aggSum()}
:aggAvg()	Aggregator to get the average	{d.array[].value:aggAvg()}
:aggMin()	Aggregator to get the minimum value	{d.array[].value:aggMin()}
:aggMax()	Aggregator to get the maximum value	{d.array[].value:aggMax()}
:aggCount()	Aggregator that return the total number of elements	{d.cars[sort>20].qty:aggCount}
:cumSum()	Aggregator for running totals: Calculates and prints the cumulative sum of data	{d[i].qty:cumSum} {d[i+1]}
:cumCount()	Aggregator that print a sequential integer to each row in a list.	{d[i].qty:cumCount} {d[i+1]}

12. Colors

The :color formatter lets you dynamically apply colors to text, paragraphs, cells, rows, or shapes in your templates. You specify the target element and the color value from your JSON data. The syntax is:

{d.colorValue:color(scope, types)}

If your JSON is:

{
  "warningHexa": "#FF0000",
  "highlightHexa": "#FFFF00"
}

The tag in the template:

<!-- For Text --> 
{d.warningHexa:color(p)}This text will be red.
<!-- For Tables -->
{d.highlightHexa:color(cell, background)}This cell will have a yellow background.

will color the text "This text will be red." in red and the cell background of "This cell will have a yellow background." in Yellow.

13. Inject HTML from WYSIWYG or Code Editors

The :html formatter allows you to inject raw HTML strings from your JSON data directly into your template (supported formats: DOCX, ODT and PDF). Without this formatter, "<" and ">" characters are escaped, and HTML is not rendered. If your JSON is:

{
  "welcomeMessage": "<strong>Welcome!</strong> Here’s your dashboard."
}

The tag in the DOCX template:

{d.welcomeMessage:html}

the welcome message is injected, and the HTML is rendered in the generated document.

14. Merge PDFs

The :appendFile(position) formatter lets you dynamically insert a PDF into your generated PDF document. The file can be provided as a Base64 string or a URL in your JSON data. If your JSON data is:

{
  "contractPDF": "base64EncodedPdfFile",
  "links": {
    "welcomePDF": "https://domain/welcome.pdf"
  }
}

The tag in the template:

{d.links.welcomePDF:appendFile(start)}
{d.contractPDF:appendFile(end)}

15. Images

To inject images dynamically, a placeholder image must be defined in the template with the tag as alternative text. Then Carbone will replace the placeholder images with images specified in your JSON data-set. In order you have to:

Insert a placeholder/dummy image in your template.
Place the tag in the alternative text of the placeholder image.
Specify the image in your JSON as either a Base64-encoded string or a URL.

If your JSON data is:

{
  "logoBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "profilePictureUrl": "https://example.com/profile.jpg"
}

The tag in the template:

<!-- In the alternative text of an image -->
{d.logoBase64}

will be replaced with the image from your JSON data.

16. Charts

The :chart formatter lets you generate charts using ECharts v5 configuration. Just Insert a placeholder image in your template (DOCX, ODT, etc.), then the tag must be placed in the alternative text of the placeholder image, and finally, chain the tag with the :chart formatter. If your JSON data is:

{
  "salesChart": {
    "type": "echarts@v5",
    "width": 600,
    "height": 400,
    "option": {
      "xAxis": {
        "type": "category",
        "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
      },
      "yAxis": {
        "type": "value"
      },
      "series": [{
        "data": [150, 230, 224, 218, 135, 147, 260],
        "type": "line"
      }]
    }
  }
}

The tag in the template:

<!-- In the alternative text of an image -->
{d.salesChart:chart}

will render the Echart as SVG image in the generated document.

Important Note: All ECharts configuration options are supported, but external scripts or dependencies are not.

17. Barcodes

It is possible to insert barcodes into your documents using the :barcode(type) formatter. The barcode is rendered as an SVG image and can be embedded directly into your template. The option type is required to define the format of barcode expected. How to Use:

Define the barcode data in your JSON.
Insert a placeholder image in your template.
Place the tag in the alternative text of the placeholder image, chain the :barcode(type) formatter (don't forget the type of barcode as argument).

If you JSON is:

{
  "productCode": "123456789",
}

The tag in the template:

<!-- In the alternative text of an image -->
{d.productCode:barcode(ean13)}

Will inject a barcode image as SVG in the generated document.

18. Translations

For multi-language documents, static and dynamic translations are supported using localization dictionaries. During rendering, the language must be provided using the lang option in the report configuration. Both static and dynamic translations rely on the same dictionary.

Static translation: use {t('key')} to translate static text in your template. The translation is based on the language set in the report options.
Dynamic translation: Use the :t formatter to translate dynamic values from your JSON data.

If your JSON is:

{
  "name": "John",
  "status": "pending"
}

AND if the localization dictionary is:

{
  "fr-fr" : { 
    "greeting" : "Bonjour",
    "pending"  : "En cours"
  },
  "en-us" : {
    "greeting" : "Hello",
    "pending"  : "In progress"
  },
}

The tag in the template:

{t('greeting')} {d.name} 👋
Payment Status: {d.status:t}.

will generate the following document if the selected language is fr:

Bonjour John 👋
Payment Status: En cours.

19. Hyperlinks

For inserting clickable links in document, insert a hyperlink in your template, and set the URL to a Carbone tag, e.g., {d.documentationUrl}, that's it. If your JSON is:

{
  "title": {
    "url": "https://carbone.io/documentation",
    "name": "Documentation"
  }
}

The tag in the template with the hyperlink {d.title.url}:

{d.title.name}

will render in the document the title "My Profile", and redirect to the page https://carbone.io/documentation.

20. Electronic Signatures

Two ways are available to inject signatures in documents:

Insert a signature image: using dynamic images.
Use a third-party e-signature service: To do this, prepare your document by placing tags with the :sign formatter where you want signatures to appear. If the JSON is:

{
  "signer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

The tag in the template:

{d.signer:sign}

will generate a document with the signature position and signer details. This information are used by third-party services like DocuSign, Yousign, Signwell, or Documenso to handle the signature process.

Conclusion

We’ve covered the most important and commonly used syntax of Carbone's templating. You can now automate the creation of contracts, reports, invoices, and other documents in many fields: finance, healthcare, accounting, legal, and science, more!

Feel free to join our Official Discord — it’s a friendly place to connect and get help from the Carbone community.

Enjoy creating stunning documents with Carbone! Cheers 🍻

Routage avec RiotJS

Steeve — Sun, 22 Jun 2025 20:00:00 +0000

Cet article traite de la création d'une application Riot couplée avec Riot-Route, la solution officielle de routage côté client de Riot.

Avant de commencer, assurez-vous d'avoir une application de base RiotJS, ou lisez mes articles précédents.

Le routage côté client lie l'URL du navigateur au contenu de la page. Lorsqu'un utilisateur navigue dans l'application Riot, l'URL change sans demander un nouveau front-end à un serveur. Ceci est appelé une SPA, pour Single Page Applications : Riot gère toutes les mises à jour de données et la navigation sans recharger la page, ce qui rend l'application riche et réactive !

Créons l'exemple de routage le plus simple ; ensuite, nous explorerons un usage avancé en production.

Route de base

Nous visons à créer l'application suivante : un Menu à gauche affichant des liens vers différentes pages, et lorsqu'on clic sur un lien, la section de droite affiche la page correspondante. Le style est alimenté par le CSS Material Design BeerCSS :

Écrivez le code suivant dans ./index.riot. Le HTML provient de la documentation BeerCSS, et j'ai ajouté la syntaxe RiotJS pour la logique :

<index-riot>
    <router>
        <nav class="drawer left right-round border">
            <header>
                <nav>
                    <img class="circle" src="./examples/data/img-card.png"/>
                    <h6>Jon Snow</h6>
                </nav>
            </header>
            <!-- These links will trigger automatically HTML5 history events -->
            <a href="/">
                <i>inbox</i>
                <span class="max">Inbox</span>
                <b>24</b>
            </a>
            <a href="/favorite">
                <i>favorite</i>
                <span class="max">Starred</span>
                <b>3</b>
            </a>
            <a href="/sent">
                <i>send</i>
                <span class="max">Sent</span>
                <b>11</b>
            </a>
            <div class="medium-divider"></div>
            <a href="/subscription">
                <i>rocket</i>
                <span>Subscription</span>
            </a>
            <a href="/settings">
                <i>settings</i>
                <span>Settings</span>
            </a>

        </nav>
        <!-- Your application routes will be rendered here -->
        <span style="display:block;margin-left:20px;margin-top:20px">
            <route path="/"> <h2>Inbox</h2> </route>
            <route path="/favorite"> <h2>Starred</h2> </route>
            <route path="/sent"> <h2>Sent</h2> </route>
            <route path="/subscription"> <h2>Subscription</h2> </route>
            <route path="/settings"> <h2>Settings</h2> </route>
        </span>
    </router>
    <script>
        import { Router, Route } from '@riotjs/route'

        export default {
            components: { Router, Route }
        }
    </script>
</index-riot>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/riot-route/index.basic.riot

Cet exemple utilise deux composants fournis par riot-route :

Router : Le <router> enveloppe l'application Riot et détecte automatiquement tous les clics sur les liens qui doivent déclencher un changement de navigation.
Route : Le <route path="/some/route/:params"> rend le contenu de la page si l'attribut path correspond au chemin d'URL actuel. Le path peut accepter des expressions régulières (Regex) ou des paramètres, et vous pouvez accéder à la route actuelle avec l'objet route :

<route path="/:some/:route/:param"> {JSON.stringify(route.params)} </route>

<route path="/search(.*)">
  <!-- Assuming the URL is "/search?q=awesome" -->

  {route.searchParams.get('q')}
</route>

Code Source trouvé sur Riot-Route

Pour accéder à la route actuelle dans la section JavaScript, il est possible d'importer l'objet route depuis '@riotjs/route' :

import { Router, Route, route } from '@riotjs/route'

Route Avancée

Explorons le routage avancé avec les exigences suivantes pour un front-end :

Afficher une page 404 si un chemin d'URL n'existe pas.
Accéder aux paramètres de requête dans chaque composant de page.
Pour chaque route, afficher un composant Riot en tant que page.
Créer un fichier de configuration de routage définissant toutes les routes, chemins et composants.

Dans un premier temps, nous allons créer 6 composants, un pour chaque page et un autre pour la page 404 Not Found. Les composants sont situés dans le répertoire pages :

pages/p-favorite.riot
pages/p-inbox.riot
pages/p-sent.riot
pages/p-settings.riot
pages/p-subscription.riot
pages/p-not-found.riot

Chaque composant possède une seule balise de titre <h2>, par exemple, le composant pages/p-sent.riot ressemble à ceci :

<p-sent>
    <h2>Sent</h2>
</p-sent>

Ou le composant pages/p-not-found.riot ressemble à ceci :

<p-not-found>
    <h2> 404 Page Not Found </h2>
</p-not-found>

Ensuite, créez un fichier de configuration de routage global dans routes.js. Le fichier renvoie une liste de pages, et chaque page possède un nom (name), un chemin avec une expression régulière longue (path), et un composant correspondant (component):

export default [
    {
      name     : 'Inbox',
      href     : '/',
      path     : '/(/?[?#].*)?(#.*)?',
      component: 'p-inbox',
      icon     : 'inbox'
    },
    {
      name     : 'Starred',
      href     : '/favorite',
      path     : '/favorite(/?[?#].*)?(#.*)?',
      component: 'p-favorite',
      icon     : 'favorite'
    },
    {
      name     : 'Sent',
      href     : '/sent',
      path     : '/sent(/?[?#].*)?(#.*)?',
      component: 'p-sent',
      icon     : 'send',
      separator: true
    },
    {
        name     : 'Subscription',
        href     : '/subscription',
        path     : '/subscription(/?[?#].*)?(#.*)?',
        component: 'p-subscription',
        icon     : 'rocket',
    },
    {
      name     : 'Settings',
      href     : '/settings',
      path     : '/settings(/?[?#].*)?(#.*)?',
      component: 'p-settings',
      icon     : 'settings'
    }
  ]

Source code: https://github.com/steevepay/riot-beercss/blob/main/examples/riot-route/routes.js

Le composant <route> de Riot utilisera l'attribut path. Chaque expression régulière est composée de 3 parties :

/settings : Chemin de la page (chaîne statique requise)
(/?[?#].*) : Paramètres de requête (groupe facultatif)
(#.*)? : Fragment, une section au sein d'une page (groupe facultatif)

Maintenant, importez routes.js et tous les composants dans le fichier index.riot : Définissez les composants dans l'objet Riot components:{}, et chargez les routes dans l'objet state:{}:

<index-riot>
    <router>
        <nav class="drawer left right-round border">
            <header>
                <nav>
                    <img class="circle" src="./examples/data/img-card.png"/>
                    <h6>Jon Snow</h6>
                </nav>
            </header>
            <!-- Navigation bar created dynamically -->
            <template each={ page in state.pages }>
                <a href={ page.href }>
                    <i>{ page.icon }</i>
                    <span class="max">{ page.name }</span>
                </a>
                <div if={ page.separator === true } class="medium-divider"></div>
            </template>            
        </nav>
        <!-- Your application components/routes will be rendered here -->
        <span style="display:block;margin-left:20px;margin-top:20px">
            <route each={ page in state.pages  } path={ page.path }>
                <span is={ page.component } route={ route }></span>
            </route>
            <p-not-found if={ state.showNotFound } />
        </span>
    </router>
    <script>
        import { Router, Route, route, toRegexp, match } from '@riotjs/route';
        import pages from './routes.js'

        import pInbox from "./pages/p-inbox.riot";
        import pFavorite from "./pages/p-favorite.riot";
        import pSent from "./pages/p-sent.riot"
        import pSettings from "./pages/p-settings.riot"
        import pSubscription from "./pages/p-subscription.riot"
        import pNotFound from "./pages/p-not-found.riot"

        export default {
            components: { Router, Route, pInbox, pFavorite, pSent, pSettings, pSubscription, pNotFound },
            state: {
                pages,
                showNotFound: false
            },
            onMounted (props, state) {
                // ROUTING: create a stream on all routes
                this.anyRouteStream = route('(.*)')
                // ROUTING: check any route change to understand if the not found site should be displayed
                this.anyRouteStream.on.value((path) => {
                    this.update({ showNotFound: !this.state.pages.some(p => match(path.pathname, toRegexp(p?.path))) })  
                })
            },
            onUnmounted() {
                this.anyRouteStream.end()
            }
        }
    </script>
</index-riot>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/riot-route/index.advanced.riot

Ce code diffère beaucoup de l'exemple de base ; voici les principaux changements :

Pour imprimer un composant pour chaque page, une boucle est créée sur state.pages. Au sein de chaque <route></route>, les éléments HTML span sont utilisés comme composants Riot en ajoutant l'attribut is :

<route each={ page in state.pages  } path={ page.path }>
   <span is={ page.component } route={ route }></span>
</route>

Les liens du menu sont également générés grâce à la configuration de route, accessible avec state.pages:

<template each={ page in state.pages }>
   <a href={ page.href }>
      <i>{ page.icon }</i>
      <span class="max">{ page.name }</span>
   </a>
   <div if={ page.separator === true } class="medium-divider"></div>
</template>

L'objet route est utilisé dans la partie JavaScript pour vérifier si l'URL actuelle existe : Un Stream de routes est créé pour écouter les changements de route dans le onMounted () {} hook (cycle de vie Riot). Lorsqu'une route change, une fonction vérifie si l'URL correspond à une route existante :

onMounted (props, state) {
  this.anyRouteStream = route('(.*)')
  this.anyRouteStream.on.value((path) => {
     this.update({ showNotFound: !this.state.pages.some(p => match(path.pathname, toRegexp(p?.path))) })  
  })
},
onUnmounted() {
  // When the component is unmounted, the stream is stopped.
  this.anyRouteStream.end()
}

Pour chaque composant, la route actuelle est passée en tant que Props:

<span is={ r.component } route={ route }></span>

Au sein de chaque composant, la route est accessible avec props.route, par exemple dans le fichier c-inbox.riot :

<p-inbox>
    <h2> Inbox </h2>
    <span>Filter: { props.route.searchParams.get('filter') }</span><br>
    <span>Order By: { props.route.searchParams.get('order') }</span>
</p-inbox>

Vous pouvez maintenant utiliser les paramètres de requête pour demander une API lorsque la page est chargée dans le onMounted(){} hook (cycle de vie Riot).

Conclusion

Riot Route vous permet de créer la navigation facilement, avec une syntaxe toujours proche des standards HTML.

Une limitation des applications monopages est qu'elles dépendent d'un backend/API pour charger les données. Le navigateur/utilisateur doit attendre que le contenu soit rendu. Pour contrer ce problème, vous pouvez rendre le HTML côté serveur avec Riot-SSR : la requête reçoit la page directement remplie de données.

Passez une excellente journée ! Santé 🍻

Partage de données entre composants Riot avec Riot-Meiosis (State Manager)

Steeve — Mon, 16 Jun 2025 12:00:00 +0000

Cet article explique comment créer un gestionnaire d'état (state manager) pour partager des données entre plusieurs composants RiotJS.

Avant de commencer, assurez-vous d'avoir une application de base Riot, ou lisez mes articles précédents. Je suppose que vous avez une compréhension fondamentale de Riot ; cependant, n'hésitez pas à vous référer à la documentation si nécessaire : https://riot.js.org/documentation/

Il existe trois méthodes pour partager des données entre composants :

Utiliser les propriétés Riot (props) pour passer des valeurs à un composant enfant. Le composant enfant doit émettre des événements vers le composant parent si une action se produit, comme un clic ou un changement d'entrée. Dans ce cas, la portée de communication est limitée : du composant parent vers l'enfant et de l'enfant vers le parent.
Utiliser un émetteur d'événements comme Mitt, un modèle de messagerie appelé Pub/Sub, en savoir plus dans mon article précédent.
Dernière méthode : un gestionnaire d'état : Un état global partagé et accessible par tous les composants. Dans d'autres frameworks frontaux, vous avez peut-être entendu parler de Pinia pour Vuejs ou Redux pour React. Pour RiotJS, le gestionnaire d'état est riot-meiosis.

Meiosis est un modèle de gestionnaire d'état utilisant des flux (streams) pour communiquer des valeurs, avec le principe de rendre l'utilisation très simple. Extrait de la documentation Meiosis :

L'idée est d'avoir un objet unique, de niveau supérieur, qui représente l'état de votre application, et d'avoir une manière simple de mettre à jour cet état. Les vues sont rendues en fonction de l'état et déclenchent des actions pour mettre à jour l'état. C'est tout !

Riot-meiosis reproduit ce modèle et est dédié à RiotJS. Cet article montre comment l'utiliser. L'objectif est de :

Étape 1 : Créer un gestionnaire d'état global
Étape 2 : Sur la page d'accueil de l'application Riot, afficher une carte accueillant une personne avec son prénom et son nom.
Étape 3 : Afficher un dialogue pour modifier le prénom et le nom.
Étape 4 : Sauvegarder les nouvelles valeurs dans l'état global

Configuration de Riot Meiosis

Commencez par installer le package NPM dans votre projet Riot/Vite :

npm i --save @riot-tools/meiosis

Ensuite, créez un fichier store.js, qui sera l'état global :


import { RiotMeiosis } from '@riot-tools/meiosis';

const state = {
  firstname     : 'Jon',
  lastname      : 'Snow',
  firstnameEdit : '',
  lastnameEdit  : '',
  displayForm   : false
}

/** Create the state manager instance */
const stateManager = new RiotMeiosis(state, { flushOnRead: false, statesToKeep: 1 });

/** Extract the state stream **/
const { stream } = stateManager;

/** Add Root state reducer: merge the old and new state objects */
stream.addReducer((newState, oldState) => {
    // Object oldState { firstname: "John", lastname: "Wick", firstnameEdit: "", lastnameEdit: "", email: "", displayForm: false } 
    // Object newState { displayForm: true }
    return {
        ...oldState,
        ...newState
    }
});

export default { 
    /** Simplifying the connect function for components */
    connect: function (component) {
        return stateManager.connect((globalState, ownState) => ({ ...ownState, ...globalState }))(component)
    },
    /** Provides the dispatch function to update values */
    dispatch: stateManager.dispatch
};

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/meiosis/store.js

Détails du code :

Un réducteur est créé pour fusionner l'état global avec les nouvelles valeurs provenant de tous les composants.
Pour connecter le composant à l'état global, le composant Riot doit être enveloppé avec la fonction store.connect(), et passer un composant et une fonction de fusion comme argument : cela fusionnera l'état du composant avec l'état global. Pour chaque composant, l'état global est accessible avec l'expression this.state.value.
Le store renvoie la connexion et la fonction dispatch utilisée pour mettre à jour les valeurs.
L'état global est initialisé avec un prénom et nom, un second prénom et nom pour les entrées du dialogue afin de modifier le profil, et un booléen displayForm pour afficher le dialogue.

Écrivez le code HTML dans c-welcome-card.riot, et connectez le Store au composant:

<c-welcome-card>
    <article class="no-padding border round">
        <img class="responsive small top-round" src="./examples/data/img-card.png">
        <div class="padding">
            <h5>Welcome</h5>
            <p>Bonjour <b>{ state.firstname} { state.lastname }</b> 👋 to our app! We're excited to have you here.Whether you're in finance, marketing, or operations, our app delivers the insights you need to drive growth and stay ahead of the competition.</p>
            <nav>
                <button onclick={ editProfile }>Edit Profile</button>
            </nav>
        </div>
    </article>
    <script>
        import store from "./store.js";

        export default store.connect({
            editProfile () {
                store.dispatch({ 
                    displayForm: true,
                    firstnameEdit: this.state.firstname,
                    lastnameEdit: this.state.lastname,
                })
            }
        })

    </script>
</c-welcome-card>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/meiosis/c-welcome-card.riot

Détails du code :

Le Store est chargé, et le composant est connecté avec store.connect().
Pour mettre à jour l'une des valeurs du magasin global, appelez la fonction store.dispatch().
Lorsque le bouton est cliqué, la fonction editProfile() est déclenchée pour afficher le dialogue et définir firstnameEdit et lastnameEdit.

Créez un fichier nommé c-form.riot, et connectez le Store pour accéder aux valeurs firstnameEdit et lastnameEdit. Il sera utilisé pour les inputs:

<c-form>
    <c-dialog active={  state.displayForm } oncancel={ close } onconfirm={ confirmEdit }>
        <template slot="body">
            <h5 style="margin-bottom:30px">Edit Profile</h5>
            <c-input value={ state.firstnameEdit } onkeyup={ (ev) => updateInput(ev, 'firstnameEdit') } onchange={ (ev) => updateInput(ev, 'firstnameEdit') } outlined="true" round="true" placeholder="Firstname" />
            <c-input value={ state.lastnameEdit } onkeyup={ (ev) => updateInput(ev, 'lastnameEdit') } onchange={ (ev) => updateInput(ev, 'lastnameEdit') }  outlined="true" round="true" placeholder="Lastname"  />
        </template>
    </c-dialog>
    <script>
        /** State manager **/
        import store from './store.js';
        /** Components **/
        import cInput from '../../components/c-input.riot';
        import cButton from '../../components/c-button.riot';
        import cDialog from '../../components/c-dialog.riot';

        export default store.connect({
            components: {
                cInput,
                cButton,
                cDialog
            },
            close() {
                store.dispatch({ displayForm: false })
            },
            updateInput(ev, keyName) {
                store.dispatch({ [keyName]: ev?.target?.value ?? '' })
            },
            confirmEdit() {
                store.dispatch({ 
                    displayForm: false, 
                    firstname: this.state.firstnameEdit,
                    lastname: this.state.lastnameEdit
                })
            }
        });
    </script>
</c-form>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/meiosis/c-form.riot

Détails du code :

Trois composants personnalisés sont chargés : un Input, un Dialog, et un bouton.
Le dialogue affiche deux composants d'entrée pour mettre à jour firstnameEdit et lastnameEdit.
Si le bouton confirmer est cliqué, les nouvelles valeurs sont sauvegardées dans l'état global firstname et lastname grâce à la fonction store.dispatch. La carte de bienvenue reçoit la mise à jour ; le prénom et le nom sont rafraîchis.

Pourquoi utiliser firstnameEdit/lastnameEdit et non directement firstname/lastname ? Lorsqu'un utilisateur saisit de nouveaux noms, il peut annuler à tout moment l'édition sans affecter firstname/lastname. Le changement de valeur ne prend effet que lorsqu'un bouton confirmer est cliqué.

Maintenant, nous pouvons charger les deux composants dans un fichier commun index.riot:

<index-riot>
    <div style="width:400px;padding:40px;">
        <c-welcome-card />
        <c-form />
    </div>
    <script>

        import cForm from "./c-form.riot"
        import cWelcomeCard from "./c-welcome-card.riot"

        export default {
            components: {
                cForm,
                cWelcomeCard
            }
        }
    </script>
</index-riot>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/meiosis/index.riot

Les deux composants sont indépendants, ne communiquant que par le gestionnaire d'état global.

Conclusion

Un gestionnaire d'état est très puissant pour lire et mettre à jour des données entre les composants Riot. Les données peuvent être des listes, des objets ou des cartes. Le magasin peut être connecté à un nombre illimité de composants pour de grandes applications frontales de production réalisées avec RiotJS !

Partage de données entre composants RiotJS avec Mitt (émetteur d'évènements)

Steeve — Mon, 09 Jun 2025 12:00:00 +0000

Cet article traite de l'utilisation des événements avec Mitt entre plusieurs composants Riot pour partager des données.

Avant de commencer, assurez-vous d'avoir une application de base RiotJS, ou lisez mes articles précédents.

Je suppose que vous avez une compréhension fondamentale de Riot ; cependant, n'hésitez pas à vous référer à la documentation si nécessaire : https://riot.js.org/documentation/

Il existe trois méthodes pour partager des données entre composants :

Utiliser les propriétés Riot props pour passer des valeurs à un composant enfant. Le composant enfant doit émettre des événements vers le composant parent si une action se produit, comme un clic ou un changement d'entrée. Dans ce cas, la portée de communication est limitée: du composant parent vers l'enfant et de l'enfant vers le parent.
Utiliser un gestionnaire d'état (state manager), comme Pinia pour Vuejs ou Redux pour React, pour partager un état entre les composants/pages. La portée de communication est globale: tous les composants peuvent voir et modifier les états.

La dernière méthode utilise un émetteur d'événements comme Mitt, un modèle de messagerie appelé Pub/Sub : un ou plusieurs éditeurs émettent les données, et les abonnés les traite sans savoir quels sont les éditeurs. Cet article reproduit le modèle entre plusieurs composants RiotJS ! L'objectif est de :

Étape 1 : Créer une application Riot de base affichant un composant Modal de Confirmation lors du clic sur un bouton. Le bouton est l'éditeur, et le Modal est l'abonné.
Étape 2 : Lorsque le modal est visible et soit validé soit annulé, il émet un événement vers l'éditeur d'origine. Dans ce cas, le Modal est l'éditeur, et le Bouton est l'abonné.

Base de l'émetteur

Commencez par installer Mitt dans votre projet Riot/Vite :

$ npm install mitt

Créez un fichier nommé events.js, puis chargez Mitt et instanciez-le :

/** EVENT BUS **/
import mitt from 'mitt'

const _bus = mitt();

export default _bus;

Composant de Dialogue (Abonné)

Créez un composant de dialogue nommé c-dialog.riot. La base du composant est tirée de mon article précédent Créer un composant de dialogue avec RiotJS:

<c-dialog>
    <dialog class="{state.active ? 'active ' : null}">
        <h5>{ state.title }</h5>
        <div>
            { state.message }
        </div>
        <nav class="right-align no-space">
            <button onclick={ toggleModal } class="transparent link">{ state.cancel }</button>
            <button onclick={ validateAction } class="transparent link">{ state.validate }</button>
        </nav>
    </dialog>
       <script>
       import events from './events.js'

        export default {
            state: {
                active: false,
                title: 'Confirmation',
                message: 'Are you sure?',
                callbackID : '',
                args : true,
                validate : 'Validate',
                cancel: "Cancel"
            },
            onMounted() {
                events.on('open-modal-validation', this.openModalValidation);
            },
            onUnmounted() {
                events.off('open-modal-validation', this.openModalValidation);
            },
            validateAction () {
                if (this.state.callbackID) {
                    events.emit(this.state.callbackID, this?.state?.args);
                }
                this.toggleModal();
            },
            openModalValidation ({ message, callbackID, args }) {
                this.update({
                    message,
                    callbackID,
                    args: args ?? true
                })
                this.toggleModal();
            },
            toggleModal() {
                this.update({ active: !this.state.active })
                if (this.state.active === true) {
                    console.log("Modal opened.")
                } else {
                    console.log("Modal closed.")
                }
            }
        }
    </script>
</c-dialog>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/mitt/c-dialog.riot

Détails du code :

Le modal est visible uniquement si state.active est true.
Le dialogue peut être personnalisé avec des données personnalisées, stockées dans l'objet State Riot.
Le bus d'événements est chargé avec import events from './events.js'.
Lorsque le composant est monté, il s'abonne à l'événement open-modal-validation grâce à events.on('open-modal-validation', this.openModalValidation);. Lorsque l'événement nommé open-modal-validation se produit, il exécute la fonction openModalValidation.
La fonction openModalValidation bascule la visibilité du modal en définissant state.active sur true. En même temps, elle recueille des données supplémentaires telles qu'un state.message personnalisé et un state.callbackID.
Si le bouton de validation est cliqué, il émet un événement vers state.callback avec des arguments personnalisés state.args ; cela peut être un objet ou une chaîne de caractères.
Si le bouton d'annulation est cliqué, le modal est désactivé en définissant state.active sur false.

Composant Index (Éditeur)

Enfin, chargez le Dialogue et un Bouton dans un fichier index.riot:

<index-riot>
    <div style="width:600px;padding:20px;">
        <c-dialog />
        <c-button onclick={ confirmDeletion }> Delete File </c-button>
    </div>
    <script>
        import cButton from "../../components/c-button.riot";
        import cSnackbar from "../../components/c-snackbar.riot";
        import cDialog from "./c-dialog.riot";

        import events from "./events.js"

        export default {
            components: {
                cButton,
                cDialog
            },
            onMounted() {
                events.on('delete-file', this.deleteFile);
            },
            onUnmounted() {
                events.off('delete-file', this.deleteFile);
            },
            state: {
                active: false
            },
            confirmDeletion () {
                events.emit('open-modal-validation', { 
                    message: "Do you confirm you want to delete the file \"2024-04-invoice.pdf\"?",
                    callbackID: 'delete-file'
                });
            },
            deleteFile () {
                console.log("FILE DELETED! 🗑️");
            }
        }
    </script>
</index-riot>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/mitt/index.riot

Détails du code :

Les composants sont importés avec import cDialog from "./components/c-dialog.riot"; puis chargés dans l'objet Riot components:{}.
Le composant dialog est instancié avec dans le HTML.
L'émetteur d'événements, Mitt, est chargé avec import events from "./events.js".
Lors du clic sur le bouton, la fonction confirmDeletion est exécutée et émet l'événement "open-modal-validation". Le Dialogue est maintenant visible ! Simultanément, un message personnalisé et l'ID de l'abonné "delete-file" sont passés en tant qu'arguments pour l'événement.
Lorsque le bouton du dialogue est cliqué, un événement est émis, en utilisant state.callbackID comme destinataire de l'abonné.

Cette méthode peut être étendue en créant plus de boutons (éditeurs) émettant vers un seul Dialogue (abonné), par exemple :

Voici le code de index.riot pour reproduire la démo GIF :

<index-riot>
    <div style="width:600px;padding:50px;">
        <c-dialog />
        <c-button onclick={ confirmDeletion }> Delete File </c-button>
        <c-button onclick={ confirmDeletionBucket }> Delete Bucket </c-button>
        <c-button error={ true } onclick={ confirmDeletionAccount }> Delete Account </c-button>
    </div>
    <script>
        import cButton from "../../components/c-button.riot";
        import cSnackbar from "../../components/c-snackbar.riot";
        import cDialog from "./c-dialog.riot";

        import events from "./events.js"

        export default {
            components: {
                cButton,
                cDialog
            },
            onMounted() {
                events.on('delete-file', this.deleteFile);
                events.on('delete-bucket', this.deleteBucket);
                events.on('delete-account', this.deleteAccount);
            },
            onUnmounted() {
                events.off('delete-file', this.deleteFile);
                events.off('delete-bucket', this.deleteBucket);
                events.off('delete-account', this.deleteAccount);
            },
            state: {
                active: false
            },
            getRandomNumber() {
                return Math.floor(Math.random() * Date.now())
            },
            confirmDeletion () {
                events.emit('open-modal-validation', { 
                    message: "Do you confirm you want to delete the File \"2024-04-invoice.pdf\"?",
                    callbackID: 'delete-file',
                    args: "file-" + this.getRandomNumber()
                });
            },
            confirmDeletionBucket() {
                events.emit('open-modal-validation', { 
                    message: "Are you sure you want to delete this S3 bucket \"2024-assets\"? This action is irreversible.",
                    callbackID: 'delete-bucket',
                    args: "bucket-" + this.getRandomNumber()
                });
            },
            confirmDeletionAccount() {
                events.emit('open-modal-validation', { 
                    message: "Are you sure you want to proceed with deleting your account? This action is irreversible and will permanently remove all your personal data associated with the account.",
                    callbackID: 'delete-account',
                    args: "account-" + this.getRandomNumber()
                });
            },
            deleteFile (id) {
                console.log("%c File deleted! ID: " + id, 'background: #222; color: #bada55');
            },
            deleteBucket (id) {
                console.log("%c Bucket deleted! ID: " + id, 'background: #222; color: #ff00ff');
            },
            deleteAccount (id) {
                console.log("%c Account deleted! ID: " + id, 'background: #222; color: #ff0000');
            }
        }
    </script>
</index-riot>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/mitt/index.riot

Détails du code :

Dans le onMounted Riot Hook, trois événements sont écoutés et redirigés vers trois fonctions : deleteFile, deleteBucket ou deleteAccount. Dans une application de production, cela pourrait être un appel API pour supprimer une ressource (fichier ou élément dans une base de données).
Trois boutons sont créés dans le HTML, et chaque clic émet l'événement open-modal-validation et passe un message personnalisé, un ID de rappel et un argument :
- Le callbackID est un événement à émettre lorsque le bouton de validation est cliqué.
- Les args sont utilisés pour passer un ID de ressource d'une API ou d'une base de données, comme un ID de fichier ou un ID de compte. Dans notre cas, un ID aléatoire est passé en tant qu'argument.
Lorsque qu'un bouton du composant Dialogue est validé, il émet callbackID en tant qu'événement, et la fonction correspondante est exécutée pour supprimer le fichier, le bucket ou le compte.
Lorsque le composant est retiré de la page web, tout événement doit être écouté : Lorsque le onUnmounted](https://riot.js.org/api/#component-object) Riot hook est exécuté, event.off supprime l'abonnement à l'événement.

Conclusion

Au lieu de créer un Dialogue pour chaque bouton, un seul Dialogue suffit pour plusieurs boutons avec le modèle pub/sub. Maintenant, un composant peut écouter et émettre des événements pour communiquer des données basées sur des actions. Voilà 🎉

Passez une excellente journée ! Santé 🍻

Composant Stepper avec RiotJS

Steeve — Mon, 02 Jun 2025 12:00:00 +0000

Cet article traite de la création d'un composant Stepper (étapes) avec RiotJS, en utilisant le CSS Material Design BeerCSS. Avant de commencer, assurez-vous d'avoir une application Riot, ou lisez mes articles précédents.

Je suppose que vous avez une compréhension fondamentale de Riot ; cependant, n'hésitez pas à vous référer à la documentation si nécessaire : https://riot.js.org/documentation/

Les steppers, ou "étapes" en Français, affichent la progression à travers un processus multi-étapes. Les utilisateurs savent intuitivement où ils en sont dans le processus et combien d'étapes restent, par exemple, un flux de paiement, une connexion ou un formulaire.

Base du composant Stepper

L'objectif est de créer une application Riot avec un Stepper qui montre une progression lorsqu'un bouton est cliqué et affiche la page correspondante.

Ouvrez le fichier index.riot à la racine de votre projet Vite, puis ajoutez le code suivant. Le HTML provient de la documentation BeerCSS et j'ai ajouté la syntaxe RiotJS pour la logique :

<index-riot>
    <div style="width:800px;padding:20px;">
        <nav class="scroll">
            <button class="circle small"  onclick={ () => changeStep(1)}>
                <template if={ state.active === 1 }>1</template>
                <i if={ state.active > 1}>done</i>
            </button>
            <div class="max divider"></div>
            <button class="circle small" disabled={ state.active < 2 } onclick={ () => changeStep(2)}>
                <template if={ state.active <= 2 }>2</template>
                <i if={ state.active > 2}>done</i>
            </button>
            <div class="max divider"></div>
            <button class="circle small" disabled={ state.active < 3 } onclick={ () => changeStep(3)}>
                <template if={ state.active <= 3 }>3</template>
                <i if={ state.active > 3}>done</i>
            </button>
        </nav>
        <br>
        <div class="page padding { state.active === 1 ? 'active' : null}" if={ state.active === 1 }>
            <h5>Page { state.active }</h5><br>
            <button onclick={ () => { changeStep(2) }}>Next</button>
        </div>
        <div class="page padding { state.active === 2 ? 'active' : null}" if={ state.active === 2 }>
            <h5>Page { state.active }</h5><br>
            <button onclick={ () => { changeStep(3) }}>Next</button>
        </div>
        <div class="page padding { state.active === 3 ? 'active' : null}" if={ state.active === 3 }>
            <h5>Page { state.active }</h5><br>
            <button onclick={ () => { changeStep(4) }}>Next</button>
        </div>
        <div class="page padding { state.active === 4 ? 'active' : null}" if={ state.active === 4 }>
            <h5>Done!</h5>
        </div>
    </div>
    <script>
        export default {
            state: {
                active: 1,
            },
            changeStep(value) {
                this.update({
                    active: value
                })
            }
        }
    </script>
</index-riot>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/index.stepper.riot

Décomposons le code :

Le Stepper est composé de boutons et de séparateurs, l'état d'une étape est défini par :
- Complété : lorsque l'icône de validation est affichée et que le numéro est masqué avec <template if={ state.active === 1 }>1</template>.
- En cours de complétion : lorsque le numéro est affiché et que l'icône de validation est masquée avec <i if={ state.active > 1}>done</i>.
- Étape suivante à venir : lorsque le bouton est désactivé avec la condition disabled={ state.active < 2 }.
L'état du Stepper est stocké dans un objet Riot state:{} sous la valeur state.active.
state.active affichera les pages 1, 2 ou 3 avec l'expression <div class="page padding" if={ state.active === 1 }>.
Si l'un des boutons d'étape est cliqué, il mettra à jour directement state.active avec le numéro de l'étape sélectionnée : La fonction changeStep est déclenchée lorsque l'événement "Click" est capturé, comme : onclick={ () => changeStep(1)}. Changer l'étape peut être utilisé pour requêter une API et/ou charger ensuite une page spécifique.

Test du composant Stepper

Il existe deux méthodes pour tester le composant Stepper, couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant Stepper Riot en utilisant des éléments Material Design avec BeerCSS. N'hésitez pas à commenter si vous avez des questions ou besoin d'aide avec RiotJS.

Passez une excellente journée ! Santé 🍻

Composant Menu avec RiotJS

Steeve — Mon, 26 May 2025 12:00:00 +0000

Cet article traite de la création d'un composant de menu avec RiotJS, en utilisant le CSS Material Design BeerCSS. Avant de commencer, assurez-vous d'avoir une application Riot, ou lisez mes articles précédents de la série.

Je suppose que vous avez une compréhension fondamentale de Riot ; cependant, n'hésitez pas à vous référer à la documentation si nécessaire : https://riot.js.org/documentation/

Un menu s'ouvre lors de l'interaction avec un élément (comme une icône, un bouton ou un champ de saisie) ou lorsque les utilisateurs effectuent une action spécifique. Le menu affiche une liste de choix sur une surface temporaire, permettant aux utilisateurs de faire une sélection pour exécuter des actions.

Base du composant de menu

L'objectif est de créer une application Riot avec un menu apparaissant lorsqu'un bouton est cliqué, de le masquer lorsqu'un élément est cliqué, et d'exécuter une action. Bonus : Masquer le menu lorsqu'un clic se produit en dehors du composant.

Pour afficher un menu lorsqu'un bouton est cliqué : Le menu fait partie du composant Button, en tant que Slot. La balise <slot> de Riot injecte des modèles HTML personnalisés dans un composant enfant à partir de son parent.

Le code suivant du composant Bouton est utilisé pour rendre le menu visible, situé dans ./components/c-button.riot. Le HTML provient de la documentation BeerCSS et j'ai ajouté la syntaxe RiotJS pour la logique :

<c-button>
  <button>
    <span><slot></slot></span>
    <i icon={ props?.icon }>props?.icon</i>
    <slot name="menu"></slot>
  </button>
</c-button>

Cliquez ici pour en apprendre plus sur créer un composant Button

Décomposons le code :

Les balises <c-button> et </c-button> définissent une balise racine personnalisée, portant le même nom que le fichier. Vous devez l'écrire ; sinon, cela pourrait créer des résultats inattendus. Utiliser la balise <button></button> comme balise racine ou redéfinir des balises HTML natives est une mauvaise pratique ; commencer par c- est une bonne convention.
L'étiquette du bouton est passée en tant que Slot.
Le menu est passé en tant que Slot nommé "Menu" : <slot name="menu"></slot>.
Une icône optionnelle peut être passée en tant qu'attribut si props.icon existe ; elle affichera une icône Google Font.

Enfin, chargez et instanciez c-button.riot dans une page principale nommée index.riot:

<index-riot>
    <div style="width:600px;padding:20px;">
        <c-button icon="arrow_drop_down" onclick={ (ev) => toggle(ev, 'button') } onfocusout={ () => update({ active: false })}>
            Menu
            <template slot="menu">
                <menu  class="no-wrap{ state.active === true ? ' active' : ''}">
                    <a class="row" onclick={ (ev) => toggle(ev, 'item1') }>
                        <i>visibility</i>
                        <span class="max">Item 1</span>
                    </a>
                    <a class="row" onclick={ (ev) => toggle(ev, 'item2') }>
                        <i>content_copy</i>
                        <span class="max">Item 2</span>
                        <span>⌘C</span>
                    </a>
                    <a class="row" onclick={ (ev) => toggle(ev, 'item3') }>
                        <i>edit</i>
                        <span class="max">Item 3</span>
                    </a>
                    <div class="small-divider"></div>
                    <a class="row" onclick={ (ev) => toggle(ev, 'item4') }>
                        <img class="circle tiny" src="../favicon.png">
                        <div class="max">
                            <div>Item 4</div>
                            <label>Some text here</label>
                        </div>
                    </a>
                </menu>
            </template>
        </c-button>
    </div>
    <script>
        import cButton from "../components/c-button.riot"

        export default {
            components: {
                cButton
            },
            state: {
                active: false
            },
            toggle (ev, origin) {
                ev.stopPropagation();
                ev.preventDefault();
                // Hide the menu
                this.update({ active: this.state.active === true ? false : true })
                if (origin === 'item1') {
                    // do something
                } else if (origin === 'item2') {
                    // do something else
                }
            }
        }
    </script>
</index-riot>

Code Source: https://github.com/steevepay/riot-beercss/blob/main/examples/index.menu.riot

Détails du code :

Le composant est importé avec import cButton from "./components/c-button.riot"; puis chargé dans l'objet Riot components:{}.
Le composant button est instancié avec <c-button> dans le HTML.
Le menu est passé en tant que slot dans une balise HTML <menu>.
Chaque élément de la liste a l'architecture suivante, enveloppée dans une balise <a> avec une icône et une étiquette : <a class="row"><i>icon</i><span class="max">Label</span></a>.
L'état du menu est stocké dans un objet Riot state:{}, via la variable booléenne state.active.
Pour rendre le menu visible, le menu doit contenir la classe "active" : Lorsque state.active est vrai (true), il applique la classe "active" ; sinon, il n'applique rien.
Lorsqu'un clic se produit sur le bouton, la fonction toggle est exécutée pour attribuer le booléen opposé à state.active. En même temps, une chaîne est passée à la fonction toggle pour définir l'origine du clic, soit : button, soit un élément du menu. Grâce à l'origine, une fonction spécifique peut être exécutée : appels API, ouverture d'une page, et toute autre action !
Lorsqu'un clic se produit en dehors du menu, l'événement "focusout" est capturé pour masquer le menu avec l'expression : onfocusout={ () => update({ active: false })}.
Un élément du menu peut avoir un style différent, par exemple, le dernier élément de la liste affiche une image au lieu d'une icône, suivie d'un titre et d'un sous-titre. Trouvez tous les exemples de menu sur la documentation des menus BeerCSS.

Test du composant de menu

Il existe deux méthodes pour tester le composant de menu, couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant de menu Riot en utilisant des éléments Material Design avec BeerCSS. Le code source de la barre de menu est disponible sur Github : https://github.com/steevepay/riot-beercss/blob/main/components/c-menu.riot

Passez une excellente journée ! Santé 🍻

Composant Snackbar avec RiotJS

Steeve — Mon, 19 May 2025 12:00:00 +0000

Cet article traite de la création d'un composant Snackbar avec Riot, en utilisant le CSS Material Design BeerCSS, et de l'exécution d'une action lors des événements d'entrée et de sélection.

Avant de commencer, assurez-vous d'avoir une application de base Riot, ou consultez mes articles précédents.

Les Snackbars communiquent des messages en bas de l'écran, qui sont minimalement interruptifs et ne nécessitent pas d'action de l'utilisateur. Ils peuvent contenir une seule action, telle que "Annuler", "Ouvrir", ou "En savoir plus".

Base du Composant Snackbar

L'objectif est de créer une application Riot avec une Snackbar apparaissant lorsqu'un bouton est cliqué, et de la faire disparaître automatiquement lorsque l'action est cliquée.

Tout d'abord, créez un nouveau fichier nommé c-snackbar.riot dans le dossier des composants. Le préfixe c- signifie "composant", une convention de nommage utile et une bonne pratique.

Écrivez le code suivant dans ./components/c-snackbar.riot. Le HTML provient de la documentation BeerCSS et j'ai ajouté la syntaxe RiotJS pour la logique :

<c-snackbar>
    <div class="
            snackbar
            { props?.active ? 'active ' : null }
            { props?.top ? 'top ' : null }
            { props?.bottom ? 'bottom ' : null }
            { props?.error ? 'error ' : null }
            { props?.primary ? 'primary ' : null }
            { props?.secondary ? 'secondary ' : null }
            { props?.tertiary ? 'tertiary ' : null }
        ">
        <i if={ props?.icon }>{props.icon}</i>
        <span class="max"><slot></slot></span>
        <a if={ props?.action } onclick={ clicked } class="inverse-link">{ props?.action }</a>
    </div>
    <script>
        export default {
            clicked (e) {
                e.preventDefault();
                e.stopPropagation();
                this.root.dispatchEvent(new Event("action"));
            }
        }
    </script>
</c-snackbar>

Source Code: https://github.com/steevepay/riot-beercss/blob/main/components/c-snackbar.riot

Expliquons le code :

Les balises <c-snackbar> et </c-snackbar> définissent une balise racine personnalisée, portant le même nom que le fichier. Vous devez l'écrire ; sinon, cela pourrait créer des résultats inattendus. Utiliser la balise <div></div> comme balise racine ou redéfinir des balises HTML natives est une mauvaise pratique, donc commencer par c- est une bonne convention.
Le message est passé en tant que balise Slot <slot></slot>, une fonctionnalité centrale de Riot.js permettant d'injecter des modèles HTML personnalisés dans un composant enfant depuis son parent. Dans notre cas, seule une chaîne est injectée, sans HTML.
Les Snackbars peuvent afficher un bouton permettant aux utilisateurs d'agir (Call to action) sur un processus effectué par l'application : Si l'attribut props.action existe, le message est affiché à l'intérieur du bouton d'action.
Lorsque le bouton d'action est cliqué : L'événement click est capturé et exécute la fonction clicked pour émettre un événement personnalisé nommé action.
Pour afficher la Snackbar, elle doit contenir la classe active : lorsque l'attribut props.active existe, il ajoute la classe active grâce à l'expression : { props?.active ? 'active ' : null }.
Différents styles sont disponibles pour le composant, par exemple, primary est appliqué si props?.primary existe et est vrai.

Enfin, chargez et instanciez le composant c-snackbar.riot dans une page principale nommée index.riot:

<index-riot>
    <div style="width:600px;padding:20px;">
        <c-button onclick={ () => openSnack("default") } inverse={ true }>Default</c-button>
        <c-button onclick={ () => openSnack("error") } error={ true }>Error</c-button>
        <c-button onclick={ () => openSnack("primary") } primary={ true }>Primary</c-button>

        <c-snackbar 
            active={ state.active }
            onaction={ close }
            error={ state.error } 
            icon={ state.icon } 
            action={ state.action }
            primary={ state.primary }
        >
            { state.message }
        </c-snackbar>
    </div>
    <script>
        import cButton from "../components/c-button.riot"
        import cSnackbar from "../components/c-snackbar.riot"

        export default {
            components: {
                cSnackbar,
                cButton
            },
            state: {
                active: false,
                icon: null,
                message: null,
                error: null,
                timeout: null
            },
            openSnack(type) {
                if (this.state.active === true) {
                    return;
                }
                this.update({ 
                    active: true,
                    message: type === 'error' ? "Something went wrong." : "Email Archived.",
                    action: type === 'error' ? "Contact Support" : "Undo",
                    icon: type === 'error' ? 'error' : 'check',
                    error: type === 'error',
                    primary: type === 'primary'
                })
                clearTimeout(this.state.timeout)
                this.state.timeout = setTimeout(() => {
                    this.update({ active: false })
                }, 3000)
                this.update();
            },
            close () {
                this.update({ active: false })
            }
        }
    </script>
</index-riot>

Source Code: https://github.com/steevepay/riot-beercss/blob/main/examples/index.snackbar.riot

Détails du code :

Le composant est importé avec import cSnackbar from "./components/c-snackbar.riot"; puis chargé dans l'objet Riot components:{}. Un composant Button est également chargé dans la page : lorsqu'un clic se produit, il affiche le toaster avec un message personnalisé !
Le composant snackbar est instancié avec <c-snackbar /> dans le HTML.
L'état du composant, tel que active, est stocké dans l'objet Riot state:{} sous la propriété booléenne state.active. La propriété est passée en tant qu'attribut, comme : <c-snackbar active={ state.active } />. Pour rendre le toaster complètement interactif, d'autres états sont stockés : le message, l'icône et le libellé de l'action.
Lorsqu'un bouton est cliqué, la fonction openSnack est exécutée grâce à onclick={ () => openSnack("default") }. Un type est passé en premier argument pour sélectionner le type de Snackbar, le message, l'icône et l'action. À la fin, le toaster est affiché en mettant à jour state.active sur vrai.
Pour faire disparaître automatiquement le toaster, un timeout est créé pour masquer le Snackbar en mettant à jour state.active sur false après 2 secondes.
L'événement personnalisé action est surveillé avec onaction : si un clic déclenche l'action du Snackbar, la fonction close met à jour state.active pour la faire disparaître.

Tests du Composant Snackbar

Il existe deux méthodes pour tester le composant Snackbar, et elles sont couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant Snackbar Riot en utilisant des éléments Material Design avec BeerCSS. Le code source est disponible sur Github : https://github.com/steevepay/riot-beercss/blob/main/components/c-snackbar.riot

Bonne journée ! Santé 🍻

Composant Recherche avec RiotJS

Steeve — Mon, 12 May 2025 12:00:00 +0000

Cet article traite de la création d'un composant de recherche (Search) avec Riot, en utilisant le CSS Material Design BeerCSS, et de l'exécution d'une action lors des événements d'entrée et de sélection.

Avant de commencer, assurez-vous d'avoir une application de base RiotJS, ou consultez mes articles précédents.

La recherche permet aux utilisateurs d'entrer un mot-clé ou une phrase pour obtenir des informations pertinentes : Les utilisateurs saisissent une requête dans la barre de recherche (1) et voient ensuite les résultats associés (2).

Base du Composant de Recherche

L'objectif est de créer une application Riot avec une barre de recherche, d'afficher les résultats de recherche, et d'exécuter une action lorsqu'un résultat est sélectionné.

Tout d'abord, créez un nouveau fichier nommé c-search.riot dans le dossier des composants. Le préfixe c- signifie "composant", une convention de nommage utile et une bonne pratique.

Écrivez le code suivant dans ./components/c-search.riot. Le HTML provient de la documentation BeerCSS et j'ai ajouté la syntaxe RiotJS pour la logique :

<c-search>
    <div class="field prefix
        { props?.outlined ? " border" : ''}
        { props?.round ? " round" : ''}
        { props?.fill ? " fill" : ''}
        { props?.small ? " small" : ''}
        { props?.medium ? " medium" : ''}
        { props?.large ? " large" : ''}
        { props?.extra ? " extra" : ''}
        { props?.error ? " invalid" : '' }
        ">
        <progress if={ props?.loading } class="circle"></progress>
        <i if={ !props?.loading } class="front">{ props?.iconSearch ?  props.iconSearch : "search"}</i>
        <input type="text" value={ props?.value } placeholder={ props?.placeholder } />
        <menu class="{ props?.max ? "max" : "min" }">
            <div class="field prefix suffix no-margin fixed         
                            { props?.outlined ? " border" : ''}
                            { props?.round ? " round" : ''}
                            { props?.fill ? " fill" : ''}
                            { props?.small ? " small" : ''}
                            { props?.medium ? " medium" : ''}
                            { props?.large ? " large" : ''}
                            { props?.extra ? " extra" : ''}
                            { props?.error ? " invalid" : '' }
                        ">
                <i class="front">{ props?.iconBack ?  props.iconBack : "arrow_back"}</i>
                <input type="text" value={ props?.value } placeholder={ props?.placeholder } />
                <i onclick={ clear } class="front">{ props?.iconClose ?  props.iconClose : "close"}</i>
            </div>
            <a class="row" each={res in props?.results} onclick={ (ev) => select(ev, res) }>
                <i>{ res?.icon ?? props?.iconResult ?? 'history' }</i>
                <div>{ res?.label ?? res?.name ?? res }</div>
            </a>
        </menu>
    </div>
    <script>
        export default {
            select(e, result) {
                e.preventDefault();
                e.stopPropagation();
                this.root.value = result;
                this.root.dispatchEvent(new Event('select'));
            },
            clear (e) {
                e.preventDefault();
                e.stopPropagation();
                this.root.dispatchEvent(new Event('clear'));
            }
        }
    </script>
</c-search>

Source Code: https://github.com/steevepay/riot-beercss/blob/main/components/c-search.riot

Expliquons le code :

Les balises <c-search> et </c-search> définissent une balise racine personnalisée, portant le même nom que le fichier. Vous devez l'écrire ; sinon, cela pourrait créer des résultats inattendus. Utiliser la balise <div></div> comme balise racine ou redéfinir des balises HTML natives est une mauvaise pratique, donc commencer par c- est une bonne convention.
La recherche a deux états :
- État par défaut : Sans interactions, la barre de recherche principale est un champ de recherche persistant et visible en haut de l'écran : le premier élément HTML <input> est affiché.
- État de focus : Lors du focus, la barre de recherche s'étend en une vue de recherche, affichant des suggestions de recherche historique : Le second élément HTML <input> est affiché à l'intérieur d'un élément <menu> suivi d'une liste de résultats.
La liste des résultats est affichée grâce à une expression Each de Riot : <a class="row" each={res in props?.results}></a>. Le résultat affiche une icône et le nom. Le résultat peut être un tableau d'objets ou un tableau de chaînes ; le nom est alors affiché grâce à la condition : { res?.label ?? res?.name ?? res }. Il prend d'abord la propriété label, puis name ; sinon, il affiche res comme une chaîne.
Si un clic se produit sur l'un des résultats, la fonction select est exécutée : Un événement personnalisé select est émis pour notifier les composants supérieurs avec le résultat sélectionné comme valeur.
Si un clic se produit sur l'icône de fermeture, la fonction reset est exécutée : Un événement personnalisé clear est émis pour notifier le composant parent sans valeur.
L'icône de recherche par défaut peut être remplacée par une icône Google Font : Fournissez l'attribut icon, accessible sur le composant avec props.icon.
Le champ de recherche peut avoir différents styles, et ils doivent être fournis en tant qu'attribut HTML, par exemple pour rendre le champ arrondi : { props?.round ? " round" : ''} si props.round existe, la classe round est appliquée aux deux champs.
Pour afficher les résultats de recherche en plein écran, la propriété props.max doit exister et être vraie, enfin la classe max est appliquée sur le <menu>.

Enfin, chargez et instanciez le composant c-search.riot dans une page principale nommée *index.riot:

<index-riot>
    <div style="width:600px;padding:20px;">
        <c-search placeholder="Fruit name..." value={ state.value } onchange={ changed } onkeyup={ changed } results={ state.results } onselect={ selected } onclear={ reset } outlined="true" large="true" round="true" fill="true" />
    </div>
    <script>
        import cSearch from "../components/c-search.riot"
        import fruits from "./data/fruits.js"

        const _defaultState = {
            value: "",
            results: ["Mango", "Strawberries", "Bananas"]
        }

        export default {
            components: {
                cSearch
            },
            state: _defaultState,
            changed (ev) {
                this.update({ 
                    value   : ev.target.value,
                    results : fruits.filter((el) => el.toLowerCase().includes(ev.target.value?.toLowerCase()) === true) 
                })
            },
            selected (ev) {
                this.update({ value: ev.target.value })
            },
            reset () {
                this.update(_defaultState)
            }
        }
    </script>
</index-riot>

Source Code: https://github.com/steevepay/riot-beercss/blob/main/examples/index.search.riot

Détails du code :

Le composant est importé avec import cSearch from "./components/c-search.riot"; puis chargé dans l'objet Riot components:{}.
Le composant search est instancié avec <c-search /> dans le HTML.
L'état de la recherche est stocké dans l'objet Riot state:{} sous la propriété state.value de type chaîne. La propriété est passée en tant qu'attribut, comme : <c-search value={ state.value } />. Dans l'état, le résultat est initialisé avec des valeurs par défaut pour agir comme un "historique de recherche". La valeur par défaut de state.results peut être initialisée à partir d'une API.
Si l'entrée de recherche change, deux événements change et keyup sont déclenchés : la fonction changed est exécutée pour mettre à jour state.value, et pour rafraîchir la liste des résultats.
La liste state.results prend une liste filtrée de fruits ; cependant, dans une application de production, le résultat peut être calculé à partir d'un serveur/DB et retourné par une requête HTTP API.
Le résultat de la recherche est passé en tant qu'attribut du composant avec results={ state.results }.
Si un clic se produit sur un élément de la liste : l'événement select est déclenché, et la fonction selected est exécutée pour définir state.value sur l'élément sélectionné. Dans une application front-end de production, vous pouvez faire un appel API, charger une page spécifique, ou exécuter toute action.
Si l'icône close est cliquée, l'événement clear est émis, et la fonction reset est exécutée pour effacer l'entrée et la liste des résultats avec les valeurs par défaut.

Tests du Composant de Recherche

Il existe deux méthodes pour tester le composant de recherche, et elles sont couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant de recherche Riot en utilisant des éléments Material Design avec BeerCSS. Le code source de la barre de recherche est disponible sur Github : https://github.com/steevepay/riot-beercss/blob/main/components/c-search.riot

Bonne journée ! Santé 🍻

Composant Dialogue avec RiotJS

Steeve — Mon, 05 May 2025 12:00:00 +0000

Cet article traite de la création d'un composant de dialogue (Dialog) avec Riot, en utilisant le CSS Material Design BeerCSS, et de la gestion des événements de clic.

Avant de commencer, assurez-vous d'avoir une application de base RiotJS, ou consultez mes articles précédents de la série.

Je suppose que vous avez une compréhension de base de Riot ; cependant, n'hésitez pas à consulter la documentation si nécessaire : https://riot.js.org/documentation/

Le dialogue informe les utilisateurs sur une tâche spécifique et peut contenir des informations critiques, nécessiter des décisions ou impliquer plusieurs tâches. Dans un dialogue modal, l'utilisateur est interrompu et interagit avec le dialogue avant de pouvoir continuer à interagir avec le reste de l'application, par exemple en choisissant une sonnerie de téléphone:

Base du Composant de Dialogue

L'objectif est de créer une application Riot avec un dialogue et d'exécuter une action si le modal est annulé ou confirmé.

Tout d'abord, créez un nouveau fichier nommé c-dialog.riot dans le dossier des composants. Le préfixe c- signifie "composant", une convention de nommage utile et une bonne pratique.

Écrivez le code HTML suivant dans ./components/c-dialog.riot (le HTML a été trouvé dans la documentation BeerCSS):

<c-dialog>
    <dialog class="
                {props?.active ? 'active ' : null}
                {props?.blur ? 'overlay blur ' : null}
                {props?.left ? 'left ' : null}
                {props?.right ? 'right ' : null}
                {props?.top ? 'top ' : null}
                {props?.bottom ? 'bottom ' : null}
                {props?.max ? 'max ' : null}
            "
        >
        <h5 if={ props?.title }>{ props?.title }</h5>
        <div>
            { props?.message }
            <slot name="body"></slot>
        </div>
        <nav class="right-align no-space">
            <button onclick={ (ev) => clicked(ev, "cancel") } class="transparent link" if={ !props?.disableCancel }>{ props?.cancelText ?? "cancel" }</button>
            <button onclick={ (ev) => clicked(ev, "confirm") } class="transparent link" if={ !props?.disableConfirm }>{ props?.confirmText ?? "confirm" }</button>
            <slot name="button"></slot>
        </nav>
    </dialog>
       <script>
        export default {
            clicked (e, name) {
                e.preventDefault();
                e.stopPropagation();
                this.root.dispatchEvent(new Event(name));
            }
        }
    </script>
</c-dialog>

Source Code: https://github.com/steevepay/riot-beercss/blob/main/components/c-dialog.riot

Expliquons le code :

Les balises <c-dialog> et </c-dialog> définissent une balise racine personnalisée, portant le même nom que le fichier. Vous devez l'écrire ; sinon, cela pourrait créer des résultats inattendus. Utiliser la balise <dialog></dialog> comme balise racine ou redéfinir des balises HTML natives est une mauvaise pratique, donc commencer par c- est un bon choix de nom.
Le dialogue comporte trois sections principales :
- Un titre en en-tête rempli grâce à {props.title}.
- Un message dans le corps imprimé avec {props.message}.
- Une action (call to action) avec deux boutons : annuler et confirmer.
Lorsqu'un bouton est cliqué, l'événement click est capturé dans la fonction clicked, puis un événement personnalisé est émis vers le HTML parent avec this.root.dispatchEvent(new Event(name)); : il émettra soit confirm soit cancel.
Le modal s'affiche uniquement si props.active existe et est positif ; alors, la classe active est appliquée.
Le composant Dialogue a différents styles, et il est imprimé conditionnellement si leurs props correspondants existent, par exemple pour rendre le dialogue plein écran : {props?.max ? 'max ' : null} si la propriété max existe, la classe max est appliquée.

Enfin, chargez et instanciez le composant c-dialog.riot dans une page principale nommée index.riot:

<index-riot>
    <div style="width:800px;padding:20px;">
        <c-button onclick={ (ev) => update({ active: !state.active, max: false })}>Dialog</c-button> 
        <c-button onclick={ (ev) => update({ active: !state.active, max: true })}>Max</c-button>

        <c-dialog 
            title="Dialog" 
            message="Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
            active={ state.active }
            oncancel={ cancel } 
            onconfirm={ confirm }
            max={ state.max }
        />
    </div>
    <script>
        import cButton from "../components/c-button.riot"
        import cDialog from "../components/c-dialog.riot"

        export default {
            components: {
                cDialog,
                cButton
            },
            state: {
                active: false,
                left: false,
                max: false
            },
            cancel() {
                console.log("dialog cancel")
                this.update({ active: false })
            },
            confirm() {
                console.log("dialog confirm")
                this.update({ active: false })
            }
        }
    </script>
</index-riot>

Source Code: https://github.com/steevepay/riot-beercss/blob/main/examples/index.dialog.riot

Détails du code :

Les composants sont importés avec import cDialog from "./components/c-dialog.riot"; puis chargés dans l'objet Riot components:{}.
Le composant dialog est instancié avec <c-dialog/> dans le HTML.
L'état du dialogue est stocké dans l'objet Riot state:{} sous la propriété booléenne state.active. La propriété est passée en tant qu'attribut, comme : <c-dialog active={ state.active }/>. Lorsque le bouton est cliqué, il définit la propriété active sur true et affiche le modal.
Le titre et le message du dialogue sont passés en tant qu'attributs.
Si le bouton annuler ou confirmer est cliqué, il émettra deux événements personnalisés :
- oncancel : il exécutera la fonction this.cancel(), et fermera le modal.
- onconfirm : il exécutera la fonction this.confirm(), et fermera le modal.
Les deux appels à l'action peuvent être liés à une fonction personnalisée : faire un appel API, ajouter un élément HTML, envoyer un email, confirmer une suppression et plus encore !

Tests du Composant de Dialogue

Il existe deux méthodes pour tester le composant de dialogue, et elles sont couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant de dialogue Riot en utilisant des éléments Material Design avec BeerCSS. Le code source du modal est disponible sur Github : https://github.com/steevepay/riot-beercss/blob/main/components/c-dialog.riot

Bonne journée ! Santé 🍻

Composant Onglets avec Riot

Steeve — Mon, 28 Apr 2025 12:00:00 +0000

Cet article traite de la création d'un composant d'onglets (Tabs) avec Riot, en utilisant le CSS Material Design BeerCSS, et de la gestion des événements de clic. Avant de commencer, assurez-vous d'avoir une application de base Riot, ou consultez mes articles précédents.

Je suppose que vous avez une compréhension de base de Riot ; cependant, n'hésitez pas à consulter la documentation si nécessaire : https://riot.js.org/documentation/

Les onglets sont utilisés pour organiser le contenu sur différents écrans et vues, par exemple, une application média avec 3 onglets : Photos, Vidéos et Audios.

Base du Composant d'Onglets

L'objectif est de créer une application Riot avec des onglets, de changer l'onglet actif au clic, et de modifier le contenu de la page:

Tout d'abord, créez un nouveau fichier nommé c-tabs.riot dans le dossier des composants. Le préfixe c- signifie "composant", une convention de nommage utile et une bonne pratique.

Écrivez le code HTML suivant dans ./components/c-tabs.riot (CSS trouvé dans la documentation BeerCSS):

<c-tabs>
     <div class="tabs
        { props?.min ? ' min' : null }
        { props?.rightAlign ? ' right-align' : null }
        { props?.centerAlign ? ' center-align' : null }
        { props?.leftAlign ? ' left-align' : null }
    ">
        <a each={ (tab, index) in props.tabs } class="{ props.active === index ? 'active ' : null }{ props?.vertical ? 'vertical' : null }" onclick={ (ev) => clicked(ev, index) }>
            <i if={ tab?.icon }>{ tab.icon }</i>
            <img if={ tab?.img } class="circle" src={ tab.img }>
            <span>{ tab.label }</span>
        </a>
    </div>
    <script>
        export default {
            clicked (e, index) {
                e.preventDefault();
                e.stopPropagation();
                this.root.value = index;
                this.root.dispatchEvent(new Event('click'));
                this.root.dispatchEvent(new Event('change'));
            }
        }
    </script>
</c-tabs>

Expliquons le code :

Les balises <c-tabs> et </c-tabs> définissent une balise racine personnalisée, portant le même nom que le fichier. Vous devez l'écrire ; sinon, cela pourrait créer des résultats inattendus. Utiliser la balise <div> comme balise racine ou redéfinir des balises HTML natives est une mauvaise pratique, donc commencer par c- est un bon choix de nom.
Une liste d'onglets doit être passée en tant qu'attribut, accessible avec props.tabs. Chaque objet de la liste définira les propriétés de l'onglet : l'étiquette, une image ou une icône provenant de Google Font Icons.
La liste des onglets est parcourue grâce à l'expression Each de Riot appliquée sur les balises HTML <a></a>, tel que : <a each={ (tab, index) in props.tabs }> { tab.label } </a>.
L'onglet actif est défini avec la propriété active, l'index de l'onglet sélectionné. Si l'index de l'onglet actuellement affiché est égal à active, la classe active est appliquée à l'onglet.
Si l'onglet possède une icône ou une image, il affiche l'expression de l'icône <i if={ tab?.icon }>{ tab.icon }</i>, ou une image <img if={ tab?.img } class="circle" src={ tab.img }>.
Lorsqu'un clic se produit sur l'un des onglets, l'index de l'onglet sélectionné est passé à la fonction clicked: la fonction émettra deux événements (change et click) et fournira l'index sélectionné.

Enfin, chargez et instanciez le composant c-tabs.riot dans une page nommée index.riot :

<index-riot>
    <div style="width:800px;padding:20px;">
        <c-tabs active={ state.active } tabs={ state.tabs } onchange={ changed } />
        <div class="page padding { state.active === 0 ? 'active' : null}" if={ state.active === 0 }>
            <h5>Tab 1</h5>
        </div>
        <div class="page padding { state.active === 1 ? 'active' : null}" if={ state.active === 1 }>
            <h5>Tab 2</h5>
        </div>
        <div class="page padding { state.active === 2 ? 'active' : null}" if={ state.active === 2 }>
            <h5>Tab 3</h5>
        </div>
        <div class="page padding { state.active === 3 ? 'active' : null}" if={ state.active === 3 }>
            <h5>Tab 4</h5>
        </div>
    </div>
    <script>
        import cTabs from "./components/c-tabs.riot"

        export default {
            components: {
                cTabs
            },
            state: {
                active: 2,
                tabs: [
                    { label: "Flights", icon: "flight" },
                    { label: "Travel", icon: "card_travel" },
                    { label: "Explore", icon: "explore" },
                    { label: "BeerCSS", img: "./favicon.png" }
                ]
            },
            changed(ev) {
                this.update({
                    active: ev.target.value
                })
            }
        }
    </script>
</index-riot>

Détails du code :

Les composants sont importés avec import cTabs from "./components/c-tabs.riot"; puis chargés dans l'objet Riot components:{}.
Le composant tabs est instancié avec <c-tabs/> dans le HTML.
Pour stocker des données dans un composant, elles doivent être définies dans l'objet Riot state:{}. Dans notre cas, deux données sont nécessaires :
- state.tabs : La liste des onglets avec des étiquettes, des icônes ou des images.
- state.active : L'index de l'onglet sélectionné.
Passez les états au composant Tabs en tant que props : <c-tabs active={ state.active } tabs={ state.tabs } onchange={ changed } />.
Lorsque quelqu'un clique sur un onglet, l'événement de changement est déclenché, et la fonction changed est exécutée : state.active obtient le nouvel index sélectionné grâce à la fonction Riot this.update({active: ev.target.value}).
Lorsque l'index state.active change, la page affichée change également avec une condition IF, tel que : <div if={ state.active === 0 }><h5>Onglet 1</h5></div>.

Tests du Composant d'Onglets

Il existe deux méthodes pour tester le composant d'onglets, et elles sont couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant d'onglets Riot en utilisant des éléments Material Design avec BeerCSS. Le code source de l'onglet est disponible sur Github : https://github.com/steevepay/riot-beercss/blob/main/components/c-tabs.riot

N'hésitez pas à commenter si vous avez des questions ou besoin d'aide concernant RiotJS.

Bonne journée ! Santé 🍻

Composant Chip avec RiotJS

Steeve — Mon, 21 Apr 2025 12:00:00 +0000

Cet article traite de la création d'un composant Chip avec RiotJS, en utilisant le CSS Material Design BeerCSS. Avant de commencer, assurez-vous d'avoir une application de base RiotJS, ou consultez mes articles précédents.

Je suppose que vous avez une compréhension de base de Riot ; cependant, n'hésitez pas à consulter la documentation si nécessaire : https://riot.js.org/documentation/

Les Chips aident les gens à entrer des informations, à faire des sélections, à filtrer du contenu ou à déclencher des actions (voir la capture d'écran suivante). L'objectif est de créer un composant Chip qui prend en charge tous les styles de BeerCSS et écoute les événements de clic.

Base du Composant Chip

Tout d'abord, créez un nouveau fichier nommé c-chip.riot dans le dossier des composants. Le préfixe c- signifie "composant", une convention de nommage utile et une bonne pratique.

Dans ./components/c-chip.riot, écrivez le code HTML suivant (CSS trouvé dans la documentation BeerCSS):

<c-chip>
    <a class="
            chip
            {props?.small ? 'small' : null }
            {props?.medium ? 'medium' : null }
            {props?.large ? 'large' : null }

            {props?.smallElevate ? 'small-elevate' : null}
            {props?.mediumElevate ? 'medium-elevate' : null}
            {props?.largeElevate ? 'large-elevate' : null}

            {props?.round ? 'round' : null }
            {props?.fill ? 'fill' : null }
            {props?.vertical ? 'vertical' : null }
        ">
        <i if={ props?.icon }>{ props.icon }</i>
        <img class={props?.inline ? null : "responsive" } if={ props?.img } src={ props.img }>
        <span><slot></slot></span>
        <i if={ props?.iconend }>{ props.iconend }</i>
    </a>
</c-chip>

Expliquons le code :

Les balises <c-chip> et </c-chip> définissent une balise racine personnalisée, portant le même nom que le fichier. Vous devez l'écrire ; sinon, cela pourrait créer des résultats inattendus. Utiliser la balise <a> comme balise racine ou redéfinir des balises HTML natives est une mauvaise pratique, donc commencer par c- est un bon choix de nom.
En utilisant la balise <slot>, vous pouvez injecter des modèles HTML personnalisés dans un composant enfant depuis son parent : nous allons injecter l'étiquette du chip.
Un chip a de nombreuses classes de variations : taille, élévation et forme (rond, rempli ou vertical). Elles sont injectées conditionnellement si les propriétés correspondantes existent. Par exemple, si la propriété props.round existe, elle activera la classe round dans le composant.
Deux icônes peuvent être passées à deux positions : soit comme préfixe, soit comme suffixe du label:
- la propriété icon injecte le glyphe avant l'étiquette
- la propriété iconend injecte le glyphe après l'étiquette
Grâce à la propriété img, une image peut être injectée à la place d'une icône.

Enfin, le composant c-chip.riot peut être instancié dans une page index.riot. Voici toutes les variations de Chip, qu'elles soient remplies, arrondies, incluant une image ou une icône :

<index-riot>
    <div style="width:800px;padding:20px;">
        <h4 style="margin-bottom:20px;margin-left:10px;">Riot + BeerCSS</h4>
        <h6 style="margin-left:10px">Chip Variations</h6><br>
        <c-chip>Suggestion</c-chip>
        <c-chip iconend="close">Input</c-chip>
        <c-chip icon="check">filter</c-chip>
        <c-chip icon="today">assist</c-chip>
        <c-chip img="./favicon.png" inline="true">image</c-chip>
        <c-chip img="./favicon.png">image</c-chip>
        <br><br>
        <c-chip round="true">Suggestion</c-chip>
        <c-chip round="true" iconend="close">Input</c-chip>
        <c-chip round="true" icon="check">filter</c-chip>
        <c-chip round="true" icon="today">assist</c-chip>
        <c-chip round="true" img="./favicon.png" inline="true">image</c-chip>
        <c-chip round="true" img="./favicon.png">image</c-chip>
        <br><br>
        <c-chip fill="true">Suggestion</c-chip>
        <c-chip fill="true" iconend="close">Input</c-chip>
        <c-chip fill="true" icon="check">filter</c-chip>
        <c-chip fill="true" icon="today">assist</c-chip>
        <c-chip fill="true" img="./favicon.png" inline="true">image</c-chip>
        <c-chip fill="true" img="./favicon.png">image</c-chip><br><br>
        <c-chip fill="true" round="true">Suggestion</c-chip>
        <c-chip fill="true" round="true" iconend="close">Input</c-chip>
        <c-chip fill="true" round="true" icon="check">filter</c-chip>
        <c-chip fill="true" round="true" icon="today">assist</c-chip>
        <c-chip fill="true" round="true" img="./favicon.png" inline="true">image</c-chip>
        <c-chip fill="true" round="true" img="./favicon.png">image</c-chip>
    </div>
    <script>
        import cChip from "./components/c-chip.riot"

        export default {
            components: {
                cChip
            },
        }
    </script>
</index-riot>

Explication du code :

Le composant est importé avec import cChip from "./components/c-chip.riot"; puis chargé dans l'objet Riot components:{}.
Dans le HTML, le composant Chip est instancié avec <c-chip>label<c-chip>.
Passez des attributs à la balise pour activer les variations, par exemple : <c-chip fill="true" round="true" icon="check">filter</c-chip>.

Capture d'écran du HTML généré :

Événements du Composant Chip

Comme mentionné, un Chip est utilisé pour filtrer, suggérer et déclencher des actions. Un exemple concret serait que vous devez sélectionner les commodités de votre appartement pour une demande de location.

Créons un groupe de chips pour chaque commodité et vérifions s'il est sélectionné.

Voici le code Riot correspondant dans index.riot:

<index-riot>
    <div style="width:800px;padding:20px;">
        <h6 style="margin-left:10px">Amenities</h6><br>
        <c-chip each={ el in state.amenities } onclick={ (ev) => clicked(el.label) } fill={ el.checked === true } icon={ el.checked === true ? 'check' : null }> { el.label } </c-chip>
    </div>
    <script>
        import cChip from "./components/c-chip.riot"

        export default {
            components: {
                cChip
            },
            state: {
                amenities: [
                    { label: "Wash / Dryer", checked: false },
                    { label: "Ramp Access", checked: false },
                    { label: "Garden", checked: false },
                    { label: "Cat OK", checked: false }
                ]
            },
            clicked (label) {
                const _el = this.state.amenities.find(el => el.label === label);
                if (_el) {
                    _el.checked = !_el.checked;
                    this.update();
                }
            }
        }
    </script>
</index-riot>

Détails du code :

Une liste de Chips est imprimée grâce à l'attribut Each de Riot.
Chaque chip écoute un événement de clic avec onclick={ (ev) => clicked(el.label) }. Si un événement de clic est déclenché, la fonction clicked est exécutée, et le label est passée comme premier argument.
La fonction clicked trouve l'élément de la liste en fonction de l'étiquette, puis la propriété checked est mise à jour.
Lorsque checked est vrai (true), deux attributs sont activés : fill et icon.

Tests du Composant Chip

Il existe deux méthodes pour tester le composant Chip, et elles sont couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant Chip Riot en utilisant des éléments Material Design avec BeerCSS.

Le code source du chip est disponible sur Github : https://github.com/steevepay/riot-beercss/blob/main/components/c-chip.riot

N'hésitez pas à commenter si vous avez des questions ou besoin d'aide concernant RiotJS.

Bonne journée ! Santé 🍻

Composant Table avec RiotJS

Steeve — Mon, 14 Apr 2025 12:00:00 +0000

Cet article traite de la création d'un composant Table avec RiotJS, en utilisant BeerCSS. Avant de commencer, assurez-vous d'avoir une application de base RiotJS, ou lisez mes articles précédents.

n'hésitez pas à consulter la documentation de Riot si nécessaire : https://riot.js.org/documentation/

Une Table est un élément complexe et riche avec de nombreux styles et actions. L'article vise à créer un composant Table avec un design BeerCSS, affichant une liste d'objets. Ensuite, personnalisez les cellules avec des éléments spéciaux (chips, cases à cocher, etc.).

Base du composant Table

Tout d'abord, créez un nouveau fichier nommé c-table.riot dans le dossier des composants. Le préfixe c- signifie "composant", une convention de nommage utile et une bonne pratique.

Écrivez le code HTML suivant dans ./components/c-table.riot (le CSS a été trouvé dans la documentation BeerCSS):

<c-table>
    <table class="
                { props?.leftAlign ? 'left-align ' : null }
                { props?.centerAlign ? 'center-align ' : null }
                { props?.rightAlign ? 'right-align ' : null }
                { props?.stripes ? 'stripes ' : null }
                { props?.outlined ? 'border ' : null }
                { props?.scroll ? 'scroll' : null }"
        >
        <thead class="{props?.scroll ? ' fixed' : null }">
            <tr>
                <th each={ col in Object.keys(props?.items?.[0])}>{ col }</th>
            </tr>
        </thead>
        <tbody>
            <tr each={ item in props?.items}>
                <td if={ item } each={ val in Object.values(item) }>
                    { val }
                </td>
            </tr>
        </tbody>
        <tfoot if={ props?.footer === true } class="{props?.scroll ? ' fixed' : null }">
            <tr>
                <th each={ header in Object.keys(props?.items?.[0])}>{ header }</th>
            </tr>
        </tfoot> 
    </table>
    <style>
        thead, tfoot > tr > th::first-letter {
            text-transform:capitalize;
        }
    </style>
</c-table>

Décomposons le code :

Les balises <c-table> et </c-table> définissent une balise racine personnalisée, portant le même nom que le fichier. Vous devez l'écrire ; sinon, cela pourrait créer des résultats inattendus. Utiliser la balise <label> comme balise racine ou redéfinir des balises HTML natives est une mauvaise pratique, donc commencer par c- est un bon nommage.
Le composant peut recevoir une liste d'objets items en tant qu'attribut, et peut être utilisé dans le composant avec props?.items.
Pour créer des cellules, l'expression Riot each est utilisée pour parcourir les éléments :
- Une première boucle est utilisée pour chaque balise de ligne de tableau avec <tr each={ item in props?.items}>. L'item est un objet de la liste.
- Une deuxième boucle enfant est utilisée pour chaque cellule de tableau avec <td if={ item } each={ val in Object.values(item) }>{ val }</td>. L'expression Object.values() renvoie un tableau des valeurs d'un objet donné.
Pour l'en-tête du tableau, il utilise les noms de key du premier élément de la liste props.items : La fonction Object.keys est utilisée pour renvoyer un tableau de toutes les clés d'objet de l'élément donné, comme <th each={ col in Object.keys(props?.items?.[0])}>{ col }</th>.
BeerCSS permet la création d'un pied de page, qui suit la même logique que l'en-tête : accéder au premier élément de la liste, obtenir une liste de clés avec Object.keys et créer une boucle avec l'expression Riot each. Le pied de page est affiché conditionnellement si la propriété props.footer existe.
La première lettre de chaque en-tête est capitalisée grâce à l'expression CSS : th::first-letter { text-transform:capitalize; }.
Enfin, BeerCSS fournit des classes utiles pour changer le style du tableau, par exemple, ajouter des rayures ou des bordures ou changer l'alignement. Les classes sont injectées conditionnellement avec l'expression Riot : { props?.stripes ? 'stripes ' : null } signifiant que si la propriété props.stripes existe, la classe stripes est ajoutée.

Enfin, chargez et instanciez le c-table.riot dans une page nommée index.riot :

<index-riot>
    <div style="width:800px;padding:20px;">
        <h4 style="margin-bottom:20px">Riot + BeerCSS</h4>
        <c-table items={ state.animals } />
    </div>
    <script>
        import cTable from "./components/c-table-full.riot"

        export default {
            components: {
                cTable
            },
            state: {
                animals: [
                    {
                        id: 1,
                        name: 'African Elephant',
                        species: 'Loxodonta africana',
                        diet: 'Herbivore',
                        habitat: 'Savanna, Forests',
                        enabled: false
                    },
                    {
                        id: 2,
                        name: 'Lion',
                        species: 'Panthera leo',
                        diet: 'Carnivore',
                        habitat: 'Savanna, Grassland',
                        enabled: true
                    },
                    {
                        id: 3,
                        name: 'Hippopotamus',
                        species: 'Hippopotamus amphibius',
                        diet: 'Herbivore',
                        habitat: 'Riverbanks, Lakes',
                        enabled: false
                    }
                ]
            }
        }
    </script>
</index-riot>

Détails du code :

Les composants sont importés avec import cTable from "./components/c-table.riot"; puis chargés dans l'objet Riot components:{}.
Le tableau est instancié avec <c-table/> dans le HTML.
Une liste d'animaux est fournie au tableau, grâce à l'attribut items : items={ state.animals } ; le tableau créera automatiquement les en-têtes, les lignes et les cellules ! ✅

Voici le HTML généré :

Composant Table avec cellules personnalisées

Afficher des composants personnalisés dans les cellules est souvent nécessaire pour les applications de production, comme des cases à cocher, ou même des boutons.

Cette capacité est activée grâce aux Slots: La balise <slot> injecte des modèles HTML personnalisés dans un composant enfant depuis son parent. Modifions la boucle suivante dans c-table.riot:

<td each={ val in Object.values(item) }>
  { val }
</td>

Remplacez-la par l'expression suivante :

<td each={ el in Object.entries(item) }>
   <slot name="item" item={ item } column={ el?.[0] } value={ el?.[1] }></slot>
   <template if={ slots.length === 0 }>
      { el?.[1] }
   </template>
</td>

Expliquons ce qui se passe ici :

Au lieu d'utiliser Object.values, on utilise Object.entries pour convertir un objet en une liste de [key, value]. Par exemple, [{key: 1, name: "blue"}] renvoie [["key", 1], ["name", "blue"]].
Un slot est créé pour chaque cellule : <slot name="item" column={ el?.[0] } item={ item } value={ el?.[1] }></slot>.
Passer des valeurs dynamiques aux slots s'appelle des Higher Order Components: Tous les attributs définis sur les balises de slot seront disponibles dans leurs modèles HTML injectés. Dans notre cas, quatre attributs sont créés :
- Le slot a un nom optionnel, une convention de nommage Riot, sans le définir, il aurait le nom default. Il n'est pas possible de définir le nom dynamiquement.
- L'objet item de la boucle de ligne est passé dans l'attribut item du slot : Il sera accessible sur le composant passé en tant que slots !.
- La clé de l'élément est passée à l'attribut column du slot grâce à column={ el?.[0] }.
- La valeur de l'élément est passée à l'attribut value du slot grâce à value={ el?.[1] }.
Si le slot n'existe pas, la valeur de la cellule est imprimée avec <template if={ slots.length === 0 }>{ el?.[1] }</template>. Les directives if peuvent être utilisées avec une balise <template>, dans notre cas, on souhaite afficher conditonnellement la valeur de l'élément (en savoir plus sur la documentation Riot).

Maintenant, dans index.riot, affichons un composant Chip pour la colonne Diet :

<index-riot>
    <div style="width:800px;padding:20px;">
        <h4 style="margin-bottom:20px">Riot + BeerCSS</h4>
        <c-table items={ state.animals }>
            <template slot="item">
                <c-chip if={ column === 'diet' }>
                    { value }
                </c-chip>
                <template if={ column !== 'diet' }>
                    { value }
                </template>
            </template>
        </c-table>
    </div>
    <script>
        import cTable from "./components/c-table-full.riot"
        import cChip from "./components/c-chip.riot"

        export default {
            components: {
                cTable,
                cChip
            },
            state: {
                animals: [
                    {
                        id: 1,
                        name: 'African Elephant',
                        species: 'Loxodonta africana',
                        diet: 'Herbivore',
                        habitat: 'Savanna, Forests',
                        enabled: false
                    },
                    {
                        id: 2,
                        name: 'Lion',
                        species: 'Panthera leo',
                        diet: 'Carnivore',
                        habitat: 'Savanna, Grassland',
                        enabled: true
                    },
                    {
                        id: 3,
                        name: 'Hippopotamus',
                        species: 'Hippopotamus amphibius',
                        diet: 'Herbivore',
                        habitat: 'Riverbanks, Lakes',
                        enabled: false
                    }
                ]
            }
        }
    </script>
</index-riot>

Décomposition du code :

Le composant Chip est définie dans l'objet Riot components:{} puis chargée avec <c-chip> Label </c-chip>.
Dès que nous utilisons slot="item", par exemple <c-chip slot="item">{ value }</c-chip>, l'élément Chip sera injecté dans toutes les cellules. Utiliser une seule Chip comme Slot est une mauvaise idée : la Chip sera affichée pour toutes les cellules. Ce n'est pas ce que nous voulons !
Grâce aux trois attributs dynamiques (magie des Higher Order Components ✨), nous pouvons contrôler ce qui est affiché :
- item est l'objet pour la ligne actuelle,
- column pour la clé d'en-tête actuelle,
- value pour la valeur de la cellule.
Lorsque plusieurs éléments HTML sont affichés dans un slot, il est préférable de les envelopper dans une balise "template", dans notre cas : <template slot="item"></template>.
La partie la plus importante est : <c-chip if={ column === 'diet' }>{ value }</c-chip><template if={ column !== 'diet' }>{ value }</template>. Si la colonne actuelle est diet, la Chip affiche la valeur, sinon, la valeur brute est affichée.

Voici le résultat HTML :

Composant Table avec des cases à cocher

Le processus d'insertion de cases à cocher dans le tableau est le même que dans la section précédente : le composant de case à cocher est passé en tant que Slot, et il doit être affiché en fonction d'un nom de colonne.

Dans notre cas, la case à cocher obtient la valeur booléenne de la colonne enabled.

Voici le code HTML pour index.riot:

<index-riot>
    <div style="width:800px;padding:20px;">
        <h4 style="margin-bottom:20px">Riot + BeerCSS</h4>
        <c-table items={ state.animals }>
            <template slot="item">
                <c-checkbox if={ column === 'enabled' } value={ value } onchange={ (ev) => changed( item.id, ev.target.value ) } />
                <c-chip if={ column === 'diet' }>
                    { value }
                </c-chip>
                <template if={ column !== 'diet' && column !== 'enabled' }>
                    { value }
                </template>
            </template>
        </c-table>
    </div>
    <script>
        import cTable from "./components/c-table-full.riot"
        import cChip from "./components/c-chip.riot"
        import cCheckbox from "./components/c-checkbox.riot"

        export default {
            changed (id, value) {
                const _el = this.state.animals.find(el => el.id === id);
                if (_el) {
                    _el.enabled = value;
                    this.update();
                }
            },
            components: {
                cTable,
                cChip,
                cCheckbox
            },
            state: {
                animals: [
                    {
                        id: 1,
                        name: 'African Elephant',
                        species: 'Loxodonta africana',
                        diet: 'Herbivore',
                        habitat: 'Savanna, Forests',
                        enabled: false
                    },
                    {
                        id: 2,
                        name: 'Lion',
                        species: 'Panthera leo',
                        diet: 'Carnivore',
                        habitat: 'Savanna, Grassland',
                        enabled: true
                    },
                    {
                        id: 3,
                        name: 'Hippopotamus',
                        species: 'Hippopotamus amphibius',
                        diet: 'Herbivore',
                        habitat: 'Riverbanks, Lakes',
                        enabled: false
                    }
                ]
            }
        }
    </script>
</index-riot>

Décomposition du code :

La case à cocher personnalisée est définie comme un composant dans l'objet Riot components:{} puis chargée avec <c-checkbox/>.
La case à cocher est imprimée uniquement si la colonne actuelle est enabled.
La valeur de la case à cocher est définie grâce à value={ value }.
Si un clic se produit sur la case à cocher, l'événement change est émis, et la fonction changed() est exécutée avec deux attributs onchange={ (ev) => changed( item.id, ev.target.value ) }:
- La fonction obtient la valeur d'ID de l'élément comme premier argument.
- En tant que deuxième argument, la fonction obtient la valeur de la case à cocher.
La fonction changed est exécutée : d'abord, l'objet actuel est trouvé grâce à l'ID de l'élément, et enfin la valeur enabled est mise à jour.

Capture d'écran du tableau généré avec des cases à cocher :

Test du composant Table

Il existe deux méthodes pour tester le composant Table, et elles sont couvertes dans deux articles différents :

Conclusion

Voilà 🎉 Nous avons créé un composant Table Riot en utilisant BeerCSS. Un tableau peut avoir beaucoup plus de fonctionnalités, et de nouveaux articles seraient nécessaires pour:

rendre les lignes sélectionnables,
créer des en-têtes personnalisés,
un défilement virtuel,
un tri,
un filtrage,
et plus encore.

Le code source du tableau est disponible sur Github : https://github.com/steevepay/riot-beercss/blob/main/components/c-table.riot

Passez une excellente journée ! Santé 🍻