Publier des bibliothèques de blocage

Les plug-ins qui fournissent des bibliothèques de définitions de blocs sont un excellent moyen de partager vos blocs réutilisables avec la communauté Blockly. Pour rendre votre bibliothèque de blocs aussi polyvalente et utile que possible, nous avons développé ces consignes.

Consignes

Permettez aux utilisateurs d'installer facilement tous vos blocs, et de n'installer que certains blocs ou éléments de blocs de leur choix.
- Facilitez l'installation de tout: pour ce faire, fournissez une fonction qui installe chaque élément requis par une seule définition de bloc (tels que les mutators, les extensions, les mixins, les champs, etc.). Vous pouvez également fournir une fonction qui installera tous les blocs proposés par votre plug-in en même temps.
- Faites en sorte qu'il soit possible de choisir des pièces spécifiques: vous devez exporter tous les éléments d'une définition de bloc séparément, afin qu'un utilisateur puisse importer uniquement les éléments dont il a besoin pour créer son propre bloc personnalisé similaire.
Évitez d'utiliser des effets secondaires dans votre plug-in.
- Vous ne devez pas installer de blocs, de champs, d'extensions et d'autres éléments comme effet secondaire du chargement de votre plug-in. Les utilisateurs doivent conserver le contrôle sur les éléments installés et le moment où ils le sont. Cela permet aux utilisateurs d'importer les éléments dont ils ont besoin sans avoir à se soucier de l'installation d'éléments dont ils n'ont pas besoin.

Utilisez le registre de champs JSON au lieu d'instancier directement de nouveaux champs.

Non recommandé : instanciation directe d'un nouveau champ :

  const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(new Blockly.FieldNumber(123), 'NAME');
    }
  }

Recommandation : Registre de champs JSON :

  export const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(Blockly.fieldRegistry.fromJson({
              name: 'field_number',
              value: 123,
            }), 'NAME');
    }
  }

L'utilisation du registre de champs permet à un utilisateur de remplacer plus facilement l'implémentation du champ utilisé dans votre bloc sans avoir à modifier la définition du bloc.

Ne faites pas d'hypothèses sur ce que l'utilisateur a déjà installé.
- Si votre plug-in nécessite un champ personnalisé ou un autre plug-in, enregistrez ces champs vous-même dans la fonction install fournie.
- Blockly fournira bientôt des outils qui vous permettront d'enregistrer des éléments déjà enregistrés sans erreur. En attendant, vous pouvez vérifier ce qui a déjà été enregistré avant d'enregistrer vous-même une extension, un mutator, un mixin ou un champ.
- Indiquez clairement les conditions préalables ou les dépendances requises par vos définitions de plug-in ou de bloc.
Envisagez de fournir des fonctions génératrices pour chacun des blocs que vous fournissez.
- Fournir des fonctions de générateur prêtes à l'emploi permet aux utilisateurs d'utiliser plus facilement vos blocs sans avoir à comprendre leur structure et leur conception. S'ils doivent écrire leurs propres fonctions de générateur, cela peut entraîner un travail redondant de la part de chaque utilisateur.
- JavaScript est le langage le plus couramment utilisé dans Blockly. Par conséquent, si vous ne choisissez qu'un seul langage, nous vous recommandons de choisir JavaScript, sauf si vos blocs sont conçus pour un langage spécifique, comme l'implémentation d'une bibliothèque Python.
- Envisagez de publier des problèmes "aide requise" pour les langues pour lesquelles vous ne parvenez pas à implémenter des fonctions de générateur, et acceptez les demandes de tirage pour ces langues si un utilisateur y contribue.
- Si vous fournissez une fonction d'installation pour votre bloc, vous pouvez accepter un paramètre generators facultatif. Si un utilisateur transmet une instance de générateur que vous acceptez, vous pouvez installer automatiquement la fonction de générateur de code de bloc et effectuer des tâches associées, telles que l'ajout de mots réservés:
```
  // Your plugin's install function
  export const installMyCustomBlock(generators = {}) {
    Blockly.defineBlocks({my_custom_block: myCustomBlock});
    if (generators.javascript) {
      generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
      generators.javascript.addReservedWords('specialReservedWord');
    }
  }

  // How a user may install your block
  import {javascriptGenerator} from 'blockly/javascript';
  import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
  // installs the block definition and the javascript block-code generator
  installMyCustomBlock({javascript: javascriptGenerator});
```

Commentaires

Si vous avez des questions sur la meilleure façon de suivre ces consignes dans votre plug-in, n'hésitez pas à nous contacter sur le forum. N'hésitez pas à nous faire part de vos commentaires sur vos bibliothèques de blocs.

Notez que tous les plug-ins propriétaires qui fournissent des définitions de bloc ne suivent actuellement pas ces consignes, mais les nouveaux plug-ins le seront et nous prévoyons de migrer les plug-ins existants.