Widgets en Jitterbit App Builder

Descripción general

Los widgets en App Builder permiten a los desarrolladores proporcionar código de terceros (o propio) para mostrar un control personalizado en la página. Los widgets permiten definir más metadatos; consulte la sección "Contenido del archivo" para más detalles. Los parámetros ahora admiten una definición más robusta; consulte la sección "API de widgets" para más detalles.

Consulte la biblioteca de descarga de widgets para obtener una lista de widgets compatibles que puedes usar en App Builder.

Pautas para widgets

1. Los widgets deben mostrar el valor subyacente, o debe ser obvio cuál es.

   • Bueno: Valor mostrado

     
     

   • Bueno: Valor evidente

     
     

   • Malo:

     

2. Prueba del widget. Recuerde considerar cómo interactuará con el widget en dispositivos táctiles y no táctiles.

3. Los widgets deben respetar la edición y el guardado automáticos. El App Builder los configurará automáticamente.

Contenido del archivo de archivo

_manifest.json

Todos los widgets incluyen un archivo de manifiesto. Puedes definir más metadatos en este archivo, como se describe a continuación.

{
    "name": "Slider",
    "developer": "App Builder",
    "binder": "binder.js",
    "template": "view.html",
    ...
    "targetContainer": false,
    "purpose": "Site",
    "parameters": [
        {
            "name": "Parameter name",
            "default": "default value",
            "translate": true
        }
    ]
}

• name: El nombre del widget que aparecerá en el IDE de App Builder y también se convertirá en el nombre del archivo de almacenamiento.

• developer: El nombre de usuario del desarrollador que trabaja en este widget.

• binder: El nombre del archivo del enlazador de widgets. Consulte más información a continuación.

• template: El nombre del archivo HTML de la modelo. Consulte más información a continuación.

• targetContainer: Apoya el valor true o false.

• purpose: Admite el valor definido de Site o Field, que indica cómo se debe usar el widget.

• parameters: Admite una matriz de metadatos de parámetros para cada uno:

  • name: el nombre del parámetro
  • default: una cadena que contiene el valor predeterminado
  • translate: admite el valor true o false

• Versión: Número de versión del widget. Incremente este número para garantizar que los usuarios reciban la última edición de su código.

• CreatedOn: Fecha de lanzamiento de esta versión. Solo con fines informativos.

• Dependencias: Lista delimitada por comas de las dependencias requeridas por el enlazador de widgets. El orden en que aparecen estos archivos coincidirá con el orden en que aparecerán en la matriz de dependencias de la API de widgets. Asegúrese de incluir la extensión del archivo.

  • JavaScript
  • CSS

  Por ejemplo, si define una biblioteca que devuelve una referencia que necesita usar para instalar en un elemento:

  Manifest Entry

  "javascript": [
    "noUiSlider.8.0.2/nouislider.js",
    "noUiSlider.8.0.2/nouislider_extras.js"
  ]
  

  El contexto de la API de tu widget incluiría ambos objetos:

  Usage

  var install = function (holderElement, context) {
    var sliderLibrary = context.loadedDependencies[0];
    sliderLibrary.createSlider(holderElement);
  }
  

  Nota

  Incluso si no tiene dependencias, incluya las propiedades de JavaScript y CSS con una matriz vacía.

  Manifest Entry

  "javascript": [],
  "css": []
  

carpeta.js

carpeta.js

define(function () {
    return {
        callbacks: {
            events: {
                install: function (holderElement, context) {},
                uninstall: function (holderElement, context) {}
            }
        }
    };
});

El enlazador proporciona dos devoluciones de llamada necesarias para enlazar la API de App Builder con tus bibliotecas. En cada una, se proporcionan dos parámetros de función.

• holderElement: Un elemento DOM que contiene el marcado HTML proporcionado en el archivo de modelo especificado. Dado que este archivo es opcional, el elemento contenedor puede estar vacío. El elemento contenedor es la celda que desplegará el widget. Es el área resaltada en la captura de pantalla a continuación y no incluye la etiqueta del campo.
  

  

• context: Una instancia del contexto de la API del widget. Este objeto contiene todas las dependencias de JavaScript especificadas en el enlazador, así como el acceso a los datos de la celda y el panel.

• view.html (opcional): Este archivo contiene todo el HTML estático necesario para cargar este widget. Si no se especifica, el widget se creará sin contenido y la llamada de instalación definida en el enlazador deberá generar el HTML necesario.

API de widgets

obtenerCelda()
Devuelve una instancia de WidgetApiCell.

obtenerFila()
Devuelve una instancia de WidgetApiRow.

isEditState() - booleano
Identifica si la fila es editable.

getParameter(nombre) - cadena
Recuperará el parámetro definido ya sea del valor predeterminado o de la celda de esta fila que fue nombrada por el diseñador.

Dependencias cargadas
Una propiedad que contiene una matriz de objetos devueltos por RequireJS. Esta matriz se proporciona en el mismo orden en que se definen las dependencias en el archivo _manifest.json.

WidgetApiCell
Representa una sola celda. Las celdas son el modelo de vista de respaldo del control que se ve en la página. Contienen valores, se pueden monitorear los cambios y existen en una fila de una tabla.

valor - cadena
Esta propiedad se puede utilizar para obtener y establecer el valor subyacente de la celda.

customTextbox.on('change', function (value) {
    cell.value = value;
});

formattedValue - string
Esta propiedad permite obtener y establecer el valor de visualización subyacente de la celda. Por ejemplo, el valor subyacente de un campo de porcentaje sería 0,25, mientras que el valor de visualización (valor formateado) sería "25%". O bien, un control de lista podría tener un GUID, mientras que el valor formateado sería el nombre y apellidos de un cliente.

persistedValue - string
Esta propiedad permite obtener el valor persistente subyacente de la celda. Un valor persistente es el valor sin editar almacenado actualmente en la fuente de datos. Esto permite restaurar una celda a un estado limpio.

setDataChangeCallback
Esta función permite configurar las devoluciones de llamada para que se ejecuten cuando el formulario en el que se encuentra el widget obtenga nuevos datos.

context.setDataChangeCallback(function () {
   var updatedMin = parseInt(context.getParameter("Min"), 10);
});

setChangeCallback(nombre: cadena, valor: Función)
Esta función se utiliza para establecer devoluciones de llamada en una celda. Se pueden definir las siguientes devoluciones de llamada con nombre:

• valor
• valorformateado
• deshabilitado

cell.setChangeCallback('value', function (value) {
    console.log("The cell's value has been changed to", value);
});

App Builder puede generar cambios en la celda durante eventos de validación, si se establecen valores predeterminados o si otro widget genera cambios que la afecten. App Builder también puede deshabilitar celdas durante la ejecución de eventos.

App Builder pasará un único parámetro a la devolución de llamada proporcionada con el valor modificado. Si está deshabilitado, el valor es verdadero o falso.

dropChangeCallback(nombre: cadena)
Elimina la suscripción a una devolución de llamada de cambio.

Fila de API de widgets Representa una fila en la fuente de datos. Esta fila contiene la celda que implementa el widget.

getCellByColumnName(nombre: cadena) - WidgetApiCell
Devuelve una instancia de una celda en esta fila. El nombre distingue entre mayúsculas y minúsculas y debe coincidir con el nombre definido en el control, no con el nombre de la fuente de datos.

editar()
Cambia la fila al modo de edición.

guardar()
Guarda cualquier valor modificado en la fuente de datos.

eliminarFila()
Intentará eliminar la fila de la fuente de datos.

Parámetros
Los parámetros de un widget se pueden definir a nivel de panel. Al añadir un parámetro, el desarrollador puede configurar:

• Parámetro del widget: Nombre asignado al valor del parámetro.

