Cómo publicar bibliotecas de bloques

Los complementos que proporcionan bibliotecas de definiciones de bloques son una excelente manera de compartir tus bloques reutilizables con la comunidad de Blockly. Para que tu biblioteca de bloques sea lo más versátil y útil posible, desarrollamos estos lineamientos.

Lineamientos

• Facilita a los usuarios la instalación de todos tus bloques y haz que sea posible que los usuarios instalen solo ciertos bloques o partes de bloques que elijan.
  • Facilita la instalación de todo: puedes hacerlo proporcionando una función que instale todas las piezas que requiere una sola definición de bloque (como mutadores, extensiones, combinaciones, campos, etcétera). También puedes proporcionar una función que instale todos los bloques que ofrece el complemento a la vez.
  • Permite elegir partes específicas: debes exportar todas las partes de una definición de bloque por separado, de modo que un usuario pueda importar solo las partes que necesita para crear su propio bloque personalizado similar.
• Evita usar efectos secundarios en el complemento.
  • Los bloques, los campos, las extensiones y otros elementos no deben instalarse como un efecto secundario de la carga del complemento. Los usuarios deben mantener el control sobre qué elementos se instalan y cuándo. Esto permite a los usuarios importar las piezas que necesitan sin preocuparse de que se instalen piezas que no.

• Usa el registro de campos JSON en lugar de crear instancias de campos nuevos directamente.

  • No recomendado: Creando una instancia de un campo nuevo directamente:

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

  • Recomendado: Registro de campos JSON:

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

  • El uso del registro de campo facilita que un usuario reemplace la implementación del campo que se usa en tu bloque sin tener que cambiar la definición del bloque.

• No hagas suposiciones sobre lo que el usuario ya instaló.

  • Si tu complemento requiere un campo personalizado o algún otro complemento, registra esos campos por tu cuenta en la función install proporcionada.
  • Pronto, Blockly proporcionará herramientas que te permitirán registrar elementos ya registrados sin errores. Hasta entonces, te recomendamos verificar lo que ya se registró antes de registrar una extensión, un mutador, una combinación o un campo por tu cuenta.
  • Ten en claro los requisitos previos o las dependencias que requieren tu complemento o las definiciones de bloque.

• Considera proporcionar funciones de generador para cada uno de los bloques que proporciones.

  • Proporcionar funciones de generador que estén listas para usar facilita que los usuarios usen tus bloques sin tener que comprender su estructura ni su diseño. Si tiene que escribir sus propias funciones de generador, es posible que cada usuario realice un trabajo redundante.
  • JavaScript es el lenguaje más usado en Blockly, por lo que, si solo eliges un lenguaje para proporcionar, te recomendamos JavaScript, a menos que tus bloques estén compilados para un lenguaje específico como la implementación de una biblioteca de Python.
  • Considera publicar problemas de “ayuda que se busca” en los idiomas en los que no puedes implementar funciones de generación y acepta solicitudes de extracción para estos si un usuario las contribuye.

  • Si proporcionas una función de instalación para el bloque, puedes aceptar un parámetro generators opcional. Si un usuario pasa una instancia de generador que admites, puedes instalar automáticamente la función de generador de código de bloque y realizar tareas relacionadas, como agregar palabras reservadas:

      // 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});
    

Comentarios

Si tienes preguntas sobre cómo seguir estos lineamientos de la mejor manera en tu complemento, escríbenos en el foro. Nos encantaría ver tus bibliotecas de bloques y proporcionar comentarios sobre ellas.

Ten en cuenta que, actualmente, no todos los complementos propios que proporcionan definiciones de bloqueo siguen estos lineamientos, pero los complementos nuevos sí lo harán y planeamos migrar los existentes.