Widgets¶

Descripción General¶

Los Widgets en Vinyl permiten a los desarrolladores proporcionar código de terceros (o propio) para mostrar un control personalizado en la página. Los widgets le permiten definir más metadatos; consulte la sección Contenido del archivo archivado 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 puedes usar en Vinyl.

Pautas para los Widgets¶

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

   • Bueno: valor mostrado

     
     

   • Bueno: Valor obvio

     
     

   • Malo:

     

2. Prueba de widgets. Recuerde considerar cómo se 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. Los widgets obtendrán este comportamiento de Vinyl automáticamente.

Archivar Contenido del Archivo¶

_manifest.json¶

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

{
    "name": "Slider", 
    "developer": "Vinyl",
    "binder": "binder.js", 
    "template": "view.html",
    ...
    "targetContainer": false,
    "purpose": "Site",
    "parameters": [
        {
            "nombre": "Nombre del parámetro",
            "predeterminado": "valor predeterminado",
            "traducir": verdadero
        }
  ] 
}

• name: El nombre del widget que aparecerá en Vinyl IDE y que también se convertirá en el nombre del archivo comprimido.

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

• binder: El nombre de archivo de la carpeta de widgets. Vea abajo para más información.

• template: El nombre de archivo del archivo HTML de modelo. Vea abajo para más información.

• targetContainer: Soporta el valor true o false.

• purpose: Soporta el valor definido de Site o Field, que indica cómo se pretende utilizar el widget.

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

  • name: el nombre del parámetro
  • default: una cadena que contiene el valor predeterminado
  • translate: soporta 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 que se lanzó esta versión. Sólo con fines informativos.

• dependencias: lista delimitada por comas de las dependencias requeridas por su carpeta de widgets. El orden en que aparecerán 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 su API de 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) {}
            }
        }
    };
});

La carpeta proporciona dos devoluciones de llamada necesarias para vincular la API de Vinyl a sus bibliotecas. En cada uno, 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 titular puede estar vacío. El elemento titular es la celda que desplegará el widget. Es el área resaltada en la captura de pantalla siguiente y no incluye la etiqueta del campo.
  

  

• context: Una instancia del contexto de la API de widgets. Este objeto contiene las dependencias de JavaScript especificadas en la carpeta, 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 la carpeta deberá representar el HTML necesario.

API de widgets¶

getCell()
Devuelve una instancia de WidgetApiCell.

getRow()
Devuelve una instancia de WidgetApiRow.

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

getParameter(nombre) - cadena
Recuperará el parámetro definido del valor predeterminado o de la celda de esta fila 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 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;
});

Valor formateado - cadena
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 mostrado (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.

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

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

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

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

• valor
• valor formateado
• desactivado

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

Vinyl puede provocar cambios en la celda durante los eventos de validación, si se establecen valores predeterminados o si otro widget provoca cambios que afectan esta celda. Vinyl también puede desactivar las celdas cuando se ejecutan eventos.

Vinyl pasará un único parámetro a la devolución de llamada proporcionada que contiene el valor modificado. En el caso de deshabilitado, el valor es verdadero o falso.

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

WidgetApiRow
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 los valores modificados nuevamente 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 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 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: use el valor de visualización formateado.
    • Activo: Indica si este enlace está activo o no. No se utilizarán enlaces inactivos.
  • Valor estático:
    • Valor: Valor estático del 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 enlaces inactivos.

Cómo crear un widget y solucionar problemas¶

Los widgets son una pizarra en blanco. Vinyl ejecutará el código del widget en lugar de la despliegue de Vinyl.

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

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

Obtener y configurar el valor de Vinyl en tu widget
Vinyl puede actualizar el valor mediante valores predeterminados o cambios en los registros principales. Su biblioteca deberá poder actualizarse cuando ocurran estos eventos.

Proporcionar devoluciones de llamada permite a Vinyl ejecutar su código cuando necesita enviar nuevos valores a su widget. Consulte setChangeCallback arriba.

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

Carga de nuevas versiones y depuración
Una vez que tengas un widget operativo y estés depurando un error, sigue los siguientes pasos:

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

Ver vs. Editar estado
Al agregar un widget a un panel, puede especificar si su widget manejará la representación tanto del estado de edición como de visualización. Si su widget solo maneja el estado de edición, Vinyl representará el valor de la celda cuando esté en el estado de visualización.

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á. Aquí hay un ejemplo:

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

También puede usar la propiedad isEditState para representar una versión de "solo lectura" del widget que muestra el valor pero que no se puede usar para modificar la celda.

Cargando dependencias grandes
Los recursos grandes como JQuery UI tardan mucho en descargarse e instalarse. Por motivos de rendimiento, se recomienda desplegar solo bibliotecas ligeras o bibliotecas que utilicen dependencias de Vinyl existentes. Se han informado algunos errores cuando las dependencias se cargan demasiado lentamente.

Trabajar con datos binarios
Algunas celdas de Vinyl pueden 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 la colección Vinyl para ver un código de ejemplo.

fila.ViewModel
La versión actual de Vinyl expone un parámetro llamado ViewModel en la fila API. Esto proporciona acceso a los datos back-end de Vinyl y no se garantiza que funcione al actualizar Vinyl. 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 usa 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 asíncrona, lo que significa que la página no esperará para 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 Vinyl¶

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 marcación
5. Haga clic en Examinar y busque el archivo .zip del widget que contiene todos los archivos de widgets necesarios, selecciónelo y haga clic en Abrir.
6. Proporcione cualquier Documentación para describir el widget. La información del 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 control y establezca los valores de 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 llamada que se ejecutan cuando cambia la ubicación de la página. Devolverá la ruta como una cadena.

onAuthenticationChange(controlador: Función(evento))
Esta función se utiliza para configurar devoluciones de llamada que se ejecutan cuando cambia el usuario autenticado. Devolverá el nombre de usuario como una cadena.

Solución de problemas¶

El Vinyl admite atajos de teclado, con el que algunas bibliotecas de widgets pueden entrar en conflicto. Vinyl 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 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 teclado, 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>

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

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