About Custom Elements in Blocks

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 in a single JS file. Don’t set anything in a separate file.

Note: A site does not need a premium account or a domain to use a Blocks app with a custom element.

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
  1. Open or create Blocks widget in your app.
  2. Open the Add panel.
  3. Click Embed.
  4. Drag the Custom Element onto your widget.
  5. Stretch or place the element as you wish.
2. See how to define the element source file
  1. Click the custom element.
  2. Click Choose Source and select one of two options:
    1. Server URL: enter the URL, including the file name.
    2. Velo file: select one of your Velo files. If you don’t have a Velo file yet, this creates a file in the Public and Backend section. If you don’t have a namespace, you’ll be prompted to create one.
3. See how to enter the tag name
  1. Click the custom element.
  2. Click Choose Source.
  3. Enter a Tag Name for your element.
    • The tag name must be at least two words long, separated by a dash (e.g., weather-widget).
    • The tag name must be exactly the same as appears in your custom element's code, for example: customElements.define('weather-widget', WeatherWidget).

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, or change the custom element inner logic according to the widget’s instance on a specific site (using getDecodedAppInstance()).

Make sure that the script of your custom element acknowledges and handles these attributes. Otherwise, they won't function properly.

There are two ways to initiate your custom element's attributes in the Blocks app:

A. Click Set Attributes: Set and initiate your element’s attributes by adding them to this designated panel. You can also edit or remove the attributes later.

  1. Click Set Attributes on the custom element.
  2. Click New Attribute.
  3. Enter a name for the attribute, for example, title.
  4. Enter the value for the attribute (it can be any relevant string).

B. Use Code: Set your element’s attributes in the widget code with the setAttribute() function.

For example, let's say that you need to use data from your widget's instance on a specific site, inside your the custom element’s logic. This data is returned by the getDecodedAppInstance() function. Your widget code will look like this:

Copy

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:

If you only need to refer to the custom element's attributes inside this widget, there is no need to connect it to the widget API or add a panel.

Add a property to the widget API

  1. Click the Widget API icon on the bottom of your Blocks screen.
  2. Click Add New Property or hover over Properties and click the icon.
  3. Name your property, select its type and default values, add a description.
  4. Click Create.

Set the attribute in the onPropsChanged() and onReady() functions

Define your widget's onPropsChanged() function and onReady() functions 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. The code below sets the custom element attribute title to be the same as the widget's property title. Creating a function to apply props and using it in both the onPropsChange() and onReady() events, helps you avoid problems when your props aren't applied in preview mode, or other similar situations.

Copy

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).

  1. Click the Panels tab at the top of Blocks.
  2. Click Create New Panel, or open a panel that you already created.
  3. Add an element that can receive a the new property (in our example, it's an input element named 'panelTextInput1').
  4. Open the designated code area in the Panels tab.
  5. Add code that will pass the property from the panel to the widget (in our example, it goes both ways):
Copy

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.

Optional: Use the Color Intput panel element

You can also use the Color Input element (in our case its name is panelColorPicker1) to set some style properties. For example:

Copy

Note: When creating a custom-element-only widget, it’s best practice to make it 100% of a widget and define it as non-selectable in the Configuration tab, so that when a site builder clicks on the widget to configure its settings, they will not click on the custom element.

Did this help?