🎓 ¿Cómo crear diseños personalizados con Fuentes de datos?

Consideraciones

Este documento está diseñado para poder realizar paso a paso la implementación de Fuentes de datos consumidas por la plataforma web de tekus.

Nuestra aplicación de señalización digital es una solución que integra diferentes tecnologías, una de ellas es realizar consultas a fuentes XML en la red, permitiendo mostrar campos dinámicos de manera automática sin necesidad de cambiar los diseños personalizados.

Otra forma de hacer consultas de información por medio de la aplicación es instalando un Cliente de Datos (Suministrado por Tekus S.A.S.) en un servidor que esté ubicado en la misma Red en la que se encuentra el Player o Dispositivo con nuestra aplicación (o que sea visible por éste). Así, el player podrá recibir información que tenga guardada de manera local, ya sea en formato Excel( .xlsx, .xls), texto plano (.txt, .csv) o bases de datos que soporten conexiones por drivers ODBC.

La evaluación de contenidos se realiza sobre fuentes XML que puedan ser consultadas desde el Player, para esto te sugerimos abrir un navegador en el player y validar que la URL del recurso XML sea accesible.

1. Sintaxis de sentencias para consulta de datos dinámicos a través de una fuente XML

1.1. Estructura de sentencia

La evaluación sobre una fuente de datos XML se debe realizar utilizando sentencias que tengan la siguiente estructura.

( ruta . nodo1 . subnodo1 ) . Funcion

La primer parte de la sentencia es una expresión que describe la ruta del nodo de interés. La segunda parte es una función que indica qué dato tomar del nodo consultado.

1.1.1 Funciones disponibles

Funciones disponibles

Actualmente se soporten 3 funciones para extración de información. Si no se provee una función se tomará la función text() por defecto

text() = obtiene el texto del contenido del nodo indicado.
attr("nombre_atributo") = obtiene el valor del atributo en el nodo indicado.
price() = Provee funciones de transformación sobre números para desplegar la información con un formato de precios.

1.2. Ruta completa en editor de diseño personalizado.

Cuando estés realizando la edición de los datos dentro del disseño personalizado debes tener presente que hay que incluir la expresión del nodo entre llaves {{ }}, de esta manera vas a garantizar que solo se evalúen las expresiones deseadas.

Puedes ingresar varias sentencias en un mismo campo:

{{( ruta . nodo1 . subnodo1 ) . Funccion }}

Si deseas referenciar más de una fuente de datos puedes especificar de la siguiente manera:

{{dataSourceId, ( ruta . nodo1 . subnodo1 ) . Funccion }}

Dónde dataSourceId corresponde al identificador de la fuente que se creó en el diseño personalizado.

Expande para ver algunos ejemplos… 🕵🏻

Ejemplos

XML

<?xml version="1.0" encoding="utf-8"?>
<data xmlns="https://www.arkbox.co/xml/data-client-2.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <item id="2" index="2">
        <field name="ID">2</field>
        <field name="DESC">Lavadora LG</field>
        <field name="PRICE">2.228.900</field>
    </item>
    <item id="3" index="3">
        <field name="ID">3</field>
        <field name="DESC">Prueba3</field>
        <field name="PRICE">2000</field>
    </item>
    <item id="4" index="4">
        <field name="ID">4</field>
        <field name="DESC">Prueba4</field>
        <field name="PRICE">1000</field>
    </item>
    <item.var id="4" index="4">
        <field name="ID">4</field>
        <field name="DESC">Prueba4</field>
        <field name="PRICE">1000</field>
    </item.var>

    <item:var id="4" index="4">
        <field name="ID">4</field>
        <field name="DESC">Prueba4</field>
        <field name="PRICE">1000</field>
    </item:var>
</data>

- Ejemplo de Consulta nodo a nodo (obteniendo el contenido):

Expresión	Expresión alternativa	Resultado	Descripción
`(data.item.field).text()`	`(data.item.field)`	2	Debes tomar el nodo data, el primer nodo item, el primer nodo field y tomar la propiedad text del nodo.
`(data.item[1].field[1]).text()`	`(data.item[1].field[1])`	3	Debes tomar el nodo data, el segundo nodo item (index = 1), el segundo nodo field (index = 1) y tomar la propiedad Text del nodo.