• Tipo de parámetro: El valor predeterminado es Control, también se puede definir como Column o Static Value Dependiendo del tipo que defina, tendrá diferentes valores para configurar:

  • Control:
    • Control de destino: un control del panel principal que proporcionará este valor de parámetro.
    • Usar valor formateado: utiliza el valor de visualización formateado.
    • Activo: Indica si este enlace está activo o no. Los enlaces inactivos no se utilizarán.
  • Columna:
    • Columna de destino: una columna de la tabla de origen del panel principal que proporcionará este valor de parámetro.
    • Usar valor formateado: utiliza el valor de visualización formateado.
    • Activo: Indica si este enlace está activo o no. Los enlaces inactivos no se utilizarán.
  • Valor estático:
    • Valor: Valor estático para el parámetro.
    • Traducible: si está habilitado, permite que el widget se traduzca cuando corresponda.
    • Activo: Indica si este enlace está activo o no. Los enlaces inactivos no se utilizarán.

Cómo crear un widget y solución de problemas

Los widgets son una página en blanco. App Builder ejecutará el código del widget en lugar de su despliegue.

Mostrando el valor actual Si está renderizando un termómetro, por ejemplo, probablemente necesitará incluir el valor actual junto con el nivel de mercurio. (vea el texto de ejemplo de $3,500 a continuación)

Sin embargo, es posible que un widget de calificación de estrellas no necesite indicar el valor de celda real.

Cómo obtener y configurar el valor de App Builder en su widget
App Builder puede actualizar el valor mediante valores predeterminados o cambios en los registros principales. Su biblioteca deberá poder actualizarse automáticamente cuando se produzcan estos eventos.

Proporcionar devoluciones de llamada permite que App Builder ejecute tu código cuando necesite enviar nuevos valores a tu widget. Consulta setChangeCallback más arriba.

Además, al instalar una biblioteca, normalmente deberá establecer el valor inicial desde la celda proporcionada. App Builder no ejecutará la devolución de llamada de cambio durante la instalación, solo cuando los eventos lo requieran.

Subiendo nuevas versiones y depurando
Una vez que tenga un widget operativo y esté depurando un error, siga los siguientes pasos:

1. Comprime el contenido de la carpeta local en la que estás trabajando (asegúrate de no comprimir la carpeta principal, ya que esto creará una carpeta adicional en el archivo zip).
2. Sube el archivo zip del widget a la aplicación Look & Feel
3. Actualiza la página con tu widget. Nota: Es posible que tengas que desactivar la caché de tu navegador durante el desarrollo; de lo contrario, podrías obtener código obsoleto.

Ver vs. Editar estado
Al añadir un widget a un panel, puede especificar si este gestionará la representación tanto del estado de edición como del de vista. Si su widget solo gestiona el estado de edición, App Builder representará el valor de la celda en el estado de vista.

Si su widget maneja ambos estados, su control PUEDE usarse para editar valores sin necesidad de hacer clic primero en el botón de edición de la barra de herramientas.

Para ello, debe cambiar la fila al estado de edición si aún no lo está. A continuación, se muestra un ejemplo:

if (!context.isEditState()) {
  context.getRow().edit();
}
context.getCell().value = myNewValueVariable;
context.getRow().save();

También puedes usar la propiedad isEditState para generar una versión de "solo lectura" del widget que muestre el valor pero que no se pueda usar para modificar la celda.

Cargando dependencias grandes
Recursos grandes como JQuery UI tardan mucho en descargarse e instalarse. Por motivos de rendimiento, se recomienda desplegar solo bibliotecas ligeras o que utilicen dependencias existentes de App Builder. Se han reportado algunos errores cuando las dependencias se cargan con demasiada lentitud.

Trabajando con datos binarios Algunas celdas de App Builder pueden contener datos binarios almacenados como una cadena base64. Se pueden usar bibliotecas para modificar y almacenar datos en estas celdas, como utilidades de edición de imágenes. Consulte la biblioteca Image Resizer en la colección de App Builder para ver un ejemplo de código.

