Editor y widgets de Portales

El Editor de Portales combina un repositorio de archivos navegable con un compositor visual. Ambos modos operan sobre el mismo borrador: las modificaciones visuales actualizan las fuentes y las partes gestionadas directamente en el código se conservan.

Al iniciarse, el Editor abre la primera página disponible en modo Visual. Si el Portal no contiene páginas, abre portal.json en modo Código.

La interfaz del Editor sigue inmediatamente el tema claro u oscuro elegido en Sybot. La barra de herramientas, los paneles, el Inspector y los diálogos cambian de paleta sin recargar la página; el lienzo y los widgets del Portal conservan el tema y los estilos definidos para el contenido publicado.

Los selectores Código y Visual se encuentran entre el nombre del Portal y el estado de guardado. Guía de widgets precede a Exportar en la barra de acciones. En pantallas estrechas, la fila permanece única: las etiquetas desaparecen progresivamente de derecha a izquierda, dejando los iconos con información emergente y nombres accesibles. La ayuda para arrastrar y redimensionar sigue visible en la barra del Canvas sin el resumen anterior de atajos de teclado.

En el lado izquierdo, la barra de actividades abre alternativamente Añadir Widget, Páginas, Imágenes, Explorador, Diagnóstico y Problemas y Propiedades del Portal. El icono de propiedades se encuentra al final de la barra. Solo se muestra un panel a la vez; al volver a seleccionar el icono activo, se cierra. En modo Visual, el Inspector permanece fijo a la derecha. Durante la sesión, el Editor recuerda el panel abierto y el ancho elegido para la columna izquierda.

Añadir Widget muestra inicialmente las categorías con el número de elementos y un chevron. Seleccione una categoría para desplegar sus tarjetas; Business Intelligence contiene por separado Informe Power BI y Panel Qlik. Buscar widget filtra nombres, categorías y claves técnicas en tiempo real y abre automáticamente los grupos con resultados.

El panel Páginas mantiene Añadir página en la parte superior y muestra todas las páginas del Portal. La página activa queda resaltada; los nombres largos se truncan sin romper el diseño y el nombre completo permanece disponible al pasar el ratón. Seleccionar una página la abre directamente en el Canvas. Cambiar a Widgets, Explorador o Problemas no cambia la página actual. Añadir página solicita un nombre, crea y guarda de forma asíncrona el documento inicial bajo pages/ y lo abre en el Canvas.

El panel Imágenes reúne el enlace al catálogo compartido, la carga desde el ordenador y las imágenes ya presentes en el Portal. Cada imagen muestra una vista previa y el nombre del archivo y se puede eliminar previa confirmación; la cuadrícula se actualiza sin recargar el Editor.

En el Canvas, cada widget se representa mediante una tarjeta compacta que muestra su icono, nombre, tipo, tamaño en la cuadrícula y visibilidad en ordenador, tableta y smartphone. La tarjeta conserva los colores, el fondo y la tipografía configurados, mientras que los textos largos se abrevian sin cubrir los controles de arrastre y cambio de tamaño. Use Vista previa para comprobar el contenido y el comportamiento completos del widget.

Duplicar widget crea una instancia independiente en la misma página o en otra. Para un widget personalizado, también copia todos los archivos del componente y los cambios en las fuentes sin guardar, con una nueva clave de componente. Se conservan la configuración, los enlaces, el estilo y las asociaciones externas; editar o eliminar la copia no afecta al original. La copia sigue siendo local, mantiene el modo sandboxed/trusted y no hereda el enlace a la versión firmada del catálogo; compartirla requiere guardarla explícitamente en el catálogo. El componente y la página se guardan juntos: si ocurre un error, se revierte la duplicación. Las instancias existentes que comparten un componente siguen compartiéndolo.

Cada copia local puede guardarse en el catálogo como un paquete distinto desde v1, en cualquier orden. El botón desaparece solo para el componente ya vinculado; sigue disponible para las copias sin vincular. Si los nombres coinciden, el servidor añade un sufijo y actualiza el nombre y el manifiesto en el editor, conservando los archivos auxiliares. El catálogo de widgets personalizados muestra únicamente los paquetes guardados explícitamente en el catálogo. Los componentes locales y las copias aún sin guardar nunca generan tarjetas en el catálogo; siguen disponibles en el Canvas y el Explorador.

