Tutorial: Build a Featured Product Widget with Blocks and the CLI

This tutorial walks you through creating a Wix app that displays a featured product widget using the @wix/stores SDK module. Here is an image of how the widget looks on a site:

Before you begin

Before getting started, make sure that:

• You have Node.js (version 20.11.0 or higher).
• You’re logged into your Wix Studio account. If you don’t already have one, sign up for a Wix Studio account.

Step 1 | Set up your environment

First, let's set up a development site, create the app and add the app to the site.

Create a Site

To create a development site:

1. Go to the eCommerce templates page.
2. Select a site template and click Edit. This creates your own copy of the site.
3. Publish the site.

Create an App

To create your app:

1. Open your terminal.

2. Run:

   Copy

3. When asked what you would like to do, select Create a new Wix App.

4. When asked how you would like to create your new app, select Create a basic app.

5. Enter a name for your app.

6. Enter a project folder name.

7. Wait as the CLI creates the files for your project.

8. Navigate to the project folder:

   Copy

9. Run the generate command:

   Copy

   This will display a list of extensions that you can add to your app.

10. Select Site Widget.

11. When asked which framework to use, select Blocks.

12. When asked if you'd like to install dependencies, type Y.

13. After the CLI finishes installing dependencies, install the the Wix Stores package:

    Copy

Install your app on a Development Site

1. Run the following command to start up a local development server:

   Copy

2. When asked to select a Development Site, select Pick an existing site.

3. Select the site you just created.

4. Press Enter to install your app on the site.

5. Click Agree & Add in the browser that opened.

6. Go back to your terminal and type B to open the Blocks editor.

Step 2 | Design your widget in the Blocks Editor

Now you are in the Blocks Editor, where you'll design your widget.

1. Click Create Extension > Widget.

2. Search for the Featured Item widget.

3. Select the widget and click Add Widget.

   

4. Delete the first widget, Widget1, by clicking the three dots next to its name in the Widgets menu.

5. Click Sync and then Sync Changes to confirm. This syncs your app's UI to your local code files.

   

Step 3 | Add your widget to the site

1. In the CLI, type E to open the site in the Editor of your Development Site. Once the site opens, your app is added to the site.

2. Click + Add Elements > App Widgets.

3. Click on the Featured Item widget to add it to the canvas.

   

The widget is now located on the page and uses the site theme to match look and feel of the site.

Step 4 | Implement the widget logic

In this step, you’ll define the widget logic, which presents data according to the product ID.

Define the widget API in api.ts

Define a property in the widget API, to hold the product ID.

1. Open the src folder of your project.
2. Go to the file: site/widgets/blocks/featured-item/api.ts
3. Delete the default event, load.
4. Delete the default function, myPublicFunction().
5. Change the property name of the property in the props array from name to productId.
6. Save the file.

Your code should look like this:

Use the property to present data in the widget.ts

The widget.ts in the same folder is where you add your widget's business logic. You'll use the property you defined in the api.ts to present the data of the selected product.

1. Import the SDK stores module:

   Copy

2. Define a helper function updateProduct inside the defineWidget() callback that fetches product data using the widget's productId property and updates the title, subtitle, and image elements accordingly.

   Copy

3. Replace the boilerplate code of the onReady() and onPropsChange() functions. Paste the following code instead, to call the updateProduct() function. Make sure that all these functions are within the defineWidget() function.

   Copy

   Copy

4. Delete the boilerplate function, myPublicFunction, from the return statement.

5. Save the file.

Step 5 | Design the Settings Panel

The Featured Item widget that you added to the app comes with a default settings panel. Let's modify this panel.

1. Go back to your open Blocks editor.

2. Click the Editor Experience icon.

3. Click Custom Panels. You can see that the Featured Item widget has one custom panel, named Settings.

4. Delete the toggle and text elements.

5. Click + Add Elements and add a dropdown element.

   

6. Click the Settings icon and change the Field title to Choose product (or any other title you want).

7. Click Sync to update your UI to your code files.

Step 6 | Add the panel logic in the panel.ts

Let's implement the Settings panel logic. The panel gets the list of products and maps them to the dropdown. When the dropdown selection changes, the panel sets the property in the widget API.

When the panel opens, it presents the product that was set in the widget API property. If no property was set, the panel presents the first product in the list.

1. Go to: site/widgets/blocks/featured-item/panels/settings/panel.ts

2. Add the following import:

3. Replace the onReady() function with this code, which gets the Stores product and sets it to the widget’s productId property.

   Copy

}); ``` 4. Save the file.

Step 7 | Add a price element to the widget

Back in the Blocks editor, let's add a text element to present the product price. To do this, you'll need to add a paragraph to the widget's stack.

1. Go back to the Featured Item widget in the App Interface.
2. Right click on the widget stack, which brings together the Item Title, the description and the button.
3. Click Quick Add.
4. Click Paragraph.

Make some design changes

1. Change the content of the paragraph you just added to be a price. For example, 75$.
2. Make sure that the paragraph is placed in the third row of the stack (use the Move up and Move down errors if needed.)
3. Align the paragraph to the left.
4. Change the font size to 16.
5. Reduce the size of the stack gaps.
6. Change the button text to More Info.

Your finished widget should look like this:

Rename the ID of the element you added

Let's rename the new element, so that you can refer to it in your code.

1. Make sure the text element is selected.
2. Click the Layers icon.
3. Click the three dots next to the #text1 element.
4. Click Rename and rename the element to price.
5. Click Sync.

Add the price to the updateProduct() function

Let's update the updateProduct() function in the widget.ts.

1. Add this line under the other lines in the function.

   Copy

2. Save the file.

Step 8 | Test Your Widget

It's time to test the widget in the editor and see the product information update when the panel changes.

1. Go back to the editor to see the new price element (you can type E if you closed it).
2. Click the widget's Settings action button.
3. Select various products from the dropdown and see that the widget information updates as expected.

Step 9 | Add a button click behavior

Let's add the logic for the button to lead the user to the product page.

1. Press Ctrl + C in the terminal, to stop the development server.

2. Run:

   Copy

3. In the widget.ts file, add:

   Copy

4. In the updateProduct() function, add:

   Copy

5. Save the file.

You'll be able to test the button on a live site after releasing a version of the app.

Step 10 | Release the app to create a version

Now that you're done developing your app, you can create a version.

1. Run:

   Copy

2. Run dev again:

   Copy

3. Click S to open the site.

4. Go to the widget.

5. Click the button — it should navigate to the product page.

Congratulations, you’ve created and connected a fully functional, data-powered featured product widget using Blocks and the CLI!