<!-- INICIO: Estilos -->
<link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">

<style>
body, h1, h2, h3, h4, h5, h6, p, ul, ol, li, code, pre, blockquote, span {
font-family: 'Roboto', sans-serif !important;
}

.nav>li {
padding-top: 6px;
padding-bottom: 6px;
line-height: 1.6;
margin-left: 0; /* Quitamos el corrimiento lateral */
}

.markdown-body ul {
padding-left: 1em; /* Espaciado limpio y coherente */
}

.markdown-body img {
border: 1px solid #e0e0e0;
border-radius: 6px;
padding: 8px;
margin: 24px 0;
background-color: #ffffff;
display: block;
max-width: 100%;
height: auto;
box-sizing: border-box;
margin-left: auto;
margin-right: auto;
}

.markdown-body li {
padding: 4px 0;
margin-left: 5px;
line-height: 1.4;
}

</style>
<!-- FIN: Estilos -->

# Configuración de Dashboard y Widgets

### Introducción:
Al ingresar a un dashboard, se pueden seleccionar **Filtros** y **Widgets**, además se tendrá disponible la **Barra de funciones**, que será utilizada para completar el diseño del Dashboard.
Se dispone de una funcionalidad denominada **Open Monitor** que permite visualizar en tiempo real los cambios que se realizan en el dashboard propiamente dicho.


Una vez seleccionado el **Widget** se accede a la configuración propia de cada uno, aunque inicialmente existe una sección en la que se ingresan los primeros datos del widget. Esta etapa de configuración se denomina "Wrapper del Widget" y se describe para cada widget en particular.

Finalizada esa etapa, se accede a la configuración visual del widget el **Widget Setup** que es la misma para todos los widgets y que se describe a continuación.

## Widget Setup

Esta sección, tambien se conoce como el "Wrapper del widget", es la que se encarga de hacer la conexión entre el widget y el dashboard.
Consta de 3 partes o más, de acuerdo al tipo de widget. Una de ellas es "Basic Options" que, además de especificar algnas configuración externas al widget, permite el acceso a la configuración de éste. La otra parte es la sección "Query" que permite la integración de los Data Sources, ya sea en queries simples o condicionales.
Tanto las subsecciones "Basic Options" y "Query" se describen a continuación.

### Basic options

En esta sección se indican los siguientes datos y opciones:

