Guía de codificación y recomendaciones

<< Clic para mostrar Tabla de Contenidos >>

Navegación:  Bizagi Studio > Asistente de Procesos > Definir Formas > Extender o personalizar las formas > Crear Widgets > Estructura de un Widget > API de Widgets >

Guía de codificación y recomendaciones

Introducción

Cuando se crea un Widget, usted podrá apoyarse en el API como se describe en API de Widgets.

Es también importante que usted siga las recomendaciones para implementar código y para aplicar estilos (tanto para JS como para CSS).

 

Guía de codificación en JS

Para seguir las mejores prácticas de desarrollo HTML y prevenir conflictos cuando cree sus propios Widgets, tenga en cuenta esta guía:

 

Cuando sea posible, evite el uso de Selectores de jQuery que manejen directamente los IDs de los elementos HTML.

En vez de esto, utilice clases y tenga sus propios selectores de jQuery (http://api.jquery.com/category/selectors/) buscando por ellos e incluyendo el contexto.

Por ejemplo, usted puede usar $(‘.miClase’, miContexto) para seleccionar aquellos elementos con la clase miClase que estén dentro del elemento específico miContexto (e.g dentro de una división -<div>).

También podrá apoyarse en el método find() de jQuery de por sí, por ejemplo, utilizando $(self.myDiv).find('#myElementID').

 

No utilice document.ready() porque su implementación al menos considerará cuándo el Widget (un control en la forma) está listo y Bizagi seguirá manejando la forma del documento.

En cambio, usted puede usar this.ready() o lanzar una función después de algunos milisegundos (usando .setTimeout()).

Sin embargo, el uso más ideal es que considere implementar el comportamiento del Widget dentro de la función renderComplex() la cuál se ejecuta una vez que el Widget y la forma de Bizagi hayan sido cargadas en su totalidad.

 

No use las funciones window.alert() o .confirm() de javascript en el modo de diseño (cuando el Widget se previsualiza en el diseñador de formas).

 

No use la propiedad visual zIndex de los elementos HTML.

El motor de renderizado de Bizagi calcula y organiza la información en las formas de manera adecuada. Usando este parámetro, se afectará la forma en que Bizagi organiza la información.

 

Mantenga un registro de los nombres de las funciones que implemente.

Como una buena práctica, dé un namespace a las librerías de funciones y a las propiedades que incluya.

Para instancias, observe que "autocomplete()" es una función que ya implementa jQuery UI como una función nativa y por lo tanto, no puede nombrar ninguna de sus funciones como autocomplete().

Para manejar esta situacióm, primero debe buscar en la documentación de jQuery para saber qué nombres de funciones ya están en jQuery (en

http://api.jqueryui.com/category/methods/ y http://api.jqueryui.com/category/widgets/).

Para asegurarse de que no esté usando un nombre existente (para evitar conflictos potenciales), usted puede usar las herramientas de depuración provistas por el navegador.

Para esto, vaya a la consola de JS y digite $.fn.:

 

Widgets12

 

Note que esto le mostrará (a través del intelliSense) una lista de todas las funciones cargadas (fn), las cuales ya son provistas por jQuery (a través de la notación "$").

Para más información sobre estas opciones, consulte Solucionador de problemas de los Widgets.

 

Para lo anterior (cuando implemente sus propias funciones) o cuando importe plugins o versiones específicas de jQuery, asegúrese de asignar un namespace para evitar conflictos.

El escenario común es que usted no necesite incluir la librería jQuery, dado que Bizagi automáticamente ya la contiene, en una versión que es compatible para soportar a versiones antiguas.

Una manera eficiente de validar que su plugin es compatible con la versión de jQuery que utiliza Bizagi, es ejecutar el demo del plugin mientras que se utiliza la versión que soporta Bizagi (v 2.1.0. tal como se encuentra disponible en https://code.jquery.com/jquery-2.1.0.min.js).

 

Usted debe dividir la lógica en el código de manera que el Widget simplemente muestre una vista preliminar en el diseñador de formas.

para ello usted puede apoyarse en la función getMode().

Note que esto es importante ya que usted si debe mostrar una previsualización del Widget (cómo se verá, cuánto espacio ocupa y dónde), usted no querrá activar su comportamiento tal y como si será en ejecución.

 

Cuando sea aplicable, es una buena idea que sus Widget sean compatibles con propiedades existentes similares a los de los controles de Bizagi, especialmente si su Widget sobrescribe la funcionalidad de un control de Bizagi (por ejemplo, cuando se crea un Widget que permite a los usuarios cargar archivos, entonces se recomienda ya sea implementar o reutilizar las propiedades del control de archivos de Bizagi, como lo son el tamaño máximo de archivo, extensión de archivo permitida, etc).

 

Usted debe separar el código de su Widget, sobrescribiendo la función renderComplex() por un lado, para implementar el comportamiento netamente del Widget (lo que usualmente tiene una página HTML codificado en JS). Y por otro lado, implementar la apariencia del Widget dentro de las funcionse getReadOnlyControl() y getEditableControl() respectivamente (los elementos HTML como tal).

 

 

Guía de estilos de CSS

Para seguir las mejores prácticas de desarrollo en HTML y para una fácil mantenibilidad y personalización de sus Widgets, siempre debe incluir un archivo CSS para los estilos usados por los Widgets.

 

Bizagi ofrece la posibilidad de considerar diferentes estilos CSS para la implementación entre diferentes dispositivos, en los cuales, se debe tener en cuenta el siguiente lineamiento:

 

Dar un nombre único a sus clases (e IDs si estos son completamente necesarios, pero es mejor evitarlos).

Esto es, porque eventualmente usted puede tener más de un Widget dentro de la misma forma. Cuando esto pase, usted no querrá que las funciones de sus Widgets empiecen a entrelazarse y presentar comportamientos inesperados.

 

No aplique estilos a elementos globales.

Esto afectará los estilos por defecto en el Portal de Trabajo de Bizagi. Esto significa NO definir estilos al elemento body (<body>), a imágenes en general, etc.

En otras palabras, solo defina estilos para clase específicas de su Widget.

 

Es mejor definir el ancho de los elementos en valores de porcentaje (i.e 100%).

Esto evita tener que realizar el calculo de pixeles para los diferentes escenarios en los cuales se puede configurar un Widget (como: dentro de un layout, dentro de un grupo, mostrado para dispositivos móviles, etc).

Nunca se deben definir posiciones bajo un CSS de position: fixed.

 

Siempre defina una clase para sus elementos (aún así sus estilos sean vacíos.

Para esto, se debe agregar la clase de los elementos que cree en su Widget y de esta manera, puede ofrecer la posibilidad de modificar rápidamente colores e indicar dónde hacerlo.

Recuerde que puede usar .addClass() y .removeClass() en cualquier momento en su implementación JS para asignar o remover clases de sus elementos HTML.

 

Usted podrá reutilizar ciertos estilos de clases que ya se utilizan en Bizagi para elementos específicos de las formas, tales como botones, campos input, o etiquetas.

Es importante que NO sobrescriba estas definiciones, solo las use para asignar clases existentes de Bizagi a sus propios elementos para que éstos hereden sus estilos.

Para botones, usted podrá utilizar: ui-bizagi-button.

Para etiquetas, usted podrá utilizar : ui-bizagi-label.

Para campos input, usted podrá utilizar: ui-bizagi-render-text.

 

Se recomienda enfáticamente definir estilos que apliquen a sus elementos siempre especificando que son elementos anidados dentro de su división principal del Widget (<div>).

Esto significa, definir cuando sea posible que los estilos apliquen solo a subelementos dentro del Widget.

No hacerlo solo así:

.MyInputClass {

 margin: 5px;

}

Sino asegurarse que primero se busque el div principal:

.MyFirstWidget_MainDivClass .MyInputClass {

 margin: 5px;

}

 

 

Este es un ejemplo de una hoja de estilos:

 

WidgetEditor_CSS