- Ejemplo de Consulta en nodo interno (obteniendo el contenido):

Cuando hay nodos comunes o que agrupan otros nodos, puedes realizar una omisión de dicho nodo en la ruta.

Para este ejemplo omitimos el nodo data.

Expresión	Resultado	Descripción
`(item.field).text()`	2	Debes tomar el primer nodo item (index = 0), el primer nodo field y tomar la propiedad Text del nodo.
`(item[0].field[0]).text()`	2	Debes tomar el primer nodo item (index = 0), el primer nodo field (index = 0) y tomar la propiedad Text del nodo.
`(field[8]).text()`	1000	Debes tomar el noveno nodo field (index = 8), y tomar la propiedad Text del nodo.

- Ejemplo de Consulta por atributo (obteniendo el contenido):

Este tipo de consultas sólo aplica para contenidos XML

Expresión	Resultado	Descripción
`(item['id=4'].field[0]).text()`	4	Debes tomar el nodo item (donde el atributo id sea igual a 4), el primer nodo field (index = 0) y tomar la propiedad Text del nodo.

- Ejemplo de Consulta en nodo interno (obteniendo un atributo):

Expresión	Resultado	Descripción
`(item.field).attr('name')`	ID	Debes tomar el primer nodo item (index = 0), el primer nodo field y tomar el atributo name del nodo.
`(item[0].field[0]).attr('name')`	ID	Debes tomar el primer nodo item (index = 0), el primer nodo field (index = 0) y tomar el atributo name del nodo.

1.3. Generalidades

● El sistema de rutas de nodos se basa en un sistema DOT (Enrutamiento por nodos separados por puntos)

● Si no defines el índice se asumirá el primer elemento encontrado (Index = 0)

● Afecta MAYUS y MINUS

● Si no indicas una función se tomará 'text()' por defecto

1.4. Variantes

● En el caso de que el nombre de un nodo contenga un punto como parte del caracter debes indicar el nodo entre comillas simples:

('item.var'[0])

● En algunos casos en los que los nodos contienen el caracter dos puntos : puedes indicar el nodo de manera natural sin las comillas:

(item:var.field[1]).text();

1.5 URL's Dinámicas y variables locales del player

En ocasiones es necesario parametrizar las consultas de tal forma que el contenido de la misma dependa del player o dispositivo. Para esto, hemos habilitado unas variables locales que son resueltas por cada dispositivo según sus propias características.

A continuación te mostramos una lista de las variables locales soportadas por un player:

Nombre	Descripción	Ejemplo
serial	Identificador único del player	123456
platform	Indica el sistema operativo o el sistema base de la plataforma	ios, android, windows, linux
model	Modelo del player	MK808, IPHONE8
manufacturer	Marca de quien fabrica el player	samsung, apple, rockchip
name	Nombre del dispositivo (Que tiene nuestra app instalada)	Player 12
width	Indica el ancho de la pantalla	1920
height	Indica el alto de la pantalla	1080
time_h	La hora, usando un reloj de 12 horas de 1 a 12.	Data la fecha 2009-06-15T01:45:30 el valor sería 1
time_hh	La hora, usando un reloj de 12 horas de 01 a 12.	Data la fecha 2009-06-15T01:45:30 el valor sería 01
time_H	La hora, usando un reloj de 24 horas de 0 a 23.	Data la fecha 2009-06-15T5:45:30 el valor sería 5
time_HH	La hora, usando un reloj de 24 horas de 00 a 23.	Data la fecha 2009-06-15T15:45:30 el valor sería 15
time_m	Minutos, de 0 a 59.	Data la fecha 2009-06-15T15:05:30 el valor sería 5
time_mm	Minutos, de 00 a 59.	Data la fecha 2009-06-15T15:45:30 el valor sería 45
date_d	El día del mes, de 1 a 31.	Dada la fecha 2009-06-01T13:45:30 el valor sería 1
date_dd	El día del mes, de 01 a 31.	Dada la fecha 2009-06-01T13:45:30 el valor sería 01
date_M	El mes, de 1 a 12	Dada la fecha 2009-06-01T13:45:30 el valor sería 6
date_MM	El mes, de 01 a 12	Dada la fecha 2009-06-01T13:45:30 el valor sería 06
date_yyyy	El año en 4 dígitos	Dada la fecha 2009-06-01T13:45:30 el valor sería 2009
time_tt	El designador AM/PM.	Dada la fecha 2009-06-01T13:45:30 el valor sería PM
ip	Indica la IP actual (IPv4)	192.168.0.50
time_s	segundos, de 0 a 59.	Data la fecha 2009-06-15T15:05:08 el valor sería 8
time_ss	segundos, de 00 a 59.	Data la fecha 2009-06-15T15:45:30 el valor sería 30

