Ce blog est le premier d'une série de widgets à construire pour vous familiariser avec la création de vos propres widgets enfichables pour MendixLes blogs couvriront des concepts de plus en plus sophistiqués et couvriront une gamme de cas d'utilisation, notamment la familiarisation avec Typescript et l'API des widgets enfichables, l'exécution de modèles d'apprentissage automatique dans votre navigateur et la création d'un jeu WebAssembly de base.

Par où commencer

Si vous ne l'avez pas déjà fait, vous devriez consulter l'exemple pratique pour créer votre premier widget enfichable :

• Créer un widget Web enfichable : Partie 1

• Créer un widget Web enfichable : Partie 2 (Avancé)

Les widgets enfichables utilisent le framework Javascript React. Nous aborderons certains concepts de React dans cette série, mais il ne s'agit en aucun cas d'une introduction complète à React. Donc, si vous avez besoin d'une introduction ou d'un rappel, je vous recommande vivement le cours suivant (vous pourrez même repérer l'inspiration pour ce widget) : Tutoriel React : Apprendre React JS – Cours gratuit de 11 heures

Objectif de ce blog

Dans ce blog, nous aborderons :

• Structure du projet de widget enfichable
• Configuration et développement des tests
• Introduction aux concepts de React
• Tirer parti des bibliothèques externes

Ce que nous construisons

Nous allons construire un compteur qui peut être augmenté ou diminué en cliquant sur un bouton, avec un changement de couleur aléatoire au clic.

L'état final du projet peut être trouvé ici : GitHub – joe-robertson-mx/colorCount

Démarrer

Pour commencer, nous échafaudons notre widget en utilisant le Mendix Générateur de widgets avec @mendix/widget color count. Cela nous donne notre implémentation HelloWorld.

Structure des dossiers :

Notre dossier de widgets a la structure suivante :

• dist — où notre code compilé et groupé sera généré
• node-modules — nos dépendances de nœuds
• src - notre dossier de code source
• composants — chaque dossier de composant fichier jsx
• ui — css pour le style du widget
• package.xml — décrit la structure du widget
• colourCount.editorConfig.ts — configuration pour l'aperçu en mode conception dans Studio Pro et Studio
• colourCount.editorPreview.jsx — composant qui fournit un aperçu dans Studio Pro et Studio
• colourCount.tsx — le point d'entrée du widget
• colourcount.xml — le balisage qui décrit l'interface entre le widget et Mendix
• package.json — décrit notre projet npm et les dépendances des widgets
• prettier.config.js — pour nous permettre de modifier les règles plus jolies pour notre code

Configuration des tests et du développement

Pour faciliter les tests, nous créons un nouveau blanc Mendix Projet dans la version que nous ciblons pour notre widget, dans ./colourCount/tests/testProject

Faites-le fonctionner

Une fois cela fait, exécutons notre script de construction et testons notre widget.

Accédez au répertoire racine de votre widget depuis votre terminal, puis entrez

construction d'exécution npm

Cela créera un package de widgets dans notre dossier dist/ et dans le dossier widgets de notre application de test.

Pour voir ce widget en action, il suffit d'ouvrir notre application de test dans Studio Pro et d'appuyer sur F4 pour synchroniser notre répertoire de fichiers. Nous pouvons ensuite ajouter notre widget à une page de la même manière que nous le ferions pour n'importe quel autre widget.

Pour configurer notre widget et vérifier que les paramètres sont transmis du modélisateur au widget dans le front-end, nous pouvons ajouter du texte à transmettre.

Lorsque nous exécutons l'application, nous pouvons voir

Ce processus de déploiement et de test de notre widget fonctionne, mais il est un peu lent. Afin d'accélérer le processus, nous pouvons démarrer le serveur de widgets en exécutant

démarrage de l'exécution npm

Cela surveillera notre code pour les changements, et afin de les voir reflétés, nous devons simplement vider le cache et forcer un rechargement.

Cela peut être fait dans Chrome en ouvrant les outils de développement Chrome (Ctrl + Maj + i), en cliquant avec le bouton droit sur le bouton d'actualisation et en sélectionnant « Vider le cache et recharger à froid ».

Code d'écriture

Il est temps de coder !

Quelques changements mineurs avant de commencer

Commençons par notre code de réaction, renommons d'abord nos composants en quelque chose de plus sensé : Count.

Tout d’abord, nous renommons les composants dans HelloWorld.jsx.

import { createElement } from "react";
import { Count } from "./components/Count";
import "./ui/ColourCount.css";

export function ColourCount({ sampleText }) {
   return <Count sampleText={sampleText ? sampleText : "World"} />
}

Il est également recommandé de renommer le fichier pour qu'il corresponde au composant dans ColourCount.

Nous devons renommer le fichier CSS dans src/ui en ColourCount.css – afin qu’il soit importé correctement. Nous devons également mettre à jour le composant enfant. Pour ce faire, nous renommons d’abord HelloWorldSample.jsx en Count.jsx et mettons à jour le nom du composant à l’intérieur en Count.

export function Count({ sampleText }: HelloWorldSampleProps) {
    return <div className="widget-hello-world">
              Hello {sampleText}
           </div>;
 }

Pour accélérer le processus de développement, nous allons modifier notre fichier editorPreview afin qu'il ne dépende pas du reste du code en le mettant à jour comme ceci

import { ReactElement, createElement } from "react";

export function preview() {
    return <div />;
}

export function getPreviewCss() {
    return require("./ui/ColourCount.css");
}

Avant de commencer à mettre à jour nos composants, renommons notre composant enfant en quelque chose de plus sensé : « Count ». Pour ce faire, nous devons mettre à jour le composant parent ColourCount pour référencer le composant Count contenu dans le fichier components/Count.

Notre construction de widget peut être divisée en 3 parties :

• Mettre à jour le Mendix Interface de widget pour accepter un nombre pour la valeur de départ du compteur
• Créer la logique pour changer ce nombre
• Ajoutez le changement de couleur aléatoire au nombre

Mises à jour Mendix Interface de widget

L'interface entre le Mendix Le modèle et votre widget sont définis dans le balisage ColourCounter.xml. Nous devons mettre à jour le nôtre pour accepter une valeur numérique, en modifiant le 'exemple de texte» propriété aux éléments suivants:

<property key="initialValue" type="integer" required="true" defaultValue="5">
    <caption>Initial Value</caption>
    <description>The initial value of the counter</description></property>

Si nous ouvrons notre Mendix modèle, appuyez sur F4 et mettez à jour le widget. Lorsque vous ouvrez le widget, vous verrez notre nouvelle interface.

Cependant, cela n'est pas encore connecté à notre composant.

Pour ce faire, nous devons remplacer exemple de texte au initialValue dans le fichier ColourCount :

import { createElement } from "react";
import { Count } from "./components/Count";
import "./ui/ColourCount.css";

export function ColourCount({ initialValue }) {
    return <Count initialValue={initialValue} />;
}

Et dans le fichier Count

export function Count({ initialValue }) {
    return <div>{initialValue}</div>;
}

si nous réexécutons notre application, nous pouvons voir notre valeur initiale rendue :

Les propriétés (ou accessoires) sont transmises par le Mendix application au composant ColourCount, où il est déstructuré dans la fonction et transmis au composant Count.

En savoir plus sur la déstructuration des objets JavaScript.

Créer la logique pour changer ce nombre

Les props ne doivent pas être modifiées directement dans React. Au lieu de cela, nous stockons les propriétés qui sont modifiées dans l'état du composant.

Afin de tirer parti de l'état dans un composant fonctionnel, nous utilisons le hook useState.

Les hooks ont été introduits dans la version React 16.8. Ils permettent d'utiliser l'état et d'autres fonctionnalités React sans écrire de classe. Les hooks sont des fonctions qui s'intègrent aux fonctionnalités d'état et de cycle de vie React à partir de composants fonctionnels. Ils ne fonctionnent pas à l'intérieur des classes. En savoir plus sur les Hooks dans React.

Tout d’abord, nous devons ajouter utiliserÉtat aux importations.

import { createElement, useState } from "react";

Ensuite, nous ajoutons le code suivant au composant Count.

export function Count({ initialValue }) {
    const [count, setCount] = useState (initialValue)
    return <div>{count}</div>;
}

Quand nous appelons utiliserÉtat il renvoie un tableau de la variable d'état et une fonction pour définir la variable d'état. Ceci est immédiatement déstructuré en compter état et setCount la fonction.

Il accepte le initialValue en tant que paramètre, qui définit la valeur de la variable count lors de la création.

Nous pouvons maintenant changer l'état en utilisant setCountLors de la définition de l'état, vous pouvez soit simplement transmettre une valeur, soit, comme dans ce cas, utiliser l'état précédent comme paramètre dans la fonction.

Sachant cela, nous pouvons ajouter une fonction pour augmenter la valeur de l’état.

export function Count({ initialValue }) {

   const [count, setCount] = useState (initialValue)
   
   const increment = () => {
      setCount(prevState => prevState + 1);
   };

   return <div>{initialValue}</div>;
}

Nous pouvons faire la même chose pour une fonction de décrémentation.

Nous devons maintenant mettre à jour le JSX pour restituer le HTML que nous voulons pour notre application :

export function Count({ initialValue }) {
    const [count, setCount] = useState (initialValue)

    const increment = () => {
         setCount(prevState => prevState + 1);
    };

    const decrement = () => {
        setCount(prevState => prevState - 1);
    };

    return (
        <div>
              <p>{count}</p>
              <button onClick={increment}>+</button>
              <button onClick={decrement}>-</button>
       </div>
    );
}

Lorsque nous exécutons notre application, nous pouvons désormais augmenter et diminuer la valeur de la Etat, qui s'affiche dans le widget :

Ajoutez le changement de couleur aléatoire au nombre

Nous souhaitons maintenant générer une couleur aléatoire lorsque le nombre change. Ce serait un morceau de code qui prendrait beaucoup de temps à écrire, mais heureusement, nous pouvons utiliser un package logiciel pré-écrit stocké dans le registre npm : couleur aléatoire

Le package fournit une fonction qui, lorsqu'elle est appelée, renvoie une couleur aléatoire sous forme de chaîne. L'utilisation de ce package est simple : tout d'abord, nous installons le package en exécutant npm install randomcolor dans notre dossier de widgets.

Ensuite, nous commençons à modifier le code dans notre fichier Count. Nous importons d'abord la fonction

import randomColor from 'randomcolor';

Ensuite, nous devons initier un état pour conserver notre propriété de couleur

const [colour, setColour] = useState('')

Nous avons également besoin que la couleur soit reflétée dans le style du widget pour ce faire, nous pouvons utiliser la propriété style pour la balise HTML. La propriété style accepte un objet JS avec les propriétés de style que vous souhaitez appliquer.

En savoir plus sur le style des éléments Dom à l'aide de React.

Pendant que nous sommes ici, nous pouvons améliorer l'apparence de nos boutons en utilisant le bouton intégré Mendix Des classes:

import { createElement, useState } from 'react'
import randomColor from 'randomcolor'
export function Count({ initialValue }) {
  const [count, setCount] = useState(initialValue)
  const [colour, setColour] = useState('')
  
  const increment = () => {
    setCount((prevState) => prevState + 1)
  }
  
  const decrement = () => {
    setCount((prevState) => prevState - 1)
  }
  
  return (
    <div>
      <p style={{ color: colour }}>{count}</p>
      <button className="mx-button btn-primary" onClick={increment}>
        +
      </button>
      <button className="mx-button" onClick={decrement}>
        -
      </button>
    </div>
  )

Nous devons maintenant déclencher le changement de couleur lorsque notre variable de comptage change. Pour cela, nous pouvons utiliser l'un des principaux utilitaires disponibles dans React : useEffet.

useEffet est un hook qui appelle une fonction (un effet secondaire) à chaque rendu du composant. En ajoutant ce qui suit, nous pouvons définir la couleur sur une valeur aléatoire lors du rendu :

import { createElement, useState } from 'react'
import randomColor from 'randomcolor'
export function Count({ initialValue }) {
  const [count, setCount] = useState(initialValue)
  const [colour, setColour] = useState('')
  
  useEffect(() => {
    setColour(randomColor())
  }, [])
  
  const increment = () => {
    setCount((prevState) => prevState + 1)
  }
  
  const decrement = () => {
    setCount((prevState) => prevState - 1)
  }
  
  return (
    <div>
      <p style={{ color: colour }}>{count}</p>
      <button className="mx-button btn-primary" onClick={increment}>
        +
      </button>
      <button className="mx-button" onClick={decrement}>
        -
      </button>
    </div>
  )

Lorsque nous exécutons ceci dans le navigateur, nous obtenons… DISCO COUNT !

C'est cool, mais ce n'est certainement pas ce que nous souhaitons. Alors pourquoi cela se produit-il ?

Eh bien, si nous mettons un console.log('Render') dans useEffect, nous pouvons voir que le composant effectue un rendu répété et cela est dû au fait que les composants effectuent un rendu répété à chaque changement d'état ou d'accessoires. Ainsi, lorsque nous définissons l'état de couleur dans useEffect cela provoque un rendu et une boucle infinie.

Heureusement, cela est facile à résoudre. Le hook useEffect accepte un 2ème paramètre, qui est un tableau d'états et/ou d'accessoires à surveiller. Cela signifie que la fonction ne s'exécutera que lorsque l'un des états/accessoires surveillés change. Nous voulons que la couleur ne change que lorsque notre nombre change, nous mettons donc à jour notre useEffect à :

useEffect(() => {
    setColour(randomColor())
  }, [count])

Remarque : pour exécuter useEffect une seule fois, lors du chargement du composant, ajoutez un tableau vide comme deuxième paramètre

Maintenant, lorsque nous mettons à jour notre widget… VOILA !

Récap

Dans ce blog, nous avons expliqué comment utiliser les widgets enfichables avec Mendix, comment configurer votre environnement de développement et certains concepts de base de React, notamment l'état, les accessoires et useEffect.

Le code final du widget peut être trouvé ici : GitHub – joe-robertson-mx/colorCount

Et ensuite?

Ensuite, nous commencerons à utiliser Typescript, à intégrer directement avec Mendix entités et attributs, et voyez comment déclencher des actions dans notre Mendix modèle de notre widget.

Dites-nous ce que vous pensez de cet article. Y a-t-il des widgets que vous aimeriez voir apparaître ? N'hésitez pas à nous faire part de vos suggestions de widgets futurs dans les commentaires ici.

Ressources

Pour en savoir plus sur les widgets enfichables, les ressources suivantes peuvent être utiles : Premiers pas – React, Créez des widgets Web enfichables,