API de Componentes
El API de componentes está basado en el proyecto Croupier. Es un proyecto creado de manera interna en ETS para la generación de APIs de componentes.
Los componentes que se instancian a través del API son componentes web nativos, definidos por los estándares de la W3C. Se reciben con un template HTML ya renderizado, con estilos y con funcionalidad javascript encapsulada.
Cómo empezar
Para hacer uso del API es necesario insertar el script croupier.js
dentro de la etiqueta
<html>
<html>
...
<script src="https://components.etsfactory.com/croupier.js"></script>
</html>
Inicialización del objeto croupier
Los componentes no se renderizan hasta que no se inicialice el objeto Croupier en javascript. Para inicializarlo
hay que pasar un objeto de configuración. La única propiedad que se pasa, por ahora, son las fuentes de proveedores. Esta
inicialización es conveniente hacerla al final del <body>
.
Propiedades del campo sources
:
name
: Nombre del proveedor, definido por el usuario, para llamar a sus componentes.url
: Ruta del servidor donde están los componentes del proveedor.-
token
: Clave necesaria para llamar al API del proveedor. El token, por ahora, es una clave que se genera en el api de componentes y que se pasa a los clientes que van a utilizar el API.
<body>
...
new Croupier({
sources: [
{
name: "ets",
url: "https://components.etsfactory.com",
token: "xxxxxxxxxxxxxxxxxxx"
}
]
});
</body>
Uso de los componentes
Los componentes se insertan dentro de la estructura de la página como si fuesen cualquier tag html nativo, al que hay que pasarle la
propiedad name
.
<cr-component name="search"></cr-component>
Immediate
Si el componente no necesita parámetros de entrada para su correcto renderizado, se le pasa la propiedad
immediate
y se ejecuta automáticamente.
<cr-component name="search" immediate></cr-component>
Instanciar componentes por javascript
La mayoría de los componentes necesitan recibir parámetros de entrada para instanciarse. Esto significa que, por defecto, los componentes no se instancian hasta que no se le llama a la función load.
<cr-component id="results" name="search"></cr-component>
Para llamar a la función load
primero hay que obtener el elemento del DOM, y después llamar la función pasándole como
parámetro el objeto que espera recibir el componente.
const resultsElem = document.getElementById("results");
resultsElem.load({
query: "bbva",
max: 5
});
Obtener información de los componentes
Hay componentes que exponen cierta información para que pueda ser consumida por el que hace uso del API. Hay 2 maneras de obtener esta información:
- Propiedad
data
: Se obtiene desde el objeto DOM - Evento
onChange
: Listener sobre el objeto DOM
Propiedad data
const resultsElem = document.getElementById("results");
const data = resultsElem.data;
Evento onChange
const resultsElem = document.getElementById("results");
resultsElem.addEventListener("change", function(e) {
const data = e.detail;
})
Estilos
Se pueden modificar los estilos de los componentes adjuntando hojas CSS en la creación de croupier.
<body>
...
new Croupier({
sources: [
{
name: "ets",
url: "https://components.etsfactory.com",
token: "xxxxxxxxxxxxxxxxxxx",
styles: {
base: "url" (a hoja de estilos CSS personalizada),
components: {
nombreDelComponente1: "url" (a hoja de estilos CSS personalizada),
nombreDelComponente2: "url" (a hoja de estilos CSS personalizada),
...
nombreDelComponenteN: "url" (a hoja de estilos CSS personalizada)
}
}
}
]
});
</body>
La hoja de estilos base
se aplica en todos los componentes. Y además, se pueden adjuntar estilos para cada uno de los
componentes añadiendo su nombre, en camelCase, dentro de la propiedad componentes
. Es decir, si se define el
base
y también uno por componente ambos estarán en el componente renderizado.
Prioridad de los estilos personalizados
En la hoja de estilos personalizada no basta con poner el nombre de la clase para redefinir estilos, porque los estilos internos de los componentes van asociados a un hash y, por tanto, tendrán mayor prioridad que la clase. Para que los estilos personalizados sean prioritarios es aconsejable que vayan precedidos por el id del componente. Todos los componentes, en su tag raíz, llevan como id el nombre del componente.
Por ejemplo, para definir los estilos del componente search
quedaría así:
#search .isin {
font-size: 16px;
}
#search .result {
color: red;
}
Y la llamada a croupier sería:
<body>
...
new Croupier({
sources: [
{
name: "ets",
url: "https://components.etsfactory.com",
token: "xxxxxxxxxxxxxxxxxxx",
styles: {
components: {
search: "http://localhost:8080/styles/search.css"
}
}
}
]
});
</body>
Como todos los componentes tienen su identificador se podrían poner todos los estilos dentro del base
:
#search .isin {
font-size: 16px;
}
#search .result {
color: red;
}
#risk-selector .circle-text {
fill: red;
}
Gestión de errores
Los componentes en caso de error emiten dicho error que se puede capturar.
const recoDraftProposal = document.getElementById("reco-draft-proposal");
recoDraftProposal.addEventListener("error", function(e) {
console.log(e.error);
})