Widgets

Descripción General

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

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

Pautas para el Uso de Widgets

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

   • Bueno: valor mostrado

     
     

   • Bueno: Valor evidente

     
     

   • Malo:

     

2. Prueba de widgets. Recuerde tener en cuenta cómo interactuará el widget en dispositivos táctiles y no táctiles.

3. Los widgets deben respetar la edición y el guardado automáticos. Los widgets obtendrán este comportamiento de App Builder automáticamente.

Contenido del Archivo de Archivo

_manifest.json

Todos los widgets incluyen un archivo de manifiesto. Puede 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 App Builder IDE y también se convierte 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 a continuación para obtener más información.

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

• targetContainer: Admite el valor true o false.

• purpose: Admite el valor definido de Site o Field, que indica cómo se pretende utilizar 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 en la que se publicó esta versión. Solo con fines informativos.

• dependencias: lista delimitada por comas de todas 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 tienes dependencias, incluye las propiedades de JavaScript y CSS con una matriz vacía.

  Manifest Entry

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

binder.js

binder.js

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

El enlazador proporciona dos devoluciones de llamadas necesarias para enlazar el App Builder API para sus bibliotecas. En cada una de ellas se proporcionan dos parámetros de función.

• holderElement: Un elemento DOM que contiene el marcado HTML proporcionado en el archivo de modelo especificado. Como 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 de widgets. Este objeto contiene todas las dependencias de JavaScript especificadas en el enlazador, así como el acceso a los datos en 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 ningún contenido y la devolución de llamada de instalación definida en el enlazador deberá representar 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.

Célula de API de widget
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 para detectar 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 se puede utilizar para 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) es "25%". O bien, un control de lista podría tener un valor de GUID, mientras que el valor formateado es el nombre y apellido de un cliente.

persistedValue - string
Esta propiedad se puede utilizar para obtener el valor persistente subyacente de la celda. Un valor persistente es el valor no editado almacenado actualmente en la fuente de datos. Esto se puede utilizar para revertir una celda a un estado limpio.

setDataChangeCallback
Esta función se utiliza para establecer devoluciones de llamadas que se ejecutarán cuando el formulario en el que se encuentra el widget obtenga datos nuevos.

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

setChangeCallback(name: string, value: Function)
Esta función se utiliza para establecer devoluciones de llamadas en una celda. Se pueden definir las siguientes devoluciones de llamadas con nombre:

• value
• formattedValue
• disabled

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

App Builder puede provocar cambios en la celda durante eventos de validación, si se establecen valores predeterminados o si otro widget provoca cambios que afecten a esta celda. App Builder también puede deshabilitar celdas cuando se ejecutan eventos.

App Builder pasará un único parámetro a la devolución de llamada proporcionada que contiene el valor modificado. En el caso de que 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 está implementando 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.

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

Parámetros
Los parámetros de un widget se pueden definir en el nivel del panel. Al agregar 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 en consecuencia:

  • Control:
    • Control de destino: un control del panel principal que proporcionará este valor de parámetro.
    • Usar valor formateado: use el valor de visualización formateado.
    • Activo: indica si este enlace está activo o no. No se utilizarán los enlaces inactivos.
  • 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. No se utilizarán los enlaces inactivos.
  • Valor estático:
    • Valor: valor estático para el parámetro.
    • Traducible: si está habilitado, permite traducir el widget cuando corresponda.
    • Activo: indica si este enlace está activo o no. No se utilizarán los enlaces inactivos.

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

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

Mostrar 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.

Obtener y configurar el valor de App Builder en tu widget
App Builder puede actualizar el valor a través de valores predeterminados o cambios en los registros principales. Su biblioteca deberá poder actualizarse a sí misma cuando ocurran estos eventos.

Proporcionar devoluciones de llamadas permite App Builder para ejecutar el código cuando necesite enviar nuevos valores a su widget. Consulte setChangeCallback más arriba.

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

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

1. Comprima el contenido de la carpeta local en la que está trabajando (asegúrese de no comprimir la carpeta principal en sí, esto creará una carpeta adicional en el archivo zip)
2. Cargue el archivo zip del widget en la aplicación Look & Feel
3. Presione actualizar en la página que usa su widget. Nota: es posible que deba deshabilitar la memoria caché de su navegador mientras desarrolla, de lo contrario podría terminar con código obsoleto.

Estado de vista vs. Estado de edición
Al agregar un widget a un panel, puede especificar si su widget manejará la representación tanto del estado de edición como del de vista. Si su widget solo maneja el estado de edición, App Builder representará el valor de la celda cuando esté en 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 hacer esto, debe cambiar la fila al estado de edición si aún no lo está. A continuación, se incluye un ejemplo:

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

También puede 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.

Carga de dependencias grandes
Los recursos grandes como JQuery UI tardan mucho tiempo en descargarse e instalarse. Por cuestiones de rendimiento, se recomienda que solo se utilicen bibliotecas ligeras o bibliotecas que utilicen dependencias existentes. App Builder se han implementado dependencias. Se han informado algunos errores cuando las dependencias se cargan demasiado lentamente.

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

row.ViewModel
La versión actual de App Builder expone un parámetro llamado ViewModel en la fila API. Esto proporciona acceso a la App Builder datos de back-end y no se garantizará que funcionen al actualizar App Builder no se recomienda escribir código que dependa de esta propiedad.

Widgets del sitio

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

Los widgets del sitio se ejecutan tan pronto como se carga el navegador. Esto permite que el código se ejecute lo antes posible. El código se ejecutará de forma asincrónica, lo que significa que la página no esperará a que se ejecute el código para renderizarse.

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

Cómo agregar un widget del 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. Proporcione un Nombre para el widget. Por ejemplo: Widget de marcado
5. Haga clic en Explorar y busque 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 la proporciona 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 de 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 devoluciones de llamadas que se ejecutan cuando cambia la ubicación de la página. Devolverá la ruta como una cadena.

onAuthenticationChange(handler: Function(event))
Esta función se utiliza para configurar devoluciones de llamadas que se ejecutan cuando el usuario autenticado cambia. Devolverá 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 desactivar la compatibilidad con teclas de acceso rápido 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, agréguelas al sufijo de clase CSS. Si hay más de una palabra, sepárelas con guiones en el sufijo de 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>