JSReports/WMD/es/notes.w.md

[[post_data {
    "author" : "KyMAN",
    "since" : 20220422,
    "version" : 20220422
}]]
# Notas

Notas para no olvidarme del proyecto.

El proyecto se basa en una librería ECMA/JS la cual se llama JSReports como nombre de clase. Hay que
crear un objecto JSReports para poder trabajar con ella. En el caso de PDF depende de las librerías:

- [https://cdn.k3y.pw/js/html2canvas.min.js]
- [https://cdn.k3y.pw/js/jspdf.umd.min.js]
- [https://cdn.k3y.pw/js/purify.min.js]

Para poder empezar a trabajar con esta librería hay que esperar asíncronamente a que termine de
cargar mediante un Callback "on_ready"

```js
(js_reports = new JSReports(/* PARAMETROS DE ENTRADA */)).on_ready(() => console.log("Ya terminó de cargar xD"));
```

> [[! note NOTA]]: La librería requiere de un sitio donde poner componentes de forma temporal a modo
de caché. No le vale un DocumentFragment. Si no se le establece se pondrá por defecto BODY.

# PDF y DOC

El trabajo con esta librería cara los PDF y DOC es exactamente igual. Hay que llamar a un método
llamado "create" el cual permite crear este tipo de documentos. La librería se centra en que crees
un HTML4 y CSS2, aunque pueden ser adjuntadas cosas de HTML5 y XHTML, así como algunos parámetros
CSS3 y customizados cara cualquier a de las dos plataformas. La idea es construir plantillas para
cabeceras, pies y cuerpos en HTML y una única hoja de estilos general en CSS, lo que cubriría el 99%
del informe, luego hay ciertos parámetros que son necesarios establecer mediante valores.

Con esta información tenemos como parámetros de entrada un único valor que vendrá siendo un
diccionario el cual tiene los siguientes elementos:

> [[! note NOTA]]: Todas las medidas se toma en mm (Milímetros).

- **header**: Cabecera HTML.
- **body**: Cuerpo HTML.
- **footer**: Pié HTML.
- **css**: Estilos CSS.
- **type**: Extensión que determina si es "doc" o "pdf".
- **margin**: Margen general para cualquier lado.
- **margin_top**: Margen superior.
- **margin_right**: Margen derecho.
- **margin_bottom**: Margen inferior.
- **margin_left**: Margen izquierdo.
- **variables**: Variables para cubrir dentro de los HTML.
- **header_height**: Alto de la cabecera.
- **footer_height**: Alto del pié.
- **margin_header**: Margen de la cabecera.
- **margin_footer**: Margen del pié.
- **dpi**: DPI para marcar tamaños digitales en PX.
- **page_format**: Formato de página (A4, A3, A5, C5, Letter (L), etc.); o tamaño (alto y ancho).

El formato PDF requiere de embedar las fuentes con las que se vaya a trabajar en formato TTF, que es
el formato por defecto cara los OS. Dicho formato requiere de un archivo por estilo (Regular o
normal, Light, Bold, Italic, etc). Para embedar fuentes es necesario cubrir la variable "fonts" en
el diccionario de parámetros de entrada del objeto y se compone de un Array bidimensional donde el
primer nivel es conjunto de fuentes y el segundo se compone de:

0. Nombre de la fuente.
0. Link del estilo.
0. Nombre del estilo.

En ambos casos, las imágenes se embedarán mediante URI Base64, pasando a formar parte del documento.
Las imágenes, por defecto, suelen estar protegidas por CORS. Para saltarse dicha restricción es
importante hacer uso de un Proxy. Para establecer el Proxy hemos de establecer el parámetro global
"proxy" que vendrá siendo una URL contra el Proxy donde la variable String "{url}" determinará donde
colocar la URL de la imagen.

```js
js_reports = new JSReports({
    proxy : "https://proxycors.local/api/DHkwPBhzp78Gz8g3BmG4VFnDgnt5kU9J6XQPjWMGDKwjr6s3f9nV7545B/{url}"
})
```

> [[! note NOTA]]: Si el Proxy no retorna las cabeceras del CORS, éste no servirá de nada. Se puede
hacer uso del proyecto [https://proxycors.k3y.pw/ ProxyCORS], proyecto en el que está basado el
ejemplo también desarrollado por KyMAN. El Git del proyecto es [https://git.k3y.pw/KyMAN/ProxyCORS].

> [[! important IMPORTANTE]]: El link del ProxyCORS posiblemente no funcione por el hecho de que con
dicho Hash podrían usar mi servidor como salto anónimo para saltarse el CORS entre otros fines por
lo que el Hash quede deshabilitado.

También se le pueden agregar componentes especiales al documento como tablas o listas programas
directamente como objetos o Arrays a partir de un objeto que determina su tipo y el contenido del
mismo. A continuación se titularán los tipos de objetos especiales que hay actualmente.

## Tablas (Grids)

Los documentos DOC y PDF permiten la generación de tablas dinámicas a partir de la idea de un Grid,
es decir, un objeto que determina la cabecera y los datos y automáticamente, el programa embedará
una tabla con dichos datos. La estructura del objeto es la siguiente:

- **type**: Tipo (puede ser "table" o "grid").
- **header** : Array de textos, cada uno será la cabecera de esa columna concreta.
- **body**: Cuerpo de la tabla o datos. Array bidimensional con los valores por cada tupla y columna.

Un ejemplo de una tabla puede ser el siguiente:

```js
const table = {
    type : "table",
    header : ["Cabecera 1", "Cabecera 2", "Cabecera 3", "...", "Cabecera N"],
    body : [
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"],
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"],
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"],
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"],
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"],
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"],
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"],
        ["Valor 1", "Valor 2", "Valor 3", "...", "Valor N"]
    ]
};
```

## Listas

Los documentos DOC y PDF permiten la generación de listas dinámicas a partir de un Array el cual
puede anidar otros Array para hacer Listas de múltiples niveles. Admiten tantos listas ordenadas
como desordenadas, y su estructura es la siguiente:

- **type**: Tipo (Siempre será "list"),
- **mode**: El modo en que se mostrarán los datos. Éste puede ser:
    - *ol* o *ordered*: Para mostrar los datos con un valor que representa su posición autoincremental.
    - *ul* o *unordered*: Para mostrar los datos con puntos, guiones o como se establezca por CSS.
- **start**: Para los elementos ordenados autoincrementalmente, valor numérico de inicio.
- **items**: Array de elementos ordenados. Puede contener objetos que anidan otras listas.

Un ejemplo de una tabla puede ser el siguiente:

```js
const list = {
    type : "list",
    mode : "ordered",
    start : 12,
    items : [
        "cosa 1",
        "cosa 2",
        "cosa 3",
        "...",
        ["jojo", {
            mode : "unordered",
            items : [
                "pasa A",
                ["pasa B", {
                    items : [
                        "otro xD"
                    ]
                }],
                "pasa C"
            ]
        }],
        "juas",
        "jiji"
    ]
};
```

[[html_data {
    "title" : "JSReports - Notas",
    "url" : "https://jsreports.k3y.pw/es/notes.html",
    "author" : "KyMAN",
    "since" : 20220422,
    "version" : 20220422,
    "key_words" : "jsreports,js,report,ecma,pdf,doc,csv,kyman,wmd,wmarkdown,documentación,notas",
    "description" : "Notas del proyecto JSReports.",
    "project" : "JSReports",
    "logo" : "https://jsreports.k3y.pw/images/JSReports.png",
    "language" : "es"
}]]