Funciones de documentos y gráficos
Construir tablas en memoria, escribir en la salida de documentos dinámicos, generar URLs firmadas de archivos y montar gráficos y mapas por código.
Funciones del espacio F. para componer la salida de un documento: tablas en memoria, escritura en el flujo de salida, URLs firmadas de archivos, gráficos y mapas. Se usan sobre todo en documentos dinámicos; ninguna vale en fórmulas de algoritmo, y las convenciones comunes están en el índice de funciones.
Tablas en memoria
Tablas que construyes a mano cuando el resultado no sale directo de una sección: creas la tabla, añades filas y rellenas celdas tipadas (el tipo condiciona cómo se formatea y exporta el valor). Funcionan en scripts independientes y en documentos dinámicos; para recorrer registros que ya existen usa datos y listados.
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
DataTable_New | () | Entero | Crea una tabla en memoria y devuelve su identificador. |
DataTable_AddRow | (tabla) | Entero | Añade una fila y devuelve su índice. |
DataTable_SetValue | (tabla, columna, valor) | , | Escribe un valor en una celda. |
DataTable_SetValueText | (tabla, columna, valor) | , | Escribe texto escapando el HTML. |
DataTable_SetValueInt | (tabla, columna, valor) | , | Escribe un entero. |
DataTable_SetValueNum | (tabla, columna, valor) | , | Escribe un decimal. |
DataTable_SetValueMoney | (tabla, columna, valor) | , | Escribe un importe monetario. |
DataTable_SetValuePercentage | (tabla, columna, valor) | , | Escribe un porcentaje. |
DataTable_SetValueBool | (tabla, columna, valor) | , | Escribe un valor sí/no. |
DataTable_SetValueDate | (tabla, columna, valor) | , | Escribe una fecha y ajusta el formato de la columna. |
DataTable_SetValueDateTime | (tabla, columna, valor) | , | Escribe una fecha y hora. |
DataTable_SetValueTime | (tabla, columna, valor) | , | Escribe una hora. |
num tabla = F.DataTable_New()
F.DataTable_AddRow(tabla)
F.DataTable_SetValueText(tabla, "Cliente", "Ana López")
F.DataTable_SetValueMoney(tabla, "Importe", 1250.50)
txt html = F.DataTable_Build(tabla, "HTML")Columnas de la tabla
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
DataTable_ColumnSetFormat | (tabla, columna, formato) | , | Asigna el formato de una columna. |
DataTable_ColumnSetRole | (tabla, columna, rol) | , | Asigna el rol de campo de una columna. |
DataTable_ColumnDelete | (tabla, columna) | , | Elimina una columna. |
DataTable_ColumnDeleteIfIsEmpty | (tabla, columna) | , | Elimina la columna solo si está vacía. |
Volcar la tabla
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
DataTable_Build | (tabla, formato) | Texto | Devuelve la tabla como texto: JSONARRAY, JSON, HTML, CSV o XML. |
Build funciona en scripts independientes y documentos dinámicos. Para sacar datos a un archivo usa un informe y su exportación, y para meterlos, el importador de Pymes.
Escribir en el documento de salida
En documentos dinámicos y funciones API el resultado se construye escribiendo en un flujo de salida. Estas funciones solo ejecutan ahí.
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
Write | (contenido) | , | Escribe contenido en bruto en la salida. |
WriteText | (texto) | , | Escribe texto plano: conserva saltos de línea y no interpreta HTML. |
WriteBool | (valor, textoSí, textoNo) | , | Escribe un sí/no con el texto que elijas para cada estado. |
WriteDate | (fecha, formato) | , | Escribe una fecha con el formato indicado. |
WriteDateTime | (valor, formato) | , | Escribe una fecha y hora con el formato indicado. |
WriteMoney | (importe, máximoDecimales) | , | Escribe un importe como moneda con N decimales. |
WriteNum | (valor, máximoDecimales) | , | Escribe un número con N decimales. |
WritePercentage | (valor, máximoDecimales) | , | Escribe un porcentaje con N decimales. |
RemoveLastWrite | () | , | Elimina el último elemento escrito en la salida. |
F.Write("<h2>Resumen del pedido</h2>")
F.WriteText(v.observaciones)
F.Write("<p>Total: ")
F.WriteMoney(v.total, 2)
F.Write("</p>")Una tarjeta en lugar del documento
Cuando el documento no tiene nada que enseñar todavía, Notice cambia todo el documento por una tarjeta que explica qué pasa y qué hacer. Por ejemplo, pedir precio de un expediente que aún no tiene transportista. Lo escrito antes y después no sale. Con salir (o return) justo detrás, el documento se corta ahí.
La tarjeta se ve igual en la pantalla, en el PDF y en el correo. Lleva un color y un icono según el estilo, el texto, las piezas que añadas y el logo de Dinaup.
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
Notice | (texto) | , | Cambia el documento por una tarjeta con este texto. |
Notice_Title | (título) | , | Pone el título de la tarjeta, en negrita encima del texto. |
Notice_Style | (estilo) | , | Elige el color y el icono: tip (verde, el de por defecto), info (azul), warning (naranja) o error (rojo). |
Notice_Step | (texto) | , | Añade un paso numerado. Se llama una vez por paso, en orden. |
Notice_Video | (url) | , | Añade un vídeo de YouTube: su miniatura con el botón de reproducir, que abre el vídeo. |
Notice_Button | (texto, url) | , | Añade un botón, normalmente hacia donde se resuelve. |
Notice_Help | (texto, url) | , | Añade al final un enlace a un tutorial o a la ayuda. |
Las piezas son opcionales y se llaman después de Notice. Si no hay una tarjeta empezada, dan error.
if V.Expediente.Estado = 'Nuevo'
F.Notice('Todavía no se le ha asignado transportista, así que no hay a quién pedirle precio.')
F.Notice_Title('Este expediente aún está en «Nuevo»')
F.Notice_Step('Abre el expediente.')
F.Notice_Step('Elige el transportista en «Proveedor».')
F.Notice_Step('Vuelve a generar este documento.')
F.Notice_Video('https://youtu.be/…')
F.Notice_Button('Abrir el expediente', 'https://…')
F.Notice_Help('Cómo asignar un transportista', 'https://…')
return
endExplica, no riñas
La tarjeta la lee quien abre el documento. Cuéntale qué pasa y cuál es el siguiente paso, como un consejo: «Todavía no se le ha asignado transportista», mejor que «Error: estado no válido». Usa error solo cuando de verdad algo ha ido mal.
Plantillas y metadatos
Ejecutan en documentos dinámicos y funciones API (MetaData_Read también en scripts independientes).
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
Include | (id) | , | Incluye y renderiza una plantilla de impresión HTML por su identificador. |
GetDynamicDocumentContent | (id) | , | Inserta el contenido de un documento dinámico por su identificador. |
DataListInfoToHTML | (informeOSeccionId, estilo) | Texto | Devuelve como HTML la información de un informe o una sección. |
RowToJson | (seccionId) | Texto | Serializa un registro a JSON, sin los textos primarios de datos estáticos. |
MetaData_Read | (clave) | Texto | Lee un parámetro de metadatos por su clave. |
MetaData_Set | (clave, valor) | , | Asigna el valor de un parámetro de metadatos. |
URLs firmadas de archivos
Para mostrar un archivo de Dinaup (una imagen, un PDF) a quien no tiene sesión: generan una URL temporal de acceso público. Solo en documentos dinámicos y funciones API.
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
SignFileURL | (archivoId, tamaño, validezSegundos) | Texto | URL firmada del archivo, accesible sin sesión durante la validez indicada. |
SignFileURL_Advanced | (archivoId, tamaño, validezSegundos, nombre) | Texto | Igual, con nombre de archivo personalizado. |
El parámetro tamaño admite los valores 0, 32, 100, 300, 720 y 1080.
Cualquiera con la URL accede al archivo sin autenticarse mientras dure la validez. Ajusta los segundos al mínimo que necesites.
Gráficos
Montas el gráfico por código y lo vuelcas a HTML para incrustarlo en el documento. Cada serie y valor lleva dos colores: uno para el tema claro y otro para el oscuro. Los gráficos y los mapas funcionan en scripts de formulario, scripts independientes y documentos dinámicos.
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
Chart_New | (título) | Entero | Crea un gráfico y devuelve su identificador. |
Chart_AddSerie | (gráfico, etiqueta, colorClaro, colorOscuro) | , | Añade una serie de datos con sus colores. |
Chart_AddValue | (gráfico, etiqueta, valor, colorClaro, colorOscuro) | , | Añade un valor etiquetado con sus colores. |
Chart_ToHTML | (gráfico, tipo, ancho, alto) | Texto | Devuelve el gráfico como HTML con el tipo y tamaño indicados. |
num grafico = F.Chart_New("Ventas del trimestre")
F.Chart_AddValue(grafico, "Enero", 1200, "#2e86c1", "#5dade2")
F.Chart_AddValue(grafico, "Febrero", 1550, "#28b463", "#58d68d")
txt html = F.Chart_ToHTML(grafico, 1, 800, 400)
F.Write(html)Mapas
| Función | Parámetros | Devuelve | Qué hace |
|---|---|---|---|
Maps_New | (título) | Entero | Crea un mapa y devuelve su identificador. |
Maps_AddPoint | (mapa, título, icono, ubicación) | , | Añade un punto con etiqueta e icono en las coordenadas indicadas. |
Maps_AddClickablePoint | (mapa, título, icono, ubicación, secciónId, registroId) | , | Punto que al pulsarlo abre un registro de una sección. |
Maps_ToHTML | (mapa, coordenadasIniciales, zoomInicial) | , | Renderiza el mapa como HTML con el centro y zoom iniciales. |
→ Índice de funciones → Documentos dinámicos → Funciones de datos y listados