fila.ViewModel
La versión actual de App Builder expone un parámetro llamado ViewModel en la API de fila. Esto proporciona acceso a los datos de backend de App Builder y no se garantiza su funcionamiento al actualizar App Builder. No se recomienda escribir código que dependa de esta propiedad.

Widgets del sitio

Los widgets también pueden ser a nivel de sitio. Esto se define a nivel de widget y se utilizan en Centro de control > Configuración de instancia > Widgets del sitio.

Los widgets del sitio se ejecutan en cuanto se carga el navegador. Esto permite que el código se ejecute lo antes posible. El código se ejecutará de forma asíncrona, lo que significa que la página no esperará a renderizarse hasta que se ejecute el código.

Los parámetros del sitio no están vinculados a datos, solo admiten valores de texto sin formato.

Cómo agregar un widget de sitio en App Builder

1. Vaya a App Workbench > Look & Feel > Widgets
   
2. Seleccione la Colección a la que desea agregar el widget
   
3. Haga clic en el botón + Widget
4. Asigne un Nombre al widget. Por ejemplo: Widget de marcación
5. Haga clic en Explorar y localice el archivo .zip del widget que contiene todos los archivos de widget necesarios, selecciónelo y haga clic en Abrir
6. Proporcione cualquier Documentación que describa el widget. La información de texto de ayuda que aparece en el IDE para un widget se proporciona mediante el registro del widget.
7. Haga clic en Guardar
8. En el panel Parámetros del widget, haga clic en + Parámetro y defina los parámetros necesarios para el widget.
9. En la página que ejecutará su widget, seleccione el widget en la región Información del widget del Diseñador de controles y configure los valores Interfaz y Modo activo
   

API

getParameter(nombre) - cadena
Recuperará el parámetro definido ya sea del valor predeterminado o del parámetro proporcionado por el diseñador a través de la definición del widget del sitio.

getCurrentPageLocation() - cadena
Obtiene la URL actual de la página.

getCurrentAuthenticationUserName() - cadena
Obtiene el nombre de usuario actualmente conectado o nulo si no está autenticado.

onPageLocationChange(controlador: Función(evento))
Esta función se utiliza para configurar las devoluciones de llamada que se ejecutan al cambiar la ubicación de la página. Devuelve la ruta como una cadena.

onAuthenticationChange(handler: Function(event))
Esta función se utiliza para configurar las devoluciones de llamada que se ejecutan cuando el usuario autenticado cambia. Devuelve el nombre de usuario como una cadena.

Solución de problemas

App Builder admite atajos de teclado, con el que algunas bibliotecas de widgets pueden entrar en conflicto. App Builder actualmente admite las siguientes teclas de acceso rápido: text; enter; esc; left-arrow; up-arrow; right-arrow; down-arrow; backtick; y delete Las siguientes instrucciones le permiten deshabilitar la compatibilidad con atajos de teclado para un elemento HTML determinado y sus elementos secundarios.

Para ignorar todos los atajos de teclado, utilice una clase CSS o el valor del campo de datos. vinyl-hotkeys-ignore:

• <div class="vinyl-hotkeys-ignore"></div>- <div data-vinyl-hotkeys-ignore="true"></div>Para ignorar solo algunas combinaciones de teclas, añádalas al sufijo de la clase CSS. Si hay más de una palabra, sepárelas con guiones en el sufijo de la clase CSS:

• <div class="vinyl-hotkeys-ignore-text"></div>- <div data-vinyl-hotkeys-ignore-text="true"></div>- <div class="vinyl-hotkeys-ignore-left-allow"></div>- <div data-vinyl-hotkeys-ignore-left-allow="true"></div>

App Builder ignorará automáticamente los campos de texto y los divs marcados como contenido editable:

• <div contenteditable="true"></div>