Para eliminar un widget, seleccionar Eliminar widget en el Inspector, o pulsar Supr o Retroceso fuera de un campo. Tras confirmar, solo se elimina la instancia seleccionada de esa página. Mientras otras instancias hagan referencia al componente, incluso en otras páginas, sus fuentes y la asociación al catálogo no cambian. Eliminar la última instancia de un componente guardado en el catálogo borra sus fuentes locales y desvincula el paquete de forma atómica: el widget permanece entre los Objetos no utilizados, listo para volver a insertarlo. La acción explícita del Explorador elimina todo el componente y todas las referencias en las páginas.

Modo Código

El modo Código muestra:

• Explorador, para buscar, crear, renombrar y organizar archivos;
• Cargar imagen, para añadir al repositorio activos PNG, JPEG, GIF o WebP;
• pestañas para los archivos abiertos;
• editor con resaltado para JSON, HTML, CSS y JavaScript;
• estado de guardado y número de revisión actual;
• panel Problemas con errores e indicaciones corregibles.

En el Explorador, el chevrón situado junto a cada directorio permite expandir o contraer solo esa rama. El estado de los directorios se mantiene durante la sesión de edición, mientras que una búsqueda expande temporalmente las ramas necesarias para mostrar las coincidencias.

Los cambios se guardan de forma asíncrona. Si el borrador ha sido actualizado por otra sesión, el editor detiene el guardado e indica el conflicto: recargar la versión actual antes de reanudar el trabajo.

Al cerrar o abandonar el Editor, la sesión de modificación se libera inmediatamente. Otro usuario puede editar el mismo Portal sin esperar a que caduque automáticamente la sesión anterior.

Usar Punto de control para fijar una revisión inmutable y reconocible del borrador. Un punto de control no publica el Portal.

Al abrir un archivo que no representa una página — por ejemplo portal.json, una Data Resource, un CSS o un archivo de componente — el editor cambia automáticamente a Código. El compositor Visual permanece asociado solo a las páginas y nunca muestra el lienzo de un archivo abierto previamente. El modo elegido para cada página se recuerda durante la sesión de edición: si una página estaba abierta en modo Visual, vuelve automáticamente a Visual después de consultar un archivo de configuración.

Para crear una página, seleccionar Nuevo archivo y usar una ruta JSON bajo pages/, por ejemplo pages/dashboard.json o pages/orders/detail.json. El nombre del archivo es libre: el editor genera automáticamente UUID, título, diseño en rejilla y lista de widgets. El Editor añade automáticamente la ruta en portal.json y la entrada de navegación en shell.json. Al eliminar la página se quitan ambas asociaciones sin recargar la interfaz.

Modo Visual

El modo Visual pone a disposición paletas, lienzo e Inspector. Al seleccionar un widget siempre se abre Propiedades, y su configuración se organiza en tres pestañas:

• Propiedades contiene título, datos, fuentes, bindings y opciones funcionales;
• Estilo contiene controles visuales, Style JSON y CSS scoped;
• Avanzado contiene posición, ancho, alto y Propiedades JSON.

Cambiar de pestaña no deselecciona el widget ni pierde los valores actuales, incluso durante el guardado asíncrono. Las mismas pestañas están disponibles para widgets estándar y personalizados, Vistas de Usuario, BPMN, Power BI y Qlik. También se puede navegar con las flechas izquierda/derecha, Inicio y Fin.

Las propiedades guiadas se aplican y guardan cuando el control cambia; un toaster confirma el resultado. Guardar cambios avanzados sirve en su lugar para los recuadros JSON y CSS, donde es normal tener contenido temporalmente no válido durante la escritura. El estado en el encabezado distingue modificaciones en curso, guardando y fuente guardada.

Los campos del Inspector dependen del widget: rutas, imágenes, Vistas de Usuario, widgets individuales de una Vista, Flujo de trabajo, parámetros y Data Resource se eligen de menús filtrados por el Proyecto. Los selectores de ruta muestran solo las páginas de la navegación activa del Portal y se actualizan sin abrir manualmente los archivos fuente. Los colores se pueden elegir con el selector o insertar como valor CSS o token de diseño.