Todas las variables se indican en minúscula. Las variables pueden ser referenciadas en cualquier campo de texto, propiedad de texto y en URL's incluyendo la URL que se indica en la fuente de datos.

Las variables se expresan contenidos entre "::" (dos puntos doble), de la siguiente forma:

::nombre_variable::

Expande si deseas ver algunos ejemplos…

Ejemplos

Ejemplo 1:
Para indicar el serial se utilizaría la siguiente expresión:
::serial::
Ejemplo 2:
Si se deseas usar una variable local en una función puedes insertar la variable dentro de la misma:
{{(ruta.nodo1.nodo2['ID=::serial::']).text()}}
Ejemplo 3:
También puedes insertar en la URL de la fuente de datos algo como lo siguiente:
http://192.168.20.50:8181/data/50/?ID=::serial::
Ejemplo 4:
Si se deseas indicar la fecha en formato HH:mm yyyy/MM/dd
::time_HH:::::time_mm:: ::date_yyyy::/::date_MM::/::date_dd::
El resultado será 09:00 2021/11/16
Ejemplo 5:
Si se deseas indicar la fecha en formato yyyy-MM-dd hh:mm tt
::date_yyyy::-::date_MM::-::date_dd:: ::time_hh:::::time_mm:: ::time_tt::
El resultado será 2021/11/16 09:00 AM

2. Definición de las URL de las fuentes de datos ejemplo RSS.

2.1. Como primera medida debes poseer la URL de consulta de donde se van a obtener la fuente RSS, en este ejemplo utilizaremos la url de la página de El tiempo que previamente buscamos en google.

La plataforma web de tekus es compatible con formato XML y formato JSON, por ende, las fuentes que vayas a agregar deben estar en alguno de estos formatos.

2.2. Ahora que tienes la url de consulta debes acceder a tu cuenta en la plataforma web de tekus e ingresar el editor de tu diseño personalizado.

2.3. En la sección inferior Fuente de datos debes hacer clic en Crear.

2.4. Una vez se abra la ventana para agregar la Fuente de datos, debes definirle Nombre, Período de comprobación, Formato, Codificación y finalmente la Url de consulta > y finalizar haciendo clic en Guardar.

Nombre: Nombre nemotécnico, por lo general se le da un nombre alusivo a la fuente de datos que vas a consultar.
Comprobación: Cada cuanto tiempo consultará la url en busca de información nueva.
Formato: El formato que soporta la plataforma web de tekus es XML.
Codificación: El formato de codificación de caracteres es el UTF-8.
Url de consulta: Corresponde a la url de donde vamos a consultar los datos, Url completa con esquema (Https | Http).

2.5. Una vez creada tu fuente de datos deberás ver algo así:

El ID es un valor único que identifica la fuente datos. Es útil en los casos en los que se tiene más de una fuente de datos creada.

3. Agregar Sintaxis XML a la fuente de datos.

3.1. Una vez agregada la fuente puedes incluir la sintaxis XML a tu diseño personalizado. Para esto, debes asgregar controles de texto por cada dato que desees traer de la fuente de datos.

3.2. Posteriormente debes agregar el contenido respectivo en cada recuadro de texto. Para esto, debes seleccionar uno a uno los recuadros de texto y editar su contenido en el menú derecho Propiedades.

Por ejemplo:
Al momento de crear nuestra fuente de datos se le asignó el ID 66, por eso el contenido del texto debe llevar el mismo ID {{66.(item[0].field[1])}}

Recuerda que el primer número que aparece en la sintaxis hace referencia al ID de la fuente de datos creada. Esto se usa en caso de que exista más de una fuente asociada a una mismo diseño personalizado.