# Écrire un composant Flow : un fichier HTML

> Un composant Flow est un seul fichier HTML avec une partie Node.js, un formulaire de réglages et un design. Construisez-en un qui change le texte d’un message, découvrez les parties du fichier et comment le tester.

Framework: flow
Product: Flow (flow@11.1)
Language: fr
Content-SHA256: 069dbfc23730566a6f7e9f37f7de03c3cdcc8d54ff570a038496682cfdcf9f80
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Un composant est **un fichier `.html`**. Flow lit le fichier, exécute sa partie Node.js dans le flux et affiche son design dans l’éditeur. Les composants officiels de [le dépôt](/en/flow/the-components-repository/) utilisent tous ce format ; vous pouvez donc lire n’importe lequel comme exemple.

## Un exemple : `shout.html`

Il reçoit un message, convertit le texte en majuscules, ajoute un suffixe et le transmet.

```html
<script total>

	exports.id = 'shout';
	exports.name = 'Shout';
	exports.group = 'Common';
	exports.version = '1';
	exports.icon = 'ti ti-speakerphone';
	exports.author = 'Forge';
	exports.config = { suffix: '!' };
	exports.inputs = [{ id: 'input', name: 'Input' }];
	exports.outputs = [{ id: 'output', name: 'Output' }];

	exports.make = function(instance, config) {

		let count = 0;

		instance.message = function($) {
			count++;
			instance.status({ shouted: count });
			$.data = String($.data).toUpperCase() + config.suffix;
			$.send('output');
		};

	};

</script>

<settings>
	<div class="padding">
		<ui-component name="input" path="?.suffix" config="maxlength:10">Suffix</ui-component>
	</div>
</settings>

<readme>
The component converts the text of a message to upper case and adds a suffix.
</readme>

<body>
	<header>
		<i class="ICON"></i>NAME
	</header>
	<footer>
		<div class="padding">Shouted: <b><ui-bind path="STATUS.shouted" config="text:value||0"></ui-bind></b></div>
	</footer>
</body>
```

## Les parties du fichier

| Partie | À quoi elle sert |
|---|---|
| `<script total>` | le code Node.js du composant, exécuté dans le processus du flux |
| `<settings>` | le formulaire de configuration, avec les composants de l’interface utilisateur (`ui-component`, les chemins qui commencent par `?.` pointent vers le `config` du composant) |
| `<readme>` | l’aide affichée dans l’éditeur |
| `<body>` | la boîte dans le diagramme : un `<header>` avec les marqueurs `ICON` et `NAME`, et éventuellement un `<footer>` ou un corps, où `<ui-bind path="STATUS.x">` affiche le statut et `CONFIG.x` la configuration |
| `<style>` | le CSS de la boîte ; `.CLASS` est remplacé par une classe unique du composant |
| `<script>` (second) | JavaScript facultatif de l’éditeur, pour les boutons de la boîte (il peut envoyer `{ TYPE: 'trigger', id: ... }` au flux) |

## Les `exports` de la partie Node.js

| Export | Signification |
|---|---|
| `id`, `name`, `group`, `version`, `icon`, `author` | l’identité du composant et où il apparaît dans la liste |
| `config` | la configuration par défaut ; le formulaire de `<settings>` la modifie |
| `inputs`, `outputs` | la liste des connecteurs `{ id, name }`. Un composant sans `inputs` est une source |
| `kind` | facultatif : le rôle du composant dans le catalogue (`trigger`, `action` ou `output`) |
| `make(instance, config)` | appelé une fois par boîte que vous placez dans le diagramme |

## L’`instance`

Dans `make`, vous définissez le comportement en affectant des fonctions à l’instance :

| Fonction | Appelée quand |
|---|---|
| `instance.message = function($) {}` | un message arrive. `$.data` est la donnée, `$.send('output')` la transmet aux connecteurs de cette sortie, `$.destroy()` la termine sans l’envoyer |
| `instance.configure = function() {}` | la configuration change, et une fois au démarrage |
| `instance.trigger = function() {}` | le bouton de l’éditeur ou le code la demande |
| `instance.pause = function(is) {}` | le flux est mis en pause ou repris |
| `instance.close = function() {}` | la boîte est supprimée ou le flux s’arrête : nettoyez vos minuteurs ici |

Et vous appelez `instance.send('output', data)` pour créer un message à vous (comme le fait `timer`), `instance.status(object)` pour afficher un statut dans la boîte (`delay.html` passe un temps en millisecondes en second argument pour le rafraîchir) et `instance.throw(error)` pour signaler une erreur.

## Essayez

1. Mettez `shout.html` dans un catalogue et écrivez son adresse dans le réglage `components2` (voir [le dépôt](/en/flow/the-components-repository/)), ou importez un flux qui le contient dans ses `components`.
2. Ajoutez à côté un `timer` et un `print` dans l’éditeur, reliez-les et démarrez le flux.
3. Ouvrez le statut de la boîte : le compteur augmente à chaque message.

Pour tester un composant sans l’éditeur, le dépôt possède un petit testeur, voir [le dépôt des composants](/en/flow/the-components-repository/).