Referencia de Widgets de Portales

Esta página describe los widgets incluidos en el catálogo inicial. Los widgets core disponen de controles visuales y, cuando corresponde, de propiedades JSON avanzadas; los tipos nativos de las Vistas de usuario se configuran por completo mediante controles guiados.

Propiedades comunes

Propiedad	Tipo	Uso
title	string	Título opcional del widget.
hidden	booleano	Oculta el widget cuando se establece en true.
placement.x, placement.y	entero	Posición en la cuadrícula, comenzando desde 1.
placement.w, placement.h	entero	Ancho y alto en celdas.
style	objeto	Propiedades CSS, estados y puntos de ruptura de la instancia.
style.rawCss	string	Reglas CSS de ámbito avanzado.

En el Inspector, el campo Título y la propiedad JSON title están sincronizados en ambas direcciones. Una cadena introducida en uno de los dos se reflejará en el otro. Para eliminar el encabezado, elimine title del JSON o vacíe Título; el control guiado guarda el cambio automáticamente.

Los controles guiados se guardan automáticamente y muestran un toaster de confirmación. Para Propiedades JSON, Estilo JSON y CSS de ámbito use en su lugar Guardar cambios avanzados.

Sección (layout.section)

Agrupa contenido relacionado. title controla el encabezado visible. También es útil como estructura de destino para componentes personalizados.

Texto (content.text)

La propiedad text contiene el texto simple; los saltos de línea se conservan.

{"title": "Avviso", "text": "Intervento programmato\nDalle 18:00 alle 19:00"}

Para cambiar solo el contenido, use .portal-text en el CSS de ámbito.

Hero (content.hero)

Bloque de apertura con eyebrow, title, subtitle, imagen (assetPath) y botón opcional (buttonLabel, routeId). routeId solo acepta una ruta interna. Use un único Hero principal por página y complete imageAlt cuando hay imagen. Disposición de la imagen permite usarla como fondo o colocarla arriba, en el centro o abajo sin deformarla.

Tarjeta (content.card)

Combina title, text, imagen y enlace interno. En las cuadrículas use dimensiones uniformes; Disposición de la imagen permite usarla como fondo de la tarjeta o colocarla arriba, en el centro o abajo conservando sus proporciones.

Divisor (content.divider)

orientation puede ser horizontal o vertical; title es una etiqueta opcional. Un divisor vertical requiere una altura de cuadrícula adecuada.

Enlace (navigation.link)

• label: etiqueta del botón;
• routeId: identificador de una ruta interna declarada en portal.json.

El widget no abre URL externas.

{"label": "Apri ordini", "routeId": "orders"}

Menú (navigation.menu)

items es un array de {label, routeId} seleccionado de las rutas existentes. orientation puede ser horizontal o vertical; collapseOnMobile habilita el modo compacto en pantallas pequeñas.

Pestañas de navegación (navigation.tabs)

Muestra rutas relacionadas como pestañas. items conserva el orden, mientras stretch distribuye las pestañas en el ancho disponible. En móvil, las pestañas se deslizan horizontalmente.

Breadcrumb (navigation.breadcrumb)

items describe la ruta jerárquica; el último elemento puede no tener routeId. separator acepta un texto corto. El Breadcrumb no reemplaza el menú principal.

Imagen (media.image)

• assetPath: ruta de la imagen en el repositorio;
• alt: descripción alternativa accesible.

Cargue primero el archivo desde el Explorador y luego use la misma ruta:

{"title": "Marchio", "assetPath": "assets/logo.png", "alt": "Logo aziendale"}

Son cargables PNG, JPEG, GIF y WebP hasta el límite indicado por el editor. La altura placement.h dimensiona también la imagen, que usa todo el espacio disponible sin deformarse. Para cambiar el recorte, use, por ejemplo, .portal-image { object-fit: cover; } en el CSS de ámbito.

Módulo de solo lectura (form.readonly)

fields es un array de objetos con key, label y value:

{
  "title": "Ordine",
  "fields": [
    {"key": "number", "label": "Numero", "value": "SO-1001"},
    {"key": "status", "label": "Stato", "value": "Aperto"}
  ]
}

Panel colapsable (layout.collapsible)

title siempre visible, content contiene el texto y openByDefault elige el estado inicial. No ocultar en un panel cerrado errores o confirmaciones obligatorias.

Barra lateral (layout.sidebar)

Área lateral confinada en el widget. side es left o right; collapsible y collapsedByDefault gobiernan el control compacto. Para una navegación completa usar preferiblemente un Menú vertical.

Cajón (layout.drawer)

Panel superpuesto abierto desde buttonLabel. side elige el lado y closeOnScrim habilita el cierre al fondo. El runtime gestiona Escape y retorno del foco; no usar el Cajón para mensajes bloqueantes.

Tabla de datos (data.table)

• columns: lista ordenada de claves a mostrar;
• bindings.data.resourceKey: Recurso de datos declarado en la carpeta data.

{
  "props": {"title": "Ordini", "columns": ["number", "status"]},
  "bindings": {"data": {"resourceKey": "orders"}}
}

El Recurso de datos puede consultar objetos autorizados, fuentes de datos o Modelos Semánticos. El navegador no accede directamente a la fuente.

El comando Datos crea y modifica el recurso con selección visual de conexión, esquema, tabla, dimensiones, medidas y agregaciones, o de Modelo Semántico publicado, campos y medidas. Abrir JSON permite las configuraciones avanzadas después del primer guardado.

Formulario de datos (form.write)

Recopila campos tipados e inicia un Workflow autorizado. Definir campos abre un diálogo específico para clave, etiqueta, tipo, valor predeterminado, obligatoriedad, mínimo y máximo; se requiere al menos un campo y los límites solo se habilitan para números, fechas y fecha/hora. El Workflow es obligatorio y la lista solo muestra los Workflows ejecutables del Proyecto que reciben datos de entrada. Los valores predeterminados del Workflow y los valores fijos deben asociarse a un campo del formulario; en la Vista previa sustituyen su valor predeterminado y se muestran directamente en el campo deshabilitado, sin una línea de texto adicional. El Formulario de datos no requiere una Data Resource, por lo que esa sección no aparece en el Inspector; al editar una configuración anterior se elimina automáticamente cualquier binding de datos obsoleto.

El tipo Lista de valores usa las opciones configuradas en el Workflow y se muestra como un menú desplegable. No expone valor predeterminado, mínimo ni máximo, no admite un valor fijo y solo puede asociarse a un parámetro Workflow del mismo tipo. Las etiquetas y los valores permanecen separados y la opción elegida se valida antes de la ejecución.

Gráfico de barras (data.chart)

Muestra métricas calculadas en el servidor como barras horizontales accesibles. series indica la clave, etiqueta y color opcional de cada métrica; el binding debe referirse a un Recurso de datos agregado.

Subir archivo (form.upload)

El lector puede arrastrar un documento al área de carga o seleccionarlo desde su dispositivo. El widget actualiza el estado sin recargar la página y después muestra el nombre, el tamaño y la acción para eliminarlo. El botón Descargar solo está disponible cuando se habilita en el Inspector.

La configuración admite PDF, PNG, JPG/JPEG, DOCX, TXT, CSV y XLSX, un tamaño máximo de 1 a 256 MB y la opción Cifrar archivo en el servidor. Sybot comprueba el contenido real antes de guardarlo y rechaza ejecutables o scripts disfrazados y archivos que no coinciden con su extensión. Cada lector solo puede descargar o eliminar los archivos que ha cargado.

Exportación de datos (data.export)

Las casillas del Inspector permiten ofrecer CSV, XLSX o ambos; al menos un formato debe permanecer seleccionado. No es necesario habilitar un comando de exportación en el Recurso de datos: se admiten Conexiones, Modelos Semánticos y Working Datasets consultables. Se siguen comprobando el vínculo del widget, el acceso al Portal y los permisos sobre la fuente. El archivo generado es temporal y neutraliza valores potencialmente peligrosos para las hojas de cálculo.

Vista de usuario (user-view.embed)

• viewId: ID de la Vista de usuario;
• versionId: ID de la versión publicada a bloquear en el lanzamiento.

Ambos valores son obligatorios. En modo Visual la lista desplegable solo muestra las Vistas de usuario publicadas pertenecientes al Proyecto del Portal y rellena automáticamente ambos IDs. El pin de la versión evita que una modificación posterior de la Vista cambie un lanzamiento del Portal ya aprobado.

