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);
})