- **Title:** Es el nombre que se mostrará en la card del widget
- **Font Weight:** Se selecciona el peso de la tipografia (Normal, Medium o Bold), por defecto siempre será de tipo Normal aún sin ser seleccionado.
- **Refresh Group:** Es el grupo de refresco de la información que debe coincidir con la opción configurada en el [datasource](https://hackmd.io/@sitrackio/S1r8PbX2ll#Settings---Configuraci%C3%B3n-Data-Sources).
- **Icon selector** Este botón sirve para seleccionar un icono que identifique la card que se diseña.
- **Alarm**: Se puede agregar una condición que una vez cumplida se active una alarma.
- Query de ejemplo: ``` select new(true) as alert from '{}' as data ```
- Se comprende que ``` alert``` debe ser un valor 'true' para activar la alarma. **------ COLOCAR EJEMPLO-----**
- **Actions:** Define una acción **-----especificar su uso y colocar link a la sección-----**
- **Tooltip:** Se muestra un icono (i) que despliega la información que el diseñador desee.
- **Action Parameters:** **------no tengo info sobre esta opción-----**

Existen otras opciones disponibles que se habilitan a través de un switch:

- **Hide Title:** Sirve para ocultar el titulo del widget
- **Collapse Icons:** **------no tengo info sobre esta opción-----**
- **Use dynamic icon:** **------no tengo info sobre esta opción-----**

### Query

En esta sección, es necesario definir la fuente de datos que alimentará el widget. Esto puede hacerse de modos diferentes:

- Referenciar un **DataSource** preconfigurado. **----Colocar link a esta sección-----**
- Escribir directamente la query deseada ya sea una Query Simple o una Query Condicional, ésta última, requiere tener en cuenta el valor de una variable, que de acuerdo a su valor, ejecutará una determinada query.


En esta sección **Query**, se define el origen de datos que alimentará al widget Chart DX.
Los atributos a configurar son los siguientes:

- **Single query**: Permite escribir una consulta única que es la genera o brinda los datos con las columnas necesarias que se correspondan con los campos definidos en las series o guías.
- **Conditional queries**: Habilita la definición de consultas que responden a una condición, lo que implica a construcción de diferentes queries. Cada query condicional puede agregarse, seleccionando **+ Add query**. Es posibe, guardar cada query seleccionando el botón **Saved**, tambien se puede borrar la query deseada, con el botón **Delete**
- **Evaluate query as expression**: Este toggle indica si la consulta ingresada debe evaluarse como una expresión dinámica. Al activarse, se pueden insertar variables o expresiones para construir la consulta de forma programática. **----Consultar sobre una explicación mejorada----**
- **Graph (Beta)**: Permite visualizar gráficamente la estructura de la query para facilitar su interpretación. **----Consultar sobre una explicación mejorada----**
- **Edit documentation**: Permite agregar documentación técnica asociada a la consulta, para facilitar su mantenimiento y comprensión por otros usuarios o desarrolladores. **----Consultar sobre una explicación mejorada----**

<br/>
<br/>

## Barra de Funciones

La barra de funciones proporciona accesos directos a operaciones clave de gestión y personalización de los dashboards. Incluye acciones como Exportar e Importar Dashboards, Compartir, acceder a Ajustes de configuración, Editar el diseño del layout, Confirmar cambios realizados y Eliminar, entre otros. Esta disposición permite una interacción eficiente y centralizada con el sistema.


### Share (Compartir)

La función *Compartir Dashboards* permite a los usuarios distribuir visualizaciones interactivas con otros miembros del equipo, clientes o partes interesadas, de forma segura y eficiente. Esta herramienta facilita la colaboración en tiempo real, mejora la toma de decisiones basada en datos y promueve la transparencia en el análisis.

Al compartir un dashboard, el usuario puede definir niveles de acceso (visualización, edición, ejecución, entre otros), establecer permisos personalizados y garantizar que cada destinatario reciba la información adecuada según su rol.


Una vez que se elige la opción Compartir, se despliega un panel desde el cual se puede acceder al ícono correspondiente para indicar la persona con quien se desea compartir el dashboard.


Una vez que se selecciona el ícono indicado, se abre un panel —como se muestra en la figura— donde se visualiza una barra con un menú desplegable que permite elegir al usuario destino, así como definir las opciones de permisos que se le otorgarán sobre el dashboard.


Se mostrarán alternativas que otorgará diversos permisos sobre el dashboard, al usuario destino.

Al compartir un dashboard seleccionando los permisos deseados con la opción **With Inheritance**, lo que se está haciendo es otorgar una autorización al usuario destino de compartir el dashboard con esos mismos permisos.

En contrapartida, si se comparte un dashboard con ciertos permisos, seleccionando la opción **No Inheritance**, este usuario final no podrá compartir ese dashboard con alguien más.

### Exportar:

Al seleccionar la opción "Exportar", se despliega una ventana que permite definir si los widgets deben incluirse en el archivo exportado. Si se activa la opción "Include widgets", se generan nuevos widgets con identificadores únicos. En cambio, si no se incluye esta opción, se conservarán los identificadores originales del artefacto, lo que significa que cualquier modificación realizada sobre los widgets originales se verá reflejada en los widgets exportados.



Una vez seleccionado el botón **"Export"** se descargará, a la carpeta local, un archivo del tipo **dashboard_name.stkdb**

### Importar:

Esta función permite **Importar** un archivo previamente exportado para restaurar o reutilizar su contenido dentro de la plataforma. Por lo expresado, esta función permite importar un archivo de tipo dasboard_name.stkdb


Una vez seleccionada esta opción se muestra un panel de opciones de importación:

<div style="display:flex; gap:10px; align-items:center">
<img src="https://hackmd.io/_uploads/B1kIz_Uy-e.png" width="45%">
<img src="https://hackmd.io/_uploads/ryYiMOUyZg.png" width="45%">
</div>

El archivo se selecciona desde la opción correspondiente del menú, tras lo cual se debe elegir entre dos opciones disponibles:

* **Import with originals objects**: Importa el dashboard tal como se exportó originalmente. Es importante tener en cuenta que se copiarán los IDs del wrapper que corresponda.
* **Import by copying objects**: Copia el dashboard con nuevas claves en el diseño. Con esta configuración se generarán nuevos IDs para los wrappers.

### Export Data:

Esta función permite descargar el **Datasource**, del dashboard, en formato json. Este archivo puede ser utilizado posteriormente para crear automáticamente datasources basadas en JSON.
Al seleccionar esta opción se abre una ventana que informa que el archivo puede utilizarse más tarde para crear automáticamente fuentes de datos basadas en JSON.
El archivo que se descarga es del tipo **name_dashboard_data.json**


<br/>
<br/>

## Settings - Configuración (Data Sources)

Esta opción dentro del panel de configuración, entre otros aspectos importantes, permite crear y gestionar fuentes de datos que serán utilizadas por los distintos widgets según sea necesario. Proporciona una estructura estándar para definir cómo se obtendrá la información desde la base de datos. Esta sección asegura que los datos se consulten correctamente y se mantengan sincronizados con el comportamiento esperado de cada widget.


Una vez seleccionada la opción se muestra este panel que contiene los accesos a la configuración de Styles (Estilos), Filters Options (Opciones de Filtro) y el "Dashboard Context" que configura variables de contexto para el dashboard que se define.

### General
En esta sección se configuran los siguientes aspectos:

1. **Separately execution**: permite ejecutar requests desagrupadas para cada DS
2. **Remove widget data when query fails**: Cuando está deshabilitado, los widgets mostrarán datos de ejecuciones anteriores, si están disponibles (revisar si es así, **colocar ejemplo**)
3. **Blank widgets with error**: si se activa esta opción indica que uno o más widgets no están mostrando contenido porque se ha producido un error en su configuración o en la fuente de datos asociada.
4. **Enable Data Hashing**: Esta opción permite habilitar el procesamiento de datos mediante técnicas de hash, lo que mejora la seguridad y la integridad de la información almacenada o transmitida. Al activar esta función, los datos se codifican en un formato irreconocible, protegiéndolos contra accesos no autorizados y manipulaciones.
5. **Update Groups**: Especifica el tiempo en segundos para cada grupo de actualización. Si figura en 0 (cero) equivale a *deshabilitado*.


### Data Sources

En todos los widgets de un dashboard, la fuente de datos (Data Source) debe configurarse desde la pestaña **Data Sources** dentro de **Setting**, siguiendo una estructura común que permite definir cómo se obtendrá la información desde la base de datos. Esta sección garantiza que los datos se consulten correctamente y se sincronicen con el comportamiento esperado del widget.

Una vez seleccionada esta opción se muestra el botón **+ Add** que permite acceder a la configuración de los datasources.


El botón **+Add** tiene una opción de subir un DS desde un archivo. **----- COLOCAR UN EJEMPLO -----**

Una vez seleccionadla la opción del botón **Add**, se accede a la configuración propiamente dicha del DS. Por defecto, el nombre sugerido del DS es ds_0, aunque puede adecuarse a las necesidades según se desee.


Desde el desplegable **Group**, puede seleccionarse un grupo que permita actualizar los datos periódicamente si es requerido.
Si no se desea actualización periódica, puede dejarse sin seleccionar ("Do not update").


Se observa que hay un espacio en el que se especifica la query requerida.

En caso de ser necesario, se brinda la posibilidad de configurar **Queries Condicionales** que dada una cierta condición, estas queries se ejecutan.
Las queries pueden diseñarse y salvarse desde el **Query Runner** y ser utilizadas en este espacio seleccionando el botón **Saved**, que mostrará las queries salvadas.


Es posible agregar más queries condicionales, seleccionando el botón **+ Add query**

#### Ejemplo de una Query Condicional:

Una "conditional query" se agrega seleccionado el botón **+Add query** y está compuesta por:

1. **Condición (Condition)**
Se define mediante una expresión booleana que evalúa el estado de una o más variables.
Ejemplo: {id} != undefined
2. **Query asociada**
Se define una query que se ejecutará si se cumple la condición anterior.

### Funcionalidades adicionales:

- **Graph (Beta)**: permite visualizar una representación gráfica de la estructura de datos (requiere habilitación).


- **Edit documentation**: se ofrece un atajo para documentar el uso del data source directamente desde la interfaz.


- **Evaluate query as expression**: esta opción permite evaluar la query como una expresión dinámica, útil cuando se usan variables o filtros interactivos.


#### Add from File

La funcionalidad **Add from file** permite importar un Data Source previamente configurado desde un archivo de texto plano (`.txt`). Esta opción resulta útil para reutilizar configuraciones existentes o para compartir queries entre distintos dashboards o usuarios.

1. Hacer clic en el botón **Add** y seleccionar la opción **"Add from file"**.
2. Seleccionar un archivo `.txt` desde el explorador local.
3. La configuración del data source (nombre, grupo, tipo de query y contenido) se cargará automáticamente.


#### Acciones disponibles

Otras acciones disponibles en esta sección se detallan a continuación:

* **Guardar (`Save`)**: guarda la configuración del data source.
* **Aplicar (`Apply`)**: aplica la configuración actual sin cerrar el modal.
* **Cerrar (`Close`)**: cierra la ventana sin aplicar cambios.
* **Clear data source**: elimina la configuración del data source actual.
* **Agregar (`Add`)**: permite agregar múltiples data sources si el widget lo soporta.


#### Vincular un Data Source a un Widget

Una vez que el **Data Source** ha sido creado, se puede utilizar dentro de cualquier **Widget** simplemente llamando su nombre en el campo **Query** de la configuración del widget.

1. Ir a la configuración del widget correspondiente.
2. En la sección **Query**, escribir el nombre del data source precedido por el símbolo `$` o también se puede hacer una consulta sobre el data source.
Ejemplo:

$ds_state o select * from ds_state


### Styles

En esta sección, se accede a configurar un Estilo al dashboard, estos pueden ser de 3 tipos:

1. **Classic**: es el diseño por defecto que brinda la plataforma
2. **Compact**: es un diseño más compacto para el dashboard
3. **Custom**: brinda la posibilidad de diseñar el estilo del dashboard de manera personalizada, especificando:
a. **Font size**: Medium, Small, Large
b. **Widgets gap**: permite establecer un gap Medium, Large, Minimal Separation o No gap.
c. **Margin in widget**: con 3 opciones Medium, No margin y Large
d. **Round corners**: este toggle, si se activa, permite redondear las esquinas del widget.
e. **Use extended layout**: determina si se utilizará el diseño de cuadrícula extendido. Esta opción permite habilitar un diseño de cuadrícula más amplio, con mayor cantidad de columnas y flexibilidad en la posición de los elementos. Por defecto, esta opción siempre está habilitada.
f. **Prevent collision**: hace que los elementos se comporten de forma más independiente al bloquear superposiciones, en lugar de provocar cambios en el diseño. Por defecto, esta opción siempre está habilitada.


### Filters Options

Esta es una sección complementaria a los Filters **colocar referencia** que brinda la posibilidad de configurar otros aspectos de éstos.

* **Label Position**: permite establecer la posición del boton de filtro, ya sea **LEFT** o **TOP**
* **Show Reset**: permite habilitar un botón para resetear los filtros diseñados.
* **Show filters dropdown**: si ses activa este toggle se despliega otro menú para especificar la posición ya sea *Superior Right* o *Superior Left*
* **Quote parsing**: *Procesamiento de comillas*, esta función permite interpretar correctamente las comillas dentro de cadenas de texto, asegurando que se analicen y estructuren adecuadamente durante el procesamiento de datos o la ejecución de comandos. **---VERIFICAR---**


### Dashboard Context

Son constantes locales que existen en el dashboard para consumir sin necesidad de consultar recursos. Hay unas básicas que vienen en todos los dash que son _accountId, _timeZoneCode y _dashboardId. Se pueden configurar unas propias también de momento solo de tipo String

**----VERIFICAR CON MICA----**

### Otras funciones

En la barra de funciones existen otras funciones que colaboran en el diseño y ejecución de un dashboard.


1. Icono de Guardar: guarda el dashboard
2. Icono de Discard: desecha los cambios realizados
3. Icono de Tilde: acepta o confirma los cambios realizados
4. Icono de Trash: elimina el dashboard
5. Icono de flecha: refresca el dashboard, si se han realizado cambios
6. Icono de pausa: pausa la ejecución de las queries de los datasources
7. Icono de pantalla completa: muestra a pantalla completa todo el dashboard diseñado
8. Icono de ancla: esta opción sirve para dejar "anclada" la barra de funciones.

### Layout

Esta función se aplica cuando el dashboard está en modo edición, permitiendo reorganizar los widgets insertados de forma flexible. El sistema ofrece varios tamaños de pantalla que facilitan el diseño adaptativo de la solución, según el tipo de dispositivo que utilizará el usuario.


Los tamaños disponibles son:

| Tamaño | Descripción | Ancho en píxeles |
|--------------|---------------------------|----------------------------|
| XS | Extra pequeño | 501 px |
| SM | Pequeño | 889 px |
| MD | Mediano | 1117 px |
| LG | Grande | 1321 px |
| XL | Extra grande | 2404 px |


**-------HASTA AQUI LLEGUE-----**

## Public Files

Al cargar un archivo en la plataforma, ya sea por medio de un dashboard o desde el Navigator, este se guardará en el recurso File. Este archivo tendrá varios atributos, aunque en este caso, la atención se centrará en el id y la url.
Si se intenta acceder al archivo cargado por medio de la url se mostrará un un mensaje de error ya que esta pertenece a un bucket privado. Es por esto que se utilizará el recurso Public File.
El Public File, genera una url pública con límite de tiempo para acceder a ese archivo. Para ello mediante una consulta se pasa el id del archivo y en caso de querer asignarle una duración específica se envía ese dato (que por defecto es de 1 minuto)
Query sin duración definida:

select *
from PublicFile
where id = b53231c3-70ae-4caa-9794-c3301292b4f0

Query con duración definida:

select *
from PublicFile
where id = b53231c3-70ae-4caa-9794-c3301292b4f0
and duration = 5

Nota: El número que se informa se interpreta en minutos. Por lo tanto, al colocar 5, se define una duración de 5 minutos.

Si se desea utilizar este recurso para un widget de imagen o video, se siguen los pasos detallados anteriormente pero al momento de configurar el Data Source, se deberá obtener el id de la imagen en la plataforma con el query:
select *
from File
where completeName like ‘(parte del nombre o nombre exacto del archivo)’

O

select *
from File
where completeName = ‘(nombre exacto de nuestro archivo)’

Una vez obtenido el id del archivo se ejecuta la query del PublicFile indicando el id y el resultado obtenido se inserta en el Data Source. En este caso no es necesario indicar una duración ya que cada vez que se abra el dashboard, se obtendrá una nueva url e inmediatamente quedará la imagen/video descargada/o y guardada/o en el browser dejando de necesitar que esté activo el link para acceder de manera pública.
El Data Source quedaría, por ejemplo, de esta manera:

En este caso particular, se asignó un “alias” al atributo url para que coincidiera con la configuración en el widget, pero esto no es necesario si se coloca “url” en la configuración del widget.

Finalmente este sería el resultado de los widgets utilizando PublicFile:

A continuación se deja un video de muestra sobre la creación de los widgets tanto con urls públicas de internet como con archivos de la plataforma por medio de PublicFile.
https://www.youtube.com/watch?v=kmyOVncEa4k

<br/>
<br/>

## Dashboard Context
Esta funcionalidad se encuentra dentro de los Dashboard y brinda la posibilidad de generar constantes locales de tipo String que existen únicamente dentro los mismos para consumirlas desde Widgets o Datasources sin necesidad de hacer consultas/subconsultas a los recursos de la plataforma.
Existen constantes iniciales que poseen todos los dashboards desde su creación, las mismas no pueden ser modificadas o eliminadas. Estas son:
* _accountId: Devuelve el ID de la cuenta desde la que se está trabajando.
* _timeZoneCode: Devuelve el huso horario que tiene configurado la cuenta desde la que se está trabajando.
* _dashboardId: Devuelve el ID del dashboard sobre el cual se está trabajando.

Las constantes existentes dentro de un dashboard pueden verse en la opción "Show context variables" dentro de la barra de herramientas del modo edición.

Apps - Dashboard - Dashboard Context_Existentes.
 *(Es un video pero no sabía como ponerlo como GIF)*

## Creación de una constante
Con el dashboard en modo edición debemos entrar en "Setting" desde la barra de herramientas y una vez abierto el menú de configuración se debe seleccionar la sección "Dashboard Context". En esta sección se visualizaran las constantes iniciales y aquellas que se hayan creado manualmente, a estas últimas se las podrá editar desde esta misma sección.

Apps - Dashboard - Dashboard Context_Config 1.png

Para crear una nueva constante debemos presionar el botón "Add variable" que se encuentra debajo de la lista de constantes.

Apps - Dashboard - Dashboard Context_Add variable.png

Al presionarlo se mostrarán 3 campos, uno indicando el tipo de la constante que es por el momento solo String, otro para indicar el nombre que tendra la misma y por último el campo donde se colocará el valor para la constante.

Apps - Dashboard - Dashboard Context_Config 2.png

Una vez completados todos los campos solamente se debe presionar el botón "Save" y quedará creada la nueva constante.
Se podrán eliminar las constantes creadas presionando la cruz que se encontrará a la derecha de cada una.