Wix Blocks: Using Custom Elements
5 min read
Enhance your Blocks widgets with your own design features and CSS capabilities, use any web technology or third party libraries, with Custom Elements. You can add any Javascript component by linking a custom element to a server URL or a Velo file. If needed, you can set more attributes directly from Blocks.
What Are Custom Elements
Custom elements let you use your own HTML tags in Blocks widgets. These elements work across all supported browsers, and can be used with any JavaScript ES6 library or framework that works with HTML 5.
With custom elements, you can:
- Design elements with additional functionality or CSS capabilities.
- Embed any widget that requires full DOM access.
Code requirements:
- Your code must be up to date and HTML5 compatible. You should transpile your JS to ES2020.
- If you are hosting your own code, it must be hosted over a secure protocol (HTTPS). Also, all HTTP calls from the code needs to be to HTTPS endpoints.
- If you are hosting your own code, all relevant design settings and complex functionalities (for example the CSS and other JS files), must be bundled to a single JS file. Don’t set anything in a separate file.
Step 1 | Adding and Setting Up a Custom Element
Add as many custom elements as you need to your widget. After dragging a custom element to your widget, define its source (server URL or a Velo file) and give it a tag name to appear in the page registry. The tag name should be the exact name used in the customElement.define() function.
1. See how to add the element
panel.2. See how to define your source file
3. See how to enter the tag name
Tips
- To see how the custom element looks live, install your app on a site and go to the published site. This is because, for security reasons, the custom element is rendered inside an iFrame in the site-editor and in preview mode, which might affect the layout.
- You can define your element's SEO settings using the Custom Element SEO Markup property.
Step 2 | Adjust the Custom Element by Setting Attributes
The custom element HTML attributes let you adjust your element according to parameters that you control. For example, you can set dynamic texts or change colors on the go. Use the Element Attributes panel to add, edit and remove attributes directly from Blocks, so you don't have to access the actual code. Just make sure that the script of your custom element acknowledges and handles these attributes. Otherwise, they won't function properly.
See how to set the attributes
Step 3 | Connect the Custom Element to Your Widget's Functionality
In most cases, you’ll want to use the custom element logic from one or more of these:
- The widget’s panel
- The site where the app is installed
- Another widget in the app
To do this, define properties in the widget API. These properties should represent the Custom Element attributes. The following steps explain how.
Tip
You can skip these steps and use setAttribute(), if you only need to refer to the custom element's attributes inside this widget and without panels.
Add a property to the widget API
- Click the Widget API
icon on the bottom of your Blocks screen. - Click Add New Property or hover over Properties and click the
icon. - Name your property, select its type and default values, add a description.
- Click Create.
Set the attribute in the onPropsChanged() function
Define your widget's onPropsChanged() function to handle a change in this property. For example, let's say we added a property named title, which enables the user to change the title of the custom element. This code will set the custom element attribute title to be the same as the widget's property title.
1$widget.onPropsChanged((oldProps, newProps) => {
2$w('#customElement1').setAttribute('title', $widget.props.title);
3});Optional: create a panel to change the property
Create a panel that allows a site creator who installed your app to be able to change the widget properties (and therefore, the custom element attributes).
- Click the Panels tab at the top of Blocks.
- Click Create New Panel, or open a panel that you already created.
- Add an element that can receive a the new property (in our example, it's an input element named 'panelTextInput1').
- Open the designated code area in the Panels tab.
- Add code that will pass the property from the panel to the widget (in our example, it goes both ways):
1import wixWidget from 'wix-widget';
2
3$w.onReady(async function () {
4 const props = await wixWidget.getProps();
5 $w('#panelTextInput1').value = props.title;
6 $w('#panelTextInput1').onChange(async () => {
7 wixWidget.setProps({ title: $w('#panelTextInput1').value });
8 })
9});To summarize this last step: the site-creator changed the title through the panel. The new title was passed to the widget through the ‘title’ property. When the property changed, the new title was sent to the custom element as an attribute.
Did this help?
|