Technical documentation

Primeros pasos

La librería de componentes del Sistema de Diseño DINTEL es una librería de Web Components.

Los Web Components no son una tecnología única, sino que se constituyen en base a una serie de estándares para navegadores definidos por el consorcio W3C que permiten crear etiquetas propias de forma nativa, dotándolos de su propio marcado, funcionalidad y/o estilo utilizando HTML, CSS y JavaScript.

Las APIs nativas de navegadores y Web Components estandarizados, facilitan la implementación y el uso de los componentes DINTEL en cualquier framework o en ninguno.

Implementación sin framework

Integrar los componentes en un proyecto sin framework JavaScript es muy sencillo. Si estamos trabajando en una página HTML simple, podemos empezar a utilizar los componentes inmediatamente añadiendo estas etiquetas a las cabeceras del documento HTML, en la etiqueta <head>.

De esta forma, consumimos la librería de componentes DINTEL descargando los componentes en tiempo de ejecución de un servidor de estáticos.

// incluimos la librería de componentes

// incluimos los estilos generales de la librería <link rel="stylesheet" href="https://estaticos.redsara.es/dintel/latest/dnt-ui/dnt-ui.css"></link>

En este ejemplo se muestra la manera de consumir la librería de DINTEL descargando los componentes en tiempo de ejecución.

Además, podemos precargar la librería con técnicas de preloading como rel="modulepreload y rel="preload", indicando al navegador que precargue los archivos JavaScript antes de que sean necesarios. Esto puede reducir el tiempo de carga y garantizar que los módulos estén disponibles de inmediato cuando se necesiten, así beneficiamos el rendimiento de la página y SEO.

Debes evaluar cuidadosamente el impacto en el rendimiento general y asegurarte de que solo se precarguen los recursos necesarios para evitar penalizaciones y mantener una experiencia de usuario óptima.

Implementación con framework

La librería del Sistema de Diseño DINTEL se encuentra alojada en un repositorio privado de Nexus, por lo que es necesario tener credenciales para poder descargarla.

Integración desde Nexus

Antes de seguir adelante, asegúrate de que tienes Node.js instalado en tu máquina. Puedes instalar la última versión a través de su página web. Si estás planeando utilizar la librería de componentes DINTEL en un proyecto que aún no utiliza Node Package Manager, tendrás que crear primero un archivo package.json. Para ello, ejecuta el comando npm init desde la consola y sigue los pasos que se indican

El primer paso es solicitar unas credenciales de acceso. Es obligatorio solicitar una credencial por cada módulo o proyecto a la Oficina Técnica de la AEAD.

Una vez obtenidas las credenciales, se han de utilizar para logarse en npm, a través de la consola de tu máquina personal. Para ello, desde la consola, ejecuta los siguientes comandos:

npm set registry https://artefactos-ic.scae.redsara.es/nexus/repository/ad-npm

npm set always-auth true

npm set strict-ssl false

npm login

Con el último comando introducimos las credenciales del usuario de Nexus que nos han proporcionado para el proyecto y el email del desarrollador. A partir de ese momento, tendrás acceso al repositorio Nexus para instalar la librería de componentes.

Instalación de la librería desde Nexus

Utilizaremos un gestor de dependencias (npm o yarn)

npm install @dintel/dnt ui

Integración desde Github

Añade la siguiente configuración en el fichero .npmrc para acceder al registro de paquetes de Github:

@dintel-sgad:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=###USER_AUTH_TOKEN###

Nota: Asegúrate de reemplazar ###USER_AUTH_TOKEN### con tu token de autenticación de Github.

Una vez configurado el .npmrc, puedes instalar la libreria utilizaremos un gestor de dependencias (npm o yarn)

npm install @dintel-sgad/dnt-ui@X.X.X

Sustituye X.X.X por la versión específica de la librería que necesitas.

Para importar los estilos generales de la librería añadimos la ruta al archivo css desde la hoja de estilos del proyecto:

// styles.scss @import '../node_modules/@dintel-sgad/dnt-ui/dist/dnt-ui/dnt-ui.css';

El paso final es cargar y registrar los componentes en el navegador. La librería incluye una función principal que se encarga de esto. Esa función se llama defineCustomElements() y necesita ser llamada una vez al arrancar la aplicación. Un lugar conveniente para hacer esto es el archivo main.ts:

// Importamos los componentes import { defineCustomElements } from "@dintel-sgad/dnt-ui/dist/loader";

 // ... 

// Registramos los componentes defineCustomElements(window)

// styles.scss

@import '@dintel/dnt-ui/dist/dnt-ui/dnt-ui.css';

Angular

Before we can use the components in Angular, we must import and add CUSTOM_ELEMENTS_SCHEMA from Angular. This allows the use of Web Components in HTML markup, without the compiler producing errors. CUSTOM_ELEMENTS_SCHEMA needs to be included in any module that uses Custom Elements. We will usually add it to AppModule:

/ ...

// We import custom elements schema

import { CUSTOM_ELEMENTS_SCHEMA} from "@angular/core";