Los presets Viewport declaran el tamaño simulado. La barra de zoom ofrece −, +, restablecimiento al 100 % y Ajustar. Ajustar usa tanto el ancho como el alto disponibles, reduce uniformemente el lienzo y mantiene las proporciones de la Vista previa. Un clic en el porcentaje restablece el 100 %; un doble clic permite introducir un valor del 5 % al 200 %. Con un zoom personalizado, las barras de desplazamiento permiten explorar las zonas que no caben en el área de trabajo. El zoom solo modifica la visualización del editor, no la geometría guardada ni el renderizado en ejecución. Cada widget muestra también su indicador ancho × alto en celdas de la rejilla.

Para modificar la geometría de un widget:

• arrastrar el asa superior izquierda para moverlo;
• arrastrar el asa inferior derecha para cambiar su tamaño;
• usar Alt + flecha para moverlo una celda;
• usar Mayús + Alt + flecha para modificar su ancho o alto de una celda.

Para eliminar un widget, seleccionarlo y usar Eliminar widget en el Inspector. Alternativamente, pulsar Supr o Retroceso cuando el cursor no esté en un campo. El editor siempre pide confirmación.

Cuando una región contiene propiedades no gestionadas por el compositor, el editor la identifica como gestionada por el código y la conserva durante las actualizaciones visuales.

Para configurar la página en lugar de un widget, hacer clic en un área libre del fondo del lienzo. El Inspector Estilo de la página permite establecer color, fondo, espaciado interno y altura mínima; Estilo JSON y CSS scoped de la página siguen disponibles para ajustes avanzados.

Propiedades del Portal se abre en la columna izquierda y deja el Inspector derecho disponible para el widget seleccionado. La pestaña General contiene el nombre, el código trusted y los controles Mostrar Header y Mostrar Navegación. Estos dos controles de la Shell se guardan inmediatamente y la Vista previa refleja el título y la barra de navegación. Para los Owners, Acceso contiene colaboradores, permisos y audiencia runtime. El cambio de pestaña conserva los valores no guardados; la carga, el guardado y los diagnósticos siguen siendo asíncronos sin recargar el Editor.

Configurar aspecto y CSS

El Estilo guiado expone color, fondo, tamaño de texto, alineación, espaciado y radio de borde. Los valores aceptan sintaxis CSS normal, por ejemplo #0f172a, 1rem o 8px.

La Configuración avanzada permite usar propiedades CSS en kebab-case, estados y puntos de ruptura:

{
  "color": "#0f172a",
  "background-color": "#ffffff",
  "padding": "1rem",
  "states": {
    "hover": {"background-color": "#e0f2fe"}
  },
  "breakpoints": {
    "md": {"font-size": "18px"}
  }
}

El campo CSS scoped permite intervenir en cualquier detalle sin influir en los demás widgets. & representa el contenedor de la instancia; .portal-text selecciona el contenido del widget Texto:

&:hover { transform: translateY(-2px); }
.portal-text { font-weight: 600; letter-spacing: .02em; }

Seleccionar Guardar cambios avanzados para registrar JSON y CSS en la página. La Vista previa muestra el resultado compilado definitivo.

Catálogos del Proyecto

Los botones Widget personalizado e Imágenes abren un catálogo unificado. Cada elemento siempre muestra su procedencia: Portal actual, otro Portal del mismo Proyecto, Vista de Usuario publicada o catálogo compartido de Vistas. No se muestran objetos externos al Proyecto o no accesibles al usuario.

En Widget personalizado, el selector junto a la búsqueda alterna las vistas Tarjetas y Tabla. La tabla admite ordenación, selección múltiple y páginas de diez registros. El menú de cada widget permite insertar la versión elegida, exportar su JSON, abrir una vista previa estática segura o eliminarlo; la confirmación muestra los Portales que lo utilizan. Importar widget carga un JSON exportado desde otro Proyecto. Cada guardado crea una nueva versión incremental sin sobrescribir las existentes.

La paleta incluye también los widgets de las Vistas de Usuario publicadas del Proyecto. Es posible incorporar tanto widgets estándar — incluidos gráficos, KPI, tablas y mapas — como widgets del catálogo personalizado. La selección registra Vista, versión publicada y clave del widget; una versión permanece estable incluso si la Vista se modifica posteriormente.

