Referencia de Widgets de Portales

Esta página describe los widgets incluidos en el catálogo inicial. Las propiedades se modifican en el Inspector como un objeto JSON; el título, la geometría y el estilo común también disponen de controles visuales.

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.

Tarjeta (content.card)

Combina title, text, imagen y enlace interno. En las cuadrículas use dimensiones uniformes; .portal-card__media permite ajustar la relación de aspecto y object-fit.

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 y los guarda en un Working Dataset asociado. El binding debe permitir añadir registros; la validación se repite en el servidor y el navegador nunca accede directamente al almacén. Tras un guardado correcto, las tablas y gráficos vinculados se actualizan sin recargar la página.

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.

Exportación de datos (data.export)

Ofrece CSV y XLSX solo cuando el Recurso de datos autoriza la exportación. El archivo generado es temporal, respeta los permisos del lector 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.

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;
}

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.