WCF API

WCF provee una API que agrega la funcionalidad que se espera de un Web Component: posibilidad de cambiar dinámicamente y comunicarse de forma fluida con otros elementos de la interfaz.

wcf_allInstances

La API se comunica con los componentes y el resto de los elementos de la interfaz a través del objeto global wcf_allInstances. Este objeto queda disponible una vez que el navegador carga y compila el archivo wcfManage.js.

wcfManage.js

Todo el código de la API está incluido en el archivo wcfManage.js, que se añade automáticamente a todas las descargas.

Es razonable preguntarse por qué un archivo aparte, si la idea de los componentes es que sean autocontenidos, que no requieran de ningún elemento externo. La explicación tiene que ver con el rendimiento: sería muy sencillo añadir todo el código de wcfManage.js al de cada componente, pero eso obligaría al navegador a descargarlo múltiples veces. En un archivo aparte, se descarga con el primer componente y luego se sirve desde el cache del propio navegador, aumentando sensiblemente el desempeño.

Funciones de la API

getAllInstances()

Devuelve todas las instancias presentes en el DOM, incluidos los subcomponentes (son las instancias registradas en el ecosistema de WFC).

Retorna: Un objeto que contiene todas las instancias, con el tagId del elemento como clave.

getInstanceById(tagId)

Devuelve la instancia de un componente.

Parámetros

• tagId: el id de la instancia del componente

Retorna: La instancia del componente, o undefined si no hay una instancia con ese tagId.

getInstanceElemByWcfid(tagId, wcfid)

Devuelve el elemento del componente con el atributo data-wcfid indicado.

Parámetros

• tagId: el id de la instancia del componente
• wcfid: el valor del wcfid buscado

Retorna: el elemento buscado o undefined si no existe.

getInstanceElemByQuery(tagId, selector)

Devuelve el mismo resultado que la función estándar de JavaScript querySelector dentro de un componente y sus subcomponentes.

Parámetros

• tagId: el id de la instancia del componente
• selector: cualquier selector válido para querySelector

Retorna: El primer elemento que coincide con el selector dentro del componente y sus subcomponentes. Si no hay ninguno retorna null y si no hay ningún componente con el tagId, retorna undefined.

getInstanceElemByQueryAll(tagId, selector)

Devuelve el mismo resultado que la función estándar de JavaScript querySelectorAll dentro de un componente y sus subcomponentes.

Parámetros

• tagId: el id de la instancia del componente
• selector: cualquier selector válido para querySelectorAll

Retorna: Un objeto de tipo nodeList con todos los elementos que coinciden con el selector. Si no hay ninguno retorna un nodeList vacío y si no hay ningún componente con el tagId, retorna undefined.

addProp(tagId, propName, propValue)

Asigna una prop a la instancia de un componente. Una prop es una pareja arbitraria clave → valor, para almacenar datos que sea útil recuperar más adelante.

Parámetros:

• tagId: el id de la instancia del componente
• propName: la clave de la prop, para poder recuperarla luego
• propValue: el valor de la prop.

Retorna: True en caso de éxito, undefined si no hay un componente para el tagId.

getInstancePropsById(tagId)

Devuelve todas las props asignadas a un componente. Una prop es una pareja arbitraria clave → valor, asignada con la función addProp.

Parámetros:

• tagId: el id de la instancia del componente

Retorna: Un objeto con todas las props o undefined si no hay un componente para tagId.

getInstanceProp(tagId, propName)

Devuelve el valor de una prop a partir de su clave.

Parámetros:

• tagId: el id de la instancia del componente
• propName: la clave de la prop

Retorna: El valor de la prop si el componente tiene una prop con esa clave o undefined en cualquier otro caso.

Funciones para el manejo de instancias

getUniqueInstanceId(id)

Verifica que un id es único para una instancia, y si no lo es genera uno único agregando al id un número correlativo. Por ejemplo si recibe “button” como parámetro y ya existen “button” y “button_1”, devolverá “button_2”.

Cuando se instancia un componente, el código ya prevé generar un id único, utilizando esta función, pero resulta útil cuando se generan componentes dinámicamente y se asigna explícitamente el id, para usarlo más adelante en el código.

Parámetros:

• id: el id que se necesita verificar si es único.

Retorna Un id único para la instancia, con base en el id recibido.

addSubComp(elem, compName, attr = {})

Agrega un componente a cualquier elemento y le asigna los atributos.

Parámetros:

• elem: cualquier elemento del DOM
• compName: el nombre del componente
• attr: un objeto con parejas de valores nombreDeAtributo → valor

Retorna: El id de la instancia o false si no pudo crearlo o agregarlo.

Nota: el elemento no tiene por qué pertenecer a un WebComponent, puede ser también cualquier elemento válido del light Dom. En ese caso se agregará un componente con su propio shadow DOM.

setInstanceAttr(tagId, attr)

Asigna el valor de los atributos a una instancia de un componente. Es una abreviatura del llamado a setAttribute para cada par clave valor.

Parámetros:

• tagId: el Id de la instancia del componente.
• attr: un objeto con parejas de valores clave → valor

Retorna: El id de la instancia si es exitoso o false en caso de error.

setInstanceElemOnClick(tagId, selector, href)

Asigna el atributo onClick a cualquier elemento dentro de un componente. Asigna además el puntero correspondiente y el atributo role=”link” para garantizar la accesibilidad.

Parámetros:

• tagId: el Id de la instancia del componente
• elemId: el id del elemento al que se le asigna el onClick
• href: la URL destino del click

Retorna: true en caso de éxito y false en caso de error.

removeInstance(tagId)

Elimina una instancia.

Parámetros:

• tagId: el Id de la instancia del componente

Retorna: true si fue exitosa, false en caso contrario.

Funciones para manejo de atributos

attrObserveRegister(tagId, name, dataParam, callback)

Agrega un atributo a los observados para todas las instancias de un componente.

Es importante notar que si bien se llama para una instancia, es solo a los efectos de reconocer el componente. El monitoreo del atributo a través de un MutationObserver de JavaScript pertenece a la clase que define el componente y por lo tanto, pasa a ser válido para todas las instancias.

Parámetros:

• tagId: el Id de la instancia del componente
• name: el nombre del atributo a monitorear
• dataParam: un objeto con información que será enviado a la función callback cada vez que sea invocada
• callback: la función a invocar cuando hay un cambio en el atributo

La función callback es invocada cuando se crea, se destruye o se modifica un atributo que coincide con el parámetro name en cualquier instancia del componente, con los siguientes parámetros:

• instance: la instancia del componente en el que se modificó el atributo.
• name: el nombre del atributo
• paramData: los datos que fueron cargados al llamar a la función attrObserveRegister. Estos datos son los mismos para todas las instancias, y si se modifican, cualquier llamado de cualquier instancia recibirá los datos modificados.
• oldValue: el valor anterior del atributo
• newValue: el nuevo valor del atributo

Retorna: undefined

Funciones para manejo de Variantes

Web Component Factory tiene la posibilidad de generar múltiples variantes para un mismo componente, tanto cuando la fuente es Figma como cuando es HTML. Se listan a continuación las funciones de la API que permiten un manejo sencillo de las distintas variantes.

En la nomenclatura de WCF un componente que tiene variantes de denomina un Set.

getCurrentVariant(setTagId)

Devuelve la variante actual de la instancia de un componente

• setTagId: el Id de la instancia del componente

Retorna: la variante actual . Retrona 0 tanto en el caso de que no se haya definido una variante como de que el componente no sea un set. Retorna undefined si no hay una instancia con ese setTagId.

getElemVariant(elem)

Devuelve la variante actual de un elemento dentro de un componente, (que es la misma siempre en todos los elementos del componente).

• elem: cualquier elemento dentro de algún componente.

Retorna: el número de variante, si lo tiene o undefined si el elemento no pertenece al ecosistema de WCF.

Funciones no documentadas

wcfManage.js incluye un conjunto de funciones que no están documentadas. Se trata de funciones que utiliza internamente, pero que no tienen la intención de formar parte de la API. Dado que se cargan y son métodos de wcf_allInstances, están disponibles, pero Web Component Factory no asume ningún compromiso ni de que seguirán disponibles en el futuro ni que su comportamiento se modifique sin previo aviso.

Por lo tanto, la recomendación es no utilizarlas, o en el caso de hacerlo copiarlas de modo que futuras versiones no las alteren.