@NgModule({

// ...

// Add custom elements schema to NgModule

Schemas: [CUSTOM_ELEMENTS_SCHEMA]

})

export class AppModule {

To import the general styles of the library we add the path to the css file from the project style sheet:

The final step is to load and record the components in the browser. The library includes a main function that takes care of this. That function is called CustomElements() and needs to be called once when starting the application. A convenient place to do this is the file main.ts:

// We import the components

import CustomElements from "@dintel/dnt-ui/dist/loader"

// ...

// We record the components

CustomElements(window)

Once imported, the components can be used in their basic HTML markup:

Example.

Send

Results:

Send

Vue3

To integrate the library into a Vue 3 application, edit the main(.ts|.js) file to include:

// We carry the general styles

import '@dintel/dnt-ui/dist/theme-dintel/global.scss'

// We import the components

import { CustomElements} from '@dintel/dnt-ui/dist/loader'

// ...

// We record the components

CustomElements(window)

const app = createApp(App)

app.mount('#app')

We'll use a RegExp to ignore all elements that start with "dnt-" to make Vue ignore custom elements defined outside of Vue (Web Components). Otherwise, it will issue a warning about an unknown custom item:

// vite.config.ts

import { Config} from 'vite'

Import vue from '@vitejs/plugin-vue'

import vueJsx from '@vitejs/plugin-vue-jsx'

export default Config({

Plugins: [

vue({

Template: {

compilerOptions: {

isCustomElement: tag => tag.startsWith('dnt-')

customElement: /dnt-$/

(a)

...

})

To integrate the library into a Vue 3 application, edit the main(.ts|.js) file to include:

Once imported, the components can be used in their basic HTML markup:

Example:

Send

Results:

Send

Vue2

Para integrar la librería en una aplicación Vue 2, edita el archivo main.js para incluir:

// Iportamos los estilos generales

import '@dintel/dnt-ui/dist/theme-dintel/global.scss'

// Importamos los componentes

import { defineCustomElements } from "@dintel/dnt-ui/dist/loader"

// ...

// Registramos los componentes

defineCustomElements(window)

// Usa un `RegExp` para ignorar todos los elementos que empiecen por "dnt-" para hacer que Vue ignore elementos personalizados definidos fuera de Vue (Web Components). De lo contrario, lanzará una advertencia sobre un elemento personalizado desconocido

Vue.config.ignoredElements = [/dnt-\w*/]

new Vue({

render: h => h(App)

}).$mount("#app")

Para utilizar los tokens dentro de nuestro proyecto, añadimos dentro del archivo vue.config.js:

module.exports = {

...

chainWebpack: config => {

const oneOfsMap = config.module.rule('scss').oneOfs.store

oneOfsMap.forEach(item => {

item

.use('sass-resources-loader')

.loader('sass-resources-loader')

.options({

resources: [

'node_modules/@dintel/dnt-ui/dist/theme-dintel/tokens/scss/index.scss', // DINTEL TOKENS

'node_modules/@dintel/dnt-ui/dist/theme-dintel/utils/index.scss', // DINTEL MIXINS & HELPERS

]

})

.end()

})

}

Una vez importados, los componentes se pueden utilizar en su marcado HTML básico:

Ejemplo:

<dnt-button type="primary">Enviar</dnt-button>

Resultados:

Enviar

React

To integrate the library into an application with React, edit the file index.js to include:

// We carry the general styles

import '@dintel/dnt-ui/dist/dnt-ui/dnt-ui.css'

// We import the components

import CustomElements from "@dintel/dnt-ui/dist/loader"

// ...

// We record the components

CustomElements(window)

ReactDOM.render(, document.getElementById("root"))

Once imported, the components can be used in their basic HTML markup:

Example:

Send

Results:

Send

Node

Para integrar la librería en una aplicación con Node.js y express.js, edita el archivo app.js para incluir:

const express = require('express');

const { promises: fs } = require('fs')

const path = require('path')

// Función para copiar directorios

async function copyDir(src, dest) {

await fs.mkdir(dest, { recursive: true });

let entries = await fs.readdir(src, { withFileTypes: true });

for (let entry of entries) {

let srcPath = path.join(src, entry.name);

let destPath = path.join(dest, entry.name);

entry.isDirectory() ?

await copyDir(srcPath, destPath) :

await fs.copyFile(srcPath, destPath);

}

const app = express();

app.set('view engine', 'ejs');

app.set('views', 'views');

// Copiamos la librería a un directorio public/lib que consumiremos desde starting-page.ejs

copyDir(__dirname + '/node_modules/@dintel/dnt-ui/dist/dnt-ui', 'public/lib/');

app.use(express.static('public'));

app.get('/', (req, res, next) => {

res.render('starting-page', { message: 'Hello from Node.js' });

});

app.listen(3000);

A continuación en el archivo starting page.ejs:

<html>

<head>

...

</head>

...

</html>

Una vez importados, los componentes se pueden utilizar en su marcado HTML básico:

Ejemplo:

<dnt-button type="primary">Enviar</dnt-button>

Resultados:

Enviar