En Vista Previa y en el Portal publicado la Vista se muestra directamente en el widget, sin requerir un segundo acceso. Si la sesión o las autorizaciones ya no son válidas, el widget muestra un diagnóstico en lugar de la Vista.

En el Portal la cabecera extendida de la Vista no ocupa espacio: actualización, filtros y visualización se agrupan en una barra flotante solo con iconos.

Widget de Vista de usuario (user-view.widget)

Incorpora un único widget estándar o personalizado de una Vista publicada. La paleta y el Inspector solo muestran widgets de las Vistas accesibles en el Proyecto y registran viewId, versionId y widgetKey. También se soportan gráficos, KPI, tablas, mapas y widgets provenientes del catálogo personalizado de las Vistas.

El runtime carga solo la porción de la Vista y la fuente de datos necesarias para el widget seleccionado; no es posible cambiar widgetKey para acceder a una fuente diferente.

Tipos nativos compartidos con las Vistas de usuario

El Portal puede crear nuevas instancias de todos los tipos disponibles en el editor de Vistas de usuario. La paleta muestra el tipo, no las instancias ya configuradas en cada Vista. Las nuevas instancias pertenecen al Portal y utilizan las propiedades, la guía y el renderer compartidos.

Las familias disponibles incluyen gráficos, mapas, KPI, detalles de registros, contenido, diseños, controles de navegación y filtrado, acciones de Workflow, diagnóstico y Tabla de datos. Los tipos de datos requieren una Data Resource del Portal; los tipos que inician un Workflow requieren el binding correspondiente.

El Inspector agrupa las propiedades en secciones y ofrece controles visuales para columnas, widgets vinculados, umbrales, intervalos y mappings, por lo que no es necesario editar JSON. Las secciones mantienen su estado abierto o cerrado durante el autoguardado. Los tipos con el mismo nombre que un widget core del Portal permanecen separados: la entrada nativa de Vista de usuario no sustituye ni modifica la implementación core.

Acción de flujo de trabajo (workflow.action)

• workflowId: Flujo de trabajo asociado;
• buttonLabel: texto del botón;
• confirmationText: confirmación opcional;
• fields: parámetros recopilados antes del inicio;
• bindings.workflow.workflowId: debe coincidir con props.workflowId.

En modo Visual la lista desplegable solo muestra los Flujos de trabajo ejecutables del Proyecto del Portal. Para cada parámetro el Inspector genera una elección entre valor predeterminado (default), solicitud al usuario (prompt) y valor fijo (literal). Los parámetros sensibles no admiten valores fijos; los Flujos de trabajo con parámetros de archivo no son seleccionables.

En Vista Previa la acción ejecuta una prueba en seco (dry-run). En el Portal activo inicia el Flujo de trabajo solo si usuario, Portal y lanzamiento están autorizados.

Diagrama BPMN (bpmn.viewer)

• templateId: BPMN perteneciente al Proyecto;
• versionId: versión desplegada y fijada.

La lista completa ambos valores y solo muestra diagramas accesibles. La Vista previa y el runtime usan un visor de solo lectura y vuelven a validar los permisos del lector.

Reporte Power BI (bi.powerbi)

El widget admite Secure URL, con la sesión de Microsoft del lector, y App owns data, con un perfil y una vinculación gobernados por el Proyecto. Se rechazan las URL Publicar en web y los valores que contienen tokens o credenciales. Consulta Power BI: Secure URL y App owns data para ver la configuración completa de ambos modos.

Panel de control de Qlik (bi.qlik)

• embedMode: secure_url u oauth_impersonation;
• embedUrl: URL HTTPS de Qlik, solo para Secure URL;
• bindingKey: vinculación lógica del Proyecto, solo para OAuth impersonation;
• allowFullscreen: habilita pantalla completa.

El modo gobernado conserva App ID y tipo de contenido en la vinculación y usa un token breve generado por Sybot. Perfil y endpoint deben superar Diagnóstico y la release conserva la revisión de la vinculación. Consulte Integraciones gobernadas.

Sandbox de widget personalizado (custom.sandbox)

Un componente personalizado utiliza esta estructura:

components/my-widget/
├── component.json
├── template.html
├── styles.css
└── index.js

component.json declara archivos y capacidades:

{
  "schemaVersion": 1,
  "name": "My widget",
  "executionMode": "sandboxed",
  "template": "template.html",
  "styles": "styles.css",
  "entry": "index.js",
  "capabilities": ["data:query", "events:emit"]
}

JavaScript puede modificar el DOM interno de su iframe. Para datos y acciones use PortalWidgetSDK; las llamadas de red directas, el acceso al documento padre, las cookies y el almacenamiento de sesión no están permitidos.

El Inspector expone Abrir código del componente, que pasa automáticamente a Código y abre manifiesto, plantilla, CSS y JavaScript. El catálogo de Proyecto también puede copiar un componente de otro Portal; el componente se convierte en una copia versionable en el repositorio actual.

export async function mount(sdk) {
  const result = await sdk.query('orders', {status: 'open'});
  document.querySelector('[data-count]').textContent = result.rows.length;
}

Para las actualizaciones en directo, registre sdk.onDataInvalidated(listener) y repita la consulta cuando el evento incluya el recurso utilizado por el widget. Después de una mutación, llame a sdk.invalidateData(resourceKey). setContext() y getContext() gestionan el contexto compartido sin acceder al documento padre.

Active Autorizar al widget a iniciar Flujos de trabajo en el Inspector para gestionar la capacidad workflow:start sin editar JSON. Un widget personalizado no necesita bindings.workflow. Use sdk.runWorkflow(nombreOId, parámetros) o el alias sdk.startWorkflow() para iniciar cualquier Flujo de trabajo ejecutable del Proyecto actual; el ámbito del Proyecto y los permisos del usuario se siguen comprobando durante la ejecución.

Estilo, estados y puntos de ruptura

Las propiedades CSS usan nombres kebab-case. Las secciones states y breakpoints aplican variaciones locales:

{
  "background-color": "#ffffff",
  "padding": "1rem",
  "border-radius": "8px",
  "states": {
    "hover": {"box-shadow": "0 8px 24px rgba(15, 23, 42, .18)"}
  },
  "breakpoints": {
    "md": {"padding": "1.5rem"}
  }
}

Los estados admitidos son hover, focus, active y disabled; los puntos de ruptura son sm, md, lg y xl. Verifique siempre Escritorio, Tableta, Móvil y Vista previa.

Power BI: Secure URL y App owns data

El widget bi.powerbi ofrece dos modos:

• Secure URL usa un enlace reportEmbed y la sesión de Microsoft del lector. La página de inicio de sesión es normal cuando el lector aún no está autenticado.
• App owns data usa una vinculación de Power BI del Proyecto. Sybot obtiene un token temporal en el servidor; las credenciales y los tokens nunca se guardan en el widget.

Para App owns data, un Super Admin crea primero el secreto en la pestaña Credential Vault del Control Center. El propietario del Proyecto abre después Gestionar perfiles e informes en el Portal Editor y crea un perfil, una vinculación y al menos el endpoint Authoring. Los selectores cargan los espacios de trabajo e informes accesibles al perfil. Ejecuta Diagnóstico antes de la Vista previa.

Cada Proyecto puede usar varios perfiles, incluso para tenants o usuarios de Power BI diferentes, y elegir el perfil de cada endpoint. Están disponibles Microsoft public cloud, US Government GCC y Power BI China. El Vault admite ámbito de instalación o Proyecto, caducidad, rotación, desactivación y revocación definitiva. RLS se configura con una identidad de Sybot, un valor estático y roles; la configuración avanzada del SDK sigue siendo opcional.

Propiedad	Uso
embedMode	secure_url o app_owns_data.
embedUrl	URL reportEmbed, solo para Secure URL.
reportBindingKey	Vinculación lógica del Proyecto, solo para App owns data.
variantKey	Variante del endpoint, normalmente default.
pageName	Página inicial opcional.
showFilters	Muestra u oculta el panel de filtros.
showPageNavigation	Muestra u oculta la navegación de páginas.

Una vinculación puede resolver informes e identidades distintos para Authoring, Development, Staging, Production o un destino específico. Rotar un secreto del Vault no requiere cambiar el widget. El token de incorporación se renueva automáticamente antes de caducar.

Antes del despliegue, cada vinculación y variante App owns data de la release debe tener un endpoint diagnosticado para el destino o el fallback de su entorno. Si falta, el preflight bloquea el despliegue e indica la configuración que debe corregirse; Secure URL no requiere este control.