Cuando se utiliza una imagen o un componente proveniente de otro objeto, el editor crea una copia en el repositorio del Portal. Esta materialización hace que los puntos de control, las compilaciones y las versiones sean reproducibles; la tarjeta del catálogo conserva la indicación del origen para evitar ambigüedades.

Widgets disponibles

El catálogo gestionado comprende:

• Texto, Hero, Card, Imagen y Divisor;
• Enlace, Menú, Pestañas de navegación y Breadcrumb;
• Sección, Panel colapsable, Barra lateral y Cajón (Drawer);
• Formulario de solo lectura, Formulario de datos, Tabla de datos, Gráfico de barras y Exportación de datos;
• Vista de Usuario completa y widget único de Vista de Usuario;
• Acción de Flujo de trabajo (Workflow);
• Reportes Power BI y Dashboards Qlik;
• Widget personalizado sandbox.

Cada widget soporta propiedades de estilo, estados visuales y puntos de ruptura. El CSS scoped permite personalizar incluso el estado de pasar el ratón (hover), el foco, el estado activo y el estado deshabilitado sin modificar los demás componentes de la página.

El botón Guía de widget abre la referencia integrada del widget seleccionado: enumera propiedades, tipos, valores predeterminados, capacidades y ejemplos de estilo. La referencia completa también está disponible en Reference dei widget.

Cargar y usar una imagen

1. Si el archivo es local, usar Cargar imagen en el Explorador y elegir un PNG, JPEG, GIF o WebP.
2. Para reutilizar un activo, abrir Imágenes y filtrar el catálogo por nombre o procedencia.
3. Seleccionar Usar imagen o Copiar y usar: el editor propone una ruta bajo assets/ y rellena el widget seleccionado.
4. Completar siempre alt, luego elegir adaptación (contain, cover, fill, none, scale-down) y posición.
5. Verificar el resultado en Vista previa.

La altura establecida para el widget en la cuadrícula determina también el espacio ocupado por la imagen. Por defecto, la imagen se contiene sin deformaciones; el CSS scoped puede modificarlo object-fit mediante el selector .portal-image.

Data Manager y consultas visuales

Datos abre el Data Manager del Portal. No es necesario conocer de antemano la estructura de la carpeta data/:

1. Crear un Recurso de Datos y asignar clave y nombre;
2. Elegir Entorno de Conexión o Modelo Semántico;
3. Para Entorno, cargar el catálogo, y luego elegir esquema, tabla, dimensiones, medidas, agregaciones y alias;
4. Para un Modelo Semántico, elegir la versión publicada del Proyecto, y luego campos y medidas gobernadas;
5. Configurar filas máximas, tiempo de espera y parámetros solo cuando sea necesario;
6. Guardar: el archivo data/<chiave>.resource.json se crea y se asocia al widget seleccionado.

El modo SQL personalizado avanzado está reservado para consultas de solo lectura que no son expresables por el configurador. También requiere la declaración de las columnas de salida. Los joins, filtros u ordenamientos complejos se pueden refinar abriendo el JSON generado en modo Código.

El navegador no recibe las credenciales ni consulta directamente la fuente. Las consultas, parámetros, límites y autorizaciones se vuelven a comprobar en tiempo de ejecución.

Datos e integraciones de Sybot

Los recursos de datos pueden usar fuentes y Modelos Semánticos autorizados. Las consultas son de solo lectura y respetan nuevamente los permisos del usuario en el momento de la ejecución.

En el widget Formulario de datos es obligatorio un Flujo de Trabajo del Proyecto. Cada parámetro puede usar un campo del formulario, el valor predeterminado del Flujo de Trabajo o un valor fijo no sensible. Los campos Lista de valores deshabilitan el valor predeterminado, el mínimo y el máximo y solo pueden asociarse a parámetros del mismo tipo. El editor importa las etiquetas y los valores del Flujo de Trabajo y muestra un menú desplegable en el Portal. Para estos parámetros no hay valores fijos: la opción elegida se valida y se pasa directamente al Flujo de Trabajo.

