Files and Code for Blocks Site Widgets

When you add a Blocks site widget extension to your CLI project, the CLI generates the following directory structure in your project repo:

In the your site widget folder, the following files are created:

• An api.ts file that contains the declarations for your Widget API properties, events, and functions. These are exposed when your widget is installed on a site (in the Wix Editors) or when it's added inside another widget.
• A widget.json file that contains the ID of your widget. Do not modify this file.
• A widget.ts file that contains the logic for your widget. Here you implement and use the properties, events, and functions that you declared in api.ts.

If you add panels to your widget in the Blocks editor and sync to the CLI, a panels directory is created inside your widget’s directory. panels contains subdirectories for each panel you added in Blocks. For more information about the panels code files, see Files and Code for Blocks Site Widget Panels

api.ts

When you add a Blocks site widget extension in the CLI, an api.ts file is generated for the extension. This file contains the declarations for your Widget API properties, events, and functions.

When you add a new blocks site widget to your project, you'll see the following code in api.ts:

You can implement and use these properties, events, and functions in your widget.ts file. They are exposed when your widget is installed on a site (in the Wix Editors) or when it's added inside another widget.

Properties

Declare widget properties as key-value pairs within the props object. Property values can only be strings.

When a widget is added to a site, your app (and users) can interact with your widget properties using $widget.

Methods

Declare methods you want your widget to expose within the methods object. You must return these methods from defineWidget() in your widget.ts file.

Events

Declare events you want your widget to trigger within the events object. You can trigger these events in defineWidget() in your widget.ts file.

widget.ts

When you add a Blocks site widget extension in the CLI, a widget.ts file is generated for the extension. This file contains the code for your site widget.

When the widget.ts file is generated, it looks like this:

defineWidget()

defineWidget() accepts a function that will execute when your widget is added to a site. This function accepts the following namespaces as parameters, allowing you to work with them in your code:

$w

$w contains everything you need in order to work with your widget's components. It allows you to select elements in your widget and interact with them. Each element type exposes properties and functions that you use to enhance the functionality of your widget.

$w.onReady()

$w.onReady() is called when all widget elements have finished loading.

Place your widget initialization logic inside the $w.onReady function.

$widget

$widget contains functionality for working with your Blocks widget's API from within the widget code. It includes: properties for storing values associated with the widget. A handler function that runs when those properties change. A function to fire events from your widget.

Properties and events must be defined in your api.ts file.

For more information, see About the Widget API in Blocks

$widget.onPropsChanged()

$widget.onPropsChanged() is called whenever one of your widget’s properties is changed, taking the old and new properties as parameters. Add logic to this function to respond to these changes.

return{}

If you want your widget to expose any functions, specify them in the returned object. You define these functions in your widget’s api.ts file.

Wix Javascript SDK

Use the Wix Javascript SDK to access and manage Wix business solutions.

For example: