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. Nous avons établi ces consignes afin de rendre votre bibliothèque de blocs aussi polyvalente et utile que possible.

Consignes

• Faites en sorte que les utilisateurs puissent installer facilement tous vos blocs, et possible pour les utilisateurs d'installer uniquement certains blocs ou éléments de blocs de leur choix.
  • Simplifiez l'installation: vous pouvez le faire en fournissant une fonction qui installe chaque élément requis par une définition de bloc unique (par exemple, des mutateurs, des extensions, des mixins, des champs, etc.). Vous pouvez également fournir une fonction qui installera simultanément tous les blocs proposés par votre plug-in.
  • 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 en guise d'effet secondaire du chargement de votre plug-in. Les utilisateurs doivent garder le contrôle sur les éléments installés et le moment. Cela permet aux utilisateurs d'importer les pièces dont ils ont besoin sans craindre que celles qui ne sont pas installées seront installées.

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

  • Déconseillé : instancier un nouveau champ directement :

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

  • Recommandé - 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 de suppositions 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 proposera 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 mutateur, un mixin ou un champ.
  • Indiquez clairement les conditions préalables ou les dépendances requises par les définitions de plug-in ou de bloc.

• Envisagez de fournir des fonctions de générateur pour chacun des blocs que vous fournissez.

  • Grâce à des fonctions de générateur prêtes à l'emploi, il est plus facile pour les utilisateurs d'utiliser vos blocs sans avoir à comprendre leur structure et leur conception. S'ils doivent écrire leurs propres fonctions de générateur, chaque utilisateur peut effectuer des tâches redondantes.
  • JavaScript est le langage le plus couramment utilisé dans Blockly. Par conséquent, si vous ne choisissez qu'un seul langage à fournir, nous vous recommandons JavaScript, sauf si vos blocs sont créés pour un langage spécifique, tel que l'implémentation d'une bibliothèque Python.
  • Envisagez de publier les problèmes de type "aide demandée" pour les langages pour lesquels vous ne parvenez pas à implémenter des fonctions de générateur et acceptez les requêtes d'extraction 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 prenez en charge, vous pouvez installer automatiquement la fonction du générateur de code en bloc et effectuer des tâches connexes, 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 respecter ces consignes dans votre plug-in, n'hésitez pas à nous contacter sur le forum. Nous serions ravis de voir vos bibliothèques de blocs et de nous faire part de vos commentaires.

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