En el widget Vista de Usuario, elegir de un desplegable una vista publicada del Proyecto del Portal. La selección registra automáticamente tanto la vista como la versión publicada anclada.

En el widget Acción de Flujo de Trabajo, elegir un Flujo de Trabajo ejecutable del Proyecto. Para cada parámetro, indicar si usar el valor predeterminado, solicitar el valor al usuario o guardar un valor fijo. Los parámetros sensibles solo pueden solicitarse en tiempo de ejecución; los Flujos de Trabajo con parámetros de archivo, no son seleccionables. En la Vista Previa solo se realiza la verificación de la configuración.

Escribir un widget personalizado

Al añadir Widget personalizado sandbox, el editor crea una carpeta explícita:

components/<chiave>/
├── component.json
├── template.html
├── styles.css
└── index.js

Abrir código componente pasa a Código y abre los cuatro archivos. template.html contiene el marcado, styles.css el estilo aislado, index.js exporta mount(sdk) y component.json declara archivos y capacidades. El código puede modificar el DOM de su iframe, reaccionar a eventos y usar PortalWidgetSDK para datos, navegación interna y Flujos de Trabajo autorizados. No puede acceder al documento padre, a la sesión, a otros widgets, a cookies o a red directa.

En template.html, styles.css e index.js, el editor ofrece autocompletado contextual durante la escritura; también puede abrirse con Ctrl+Espacio o Cmd+Espacio. Después de sdk., solo se muestran los métodos permitidos por las capacidades del component.json actual. El margen señala errores de sintaxis JavaScript, identificadores no definidos, etiquetas HTML no equilibradas y propiedades CSS no válidas sin interrumpir el guardado automático.

Guía de widgets → Widget sandbox personalizado → SDK Sandbox documenta la firma, los parámetros, el valor devuelto, la capacidad necesaria y un ejemplo de cada método, incluidos query, emit, navigate, las operaciones de Workflow, invalidateData, setContext, getContext y onDataInvalidated.

Después de una mutación, sdk.invalidateData() notifica las Data Resources modificadas. Las Tablas y Gráficos vinculados se actualizan en segundo plano sin recargar la página, mientras que sdk.onDataInvalidated() permite al Custom Widget repetir su consulta. sdk.setContext() actualiza el contexto compartido y notifica a todos los consumidores; sdk.getContext() devuelve una copia local.

Las Data Resources basadas en un Modelo Semántico también se actualizan cuando una mutación se origina en un recurso directo con una clave diferente.

Para habilitar la ejecución, seleccione el widget y active Autorizar al widget a iniciar Flujos de trabajo en el Inspector. El editor actualiza el manifiesto automáticamente: no se necesita un binding en la página ni editar JSON. sdk.runWorkflow(nombreOId, parámetros) y sdk.startWorkflow(nombreOId, parámetros) pueden invocar un Flujo de trabajo ejecutable del Proyecto actual; los permisos se vuelven a comprobar durante la ejecución.

Las solicitudes de datos simultáneas de distintos widgets permanecen independientes y tienen un tiempo máximo. Si el código del widget no gestiona un error durante el inicio, el Portal finaliza igualmente la carga y muestra un mensaje dentro del widget.

Power BI y Qlik

Reporte Power BI admite Secure URL con la sesión Microsoft del lector y App owns data con un perfil y una vinculación gobernados por el Proyecto. Panel Qlik admite Secure URL y OAuth impersonation con qlik-embed. En ambos casos, los secretos permanecen en la configuración administrativa y el widget solo guarda una URL o vinculación lógica. Ejecute Diagnóstico antes de la Vista previa y pruebe permisos, licencia y políticas del proveedor en el dominio publicado.

Consulte Integraciones gobernadas para el procedimiento completo.

Validar y probar el borrador

1. Guardar el archivo o aplicar las propiedades desde el compositor.
2. Seleccionar Validar.
3. Corregir los elementos listados en el panel Problemas.
4. Seleccionar Compilar para verificar la construcción del borrador.
5. Seleccionar Vista Previa y probar el diseño, los datos y las interacciones.

La Vista Previa está separada de la versión publicada. Los errores muestran un mensaje utilizable y, cuando está disponible, un identificador para comunicarlo a soporte.

Para accesos y ciclo de publicación, consultar Pubblicazione e accessi.