Wix Blocks: Using Your Widget API When Editing a Site

Wix Blocks is open to all Wix Studio users. To get access to Blocks, join Wix Studio.

After a Widget API was defined in Blocks and the widget is now installed on a site, you can easily access the Widget API from the Wix Editor or Editor X. 

Learn more about using the Widget API when editing a site: 

Important Any changes that you make to the API while editing a site, only impact this specific site. The original widget is not impacted. If this isn't your intention and you want to edit the Widget API so that it updates on all sites using the widget, edit it in Wix Blocks.

Access Widget API Properties

Access Properties Through the Settings Panel

  1. Select the widget in the Wix Editor or Editor X.  
  2. Click Settings in the widget's action bar to access its properties. 
  3. Edit the properties in the Settings panel. Note: Your changes will only apply to the site you're editing.
  4. Click Preview to see how your widget works on this site. 

Important If you did not define properties in your Widget API, you won't see the Settings button.

If you have created a custom panel for the Settings button, the default Settings panel with all your widget's properties won't be available.

Access Properties Through Code

  1. Select the widget in the Wix Editor or Editor X.
  2. Click the Properties and Events  icon to view the widget's ID. 

  1. Use the syntax: $w("#)".property  to access properties (use extra dots if the property is an object and you want to access its inner properties). For example, let's log the name of our customer from the shopping widget to the console. 
Copy
1
let name = $w("#widget11").existingCustomer.name;
2
console.log(name);

Access Widget API Events

There are two ways to handle an event fired from a Blocks widget in the site editor.

Option 1

When your widget is installed on a site, site creators can see the event in the Velo Properties and Events panel, in the format of on<EventName>, for example, onAddedToCart.

  1. Select the widget in the site editor.
  2. Click on the name of the event in the Properties and Events panel.
  3. Handle it in the empty function that appears in your Velo IDE.

Note: If you want to handle data from this event, you must add it as an argument (it's not added automatically). For example:

Copy
1
export function widget11_addToCart(event){
2
  const { productId, customerId } = event.data;
3
  console.log('Product added to cart', { productId, customerId });  
4
}

Option 2

Handle the event in the onReady() function of your site.

Copy
1
$w.onReady( function() {
2
       $w('#widget1').onAddedToCart((event) => {
3
        const { productId, customerId } = event.data;
4
        console.log('Product added to cart', { productId, customerId });
5
      });
6
} );

Important Note that the condition for firing the event was defined in Blocks, while the actions to take when catching the event are defined in the site that installed the widget. 

Learn more about defining your API events in Blocks.

Access Widget API Functions

Copy
1
let productAddedToCart = $w('#widget11').addItemToCart(productID, quantity));

Access your Widget API functions in your site's code easily, with Velo's auto-complete. 

For example, when an item was successfully added to the cart - you can notify the user. 

Once you begin to write the functions name (such as "add"), Velo auto completes so you can see what functions are available:  

Was this helpful?
Yes
No