WCF provides an API that adds the functionality expected from a Web Component: the ability to dynamically change and communicate seamlessly with other interface elements.
wcf_allInstances
The API communicates with the components and the rest of the interface elements through the global object wcf_allInstances. This object becomes available once the browser loads and compiles the wcfManage.js file.
wcfManage.js
The API’s full code is included in the wcfManage.js file, which is automatically added to every download.
It would be reasonable to ask why a separate file is needed, if the idea of components is that they are self-contained and do not require any external elements. The explanation has to do with performance: it would be very simple to add all the code from wcfManage.js to each component’s code, but that would force the browser to download it multiple times. In a separate file, it is downloaded with the first component and then served from the browser’s cache, significantly improving performance.
API functions
getAllInstances()
Returns all instances present in the DOM, including subcomponents (these are the instances registered in the WCF ecosystem).
Returns: An object containing all instances, with the element’s tagId as the key.
getInstanceById(tagId)
Returns a component instance.
Parameters:
- tagId: component instance id
Returns: the component instance, or undefined if there is no instance with that tagId to be found.
getInstanceElemByWcfid(tagId, wcfid)
Returns the component element with the specified data-wcfid attribute.
Parameters:
- tagId: component instance id
- wcfid: searched wcfid value
Returns: the element instance or undefined if nonexistent.
getInstanceElemByQuery(tagId, selector)
Returns the same outcome as a standard JavaScript querySelector function within a component and its subcomponents.
Parameters:
- tagId: componente instance id
- selector: any valid querySelector selector
Returns: the first element matching the selector within the component and its subcomponents. If none is found, it returns null and if no component with the tagId exists, it returns undefined.
getInstanceElemByQueryAll(tagId, selector)
Returns the same outcome as the standard JavaScript querySelectorAll within a component and its subcomponents.
Parameters:
- tagId: component instance id
- selector: any valid querySelectorAll selector
Returns: a nodeList object containing all elements matching the selector. If none are found, it returns an empty nodeList and if no component with the tagId exists, it returns undefined.
addProp(tagId, propName, propValue)
Assigns a property to a component instance. A property is an arbitrary key → value pair used to store data that may be useful to retrieve later.
Parameters:
- tagID: component instance id
- propName: property key for later retrieval
- propValue: property value
Returns: true on success, undefined if there is no component for the tagId.
getInstancePropsById(tagId)
Returns all properties assigned to a component. A property is an arbitrary key → value pair, assigned to the addProp function.
Parameters:
- tagId: component instance id
Returns: an object with all properties or undefined, if no component with the tagId exists.
getInstanceProp(tagId, propName)
Returns property value from its key.
Parameters:
- tagId: component instance id
- propName: property key
Returns: the property value if the component has a property with that key or undefined in any other case.
Instance handling functions
getUniqueInstanceId(id)
Verifies that an id is unique for an instance, and if not, generates a unique one by appending a sequential number to the id. For example, if it receives the parameter “button”, and this parameter and “button_1” already exist, it will return “button_2”.
WCF generated components already call this function in order to have unique ids. However, it is very useful in cases where components are generated dynamically, and it is necessary to retain the id of each one to use it later in the code.
Parameters:
- id: the id to verify for uniqueness
Returns: unique id for the instance based on the received id.
addSubComp(elem, compName, attr = {})
It adds a component to any element and assigns the attributes.
Parameters:
- elem: any DOM element
- compName: component name
- attr: an object with key → value pairs of attribute names and values
Returns: component id or false if it could not be added or created.
Note: the element does not need to belong to a WebComponent, it can also be any valid light DOM element. In that case, a component with its own shadow DOM will be added.
setInstanceAttr(tagId, attr)
Assigns attribute value to a component instance. It is a shorthand for calling setAttribute for each key → value pair.
Parameters:
- tagId: component instance id
- attr: an object with key → value pairs
Returns: instance id if successful or false in case of error.
setInstanceElemOnClick(tagId, selector, href)
Assigns the attribute onClick to any element within a component. Additionally, it sets the appropriate cursor and the role:”link” attribute to ensure accessibility standards.
Parameters:
- tagId: component instance id
- elemId: element id to which the onClick attribute is assigned
- href: the URL destination of the click
Returns: true in case of success and false in case of error.
removeInstance(tagId)
Deletes an instance.
Parameters:
- tagId: component instance id
Returns: true in case of success and false in case of error.
Attribute handling functions
attrObserveRegister(tagId, name, dataParam, callback)
It adds an attribute to the observed attributes for every component instance, so that modifying the attribute modifies the component itself.
It is important to note that while the function is called for an instance, it is only for recognizing the component class. Attribute monitoring through a JavaScript MutationObserver belongs to the class that defines the component and therefore, it will be applied to all instances.
Parameters:
- tagId: component instance id
- name: name of the attribute to observe
- dataParam: an object with information that will be sent to the callback when called
- callback: the function that will be called when an attribute is modified
Callback function is called whenever an attribute matching the name parameter is created, modified or removed in any instance of the component, with the following parameters:
- instance: component instance where the changed attribute belongs to
- name: attribute’s name
- paramData: data loaded when calling attrObserveRegister. This data is the same for all instances, and if modified, any call from any instance will receive the modified data
- oldValue: attribute’s old value
- newValue: attribute’s new value
Returns: undefined.
Variant handling functions
Web Component Factory offers the possibility to create multiple variants for a single component, directly from Figma or HTML. Listed below are the functions that allow an easy use of the different variants.
In WCF terms, a component with variants is referred to as a Set.
getCurrentVariant(setTagId)
Returns the current variant of a component instance.
Parameters:
- setTagId: component instance id.
Returns: The current variant. Returns 0 if no variant has been defined or if the component does not conform to a Set. Returns undefined if no instance with that setTagId is found.
getElemVariant(elem)
Returns the current variant of an element within a component (which is the same for all elements in the component).
Parameters:
- elem: any element within a component
Returns: The variant’s number if defined, or undefined if the element does not belong to the WCF’s ecosystem.
Undocumented functions
wcfManage.js includes a set of functions that are not documented. These are functions used internally but are not intended to be part of the API. Since they are loaded and are methods of wcf_allInstances, they are available, but Web Component Factory does not guarantee that they will remain available in the future or that their behavior will not change without notice.
Therefore, it is recommended not to use them, or if used, to copy them so that future versions do not alter them.
Leave a Reply