Help Center
    Help Center
  1. Creating your site
  2. Advanced features
  3. Wix Blocks
  4. Tutorials
    5. Wix Blocks Tutorial: Creating a Counter Widget

Wix Blocks Tutorial: Creating a Counter Widget

12 min read
Wix Blocks is open to all Wix Studio users. To get access to Blocks, join Wix Studio.
This tutorial shows you how to build a counter widget, where you can increment and decrement a number. Through this simple widget we will walk through everything that you can do with Wix Blocks. 

counter
We recommend that you build this widget from scratch, but if you get stuck, you can view a template of the widget in Blocks and edit it under your Wix account.

Step 1 | Create a new Widget in Blocks

  1. Create an empty Blocks app.
  2. If the app is not created with a default widget, add a widget to your app. 

Step 2 | Add a Layouter

A layouter is a container that allows responsiveness. It will keep the other elements organized. To add a layouter: 
  1. Click the Add Elements add button in the top menu. 
  2. Click LAYOUT ->  Flexboxes -> LAYOUTERS
  3. Click the vertical 3-section layouter. 

Step 3 | Add Widget Elements

Adding the buttons

  1. Click the Add Elements add button on the top menu. 
  2. Click BUTTON. 
  3. Drag and drop a button onto the right section of the layouter.
4.  Click Change Text & Icon. 
5.  Select Text only from the drop down list. 
6.  Change the text to "+".
7.  Click the Design design icon icon in the Inspector panel inspector and select Text.
8.  Click Themes and select Heading 6 from the drop down list. 
9. Drag and drop another square button to the left section. 
10. Change the text to "-".

Adding the middle number

  1. Click the Add Elements add button and select TEXT.
  2. Drag and drop an 32px Title element to the central section of the layouter. 
  3. Edit the text to "0" and align it to the center. 

Changing the IDs

  1. Click the Properties and Events properties and events icon in the bottom right of the screen.  
  2. Change the ID of your increment button to incBtn.
  3. Change the ID of your decrement button to decBtn.
  4. Change the ID of your text element to countTxt.

Step 4 | Add Code to Your Elements

Now it's time to make the widget do what it's supposed to do: count up and down when the buttons are clicked. 
1.  Click the Code tab or go to the bottom part of your screen to add code to your widget. 
2.  Add the following code before your onReady() function.

1//Set the count to 0 
2let count = 0;
3
4//Assign the count to your text element
5function render() {
6 $w('#countTxt').text = count.toString();
7}
8
9//Add a certain amount to the count and fire an event in the widget API
10function addToCount(amount) {
11 count += amount;
12 render();
13}
3.  Add the following code in your onReady() function. 
1 $w('#incBtn').onClick(() => {
2  addToCount(1);
3 });
4 
5   $w('#decBtn').onClick(() => {
6  addToCount(-1); 
7 });
8  
9  render();
4.  Click the Preview button to see your widget in action. 

Step 5 | Make Your Widget Customizable with Widget API

You can define an API for your widget, so that the user (a site owner who installs the widget) can customize it to their needs. The API can contain properties, events and exported functions.

Let's say that you want the site owner to be able to decide what the "step" of the count is. Perhaps they want the step to be 2, so that the count is 0,2,4,6 etc. 

You can define a property in the widget API named "step" and allow the user to customize it.

Define the "step" Property

  1. Click the Widget API widget api icon to open the Widget API panel.
  2. Click Add New Property in the Properties section (or hover over the section and click the add icon that appears).
3.  Name your property "step", give it the type Number and a default value of 1. 

Change Your Code to Consider Your New Property

Change your code so that when the buttons are clicked, addToCount is called with the step from the properties rather than with the default value of 1.
Use $widget.props to access your properties (notice the autocomplete Velo suggestions). 
1$w.onReady(function () {
2 $w('#incBtn').onClick(() => {
3  addToCount($widget.props.step);
4 });
5 $w('#decBtn').onClick(() => {
6  addToCount(-$widget.props.step);
7 });
8
9 render();
10});

Test Your Property in Preview Mode

  1. Click Preview to move to preview mode. 
  2. Click Test API Properties. 
3.  Change the step to a different number and see how your widget works. 

Add a Public Event to Your Widget API

The widget API allows you to add an event that is fired whenever you decide. 
Add an event that is fired when the "count" variable changes:
  1. Click the Widget API widget api icon to open the Widget API panel. 
  2. Click Add New Public Event in the Events section (or hover over the section and click the add icon that appears). 
  3. Name your event and describe it
4.  Add this line to your addToCount() function, to fire the event when the count changes. 
1$widget.fireEvent('change', count);
5.   Now, your addToCount() function should look like this: 
1function addToCount(amount) {
2 count += amount;
3 render();
4 $widget.fireEvent('change', count);
5}
Catch your event in the site editor
You'll need to catch your event in the site editor once you have installed your widget in your website (this will be describe in Step 8).

Add a Public Function to Your Widget API

Create and export a reset() function, so that site owners can easily set the count to 0. 
  1. Click the Widget API widget api icon to open the Widget API panel. 
  2. Click Add New Public Function in the Functions section (or hover over the section and click the add icon that appears). 
  3. A new empty function by the default name foo() is created, with a designated JSDoc (the comments block) that can be read by anyone who will use your function on a site. 
4.  Paste the following code instead of the function default code: 
1export function reset(){
2 //This function is part of my public API
3 count = 0;
4 render();
5}
5.  Update the JSDoc. Note: you must keep the function's annotation in this format.  
1/**
2*@function
3*@description Sets count to 0 and renders. 
4*@returns nothing
5*/
Tip
You can also go the other way around. Any exported function with the proper JSDoc above it, will appear in the Widget API panel on the right. So, you can write your code directly, instead of receiving the template through clicking Add New Public Function. 

Step 6 | (Optional) Configure Your Widget's Edit-Time Behavior

The Configuration tab allows you to determine the behavior of the widget and its elements when a site owner edits it in the editor.  Try out a few options in the Configuration tab.
Set a display name for your widget elements: 
  1. Select the decrement button.
  2. Change its display name under Component Name to "My Decrement" in the Inspector inspector panel.
Prevent the text element from being selectable in the editor: 
  1. Select the text element that represents your count. 
  2. Click the Can be selected option in the Behavior section of the Inspector inspector panel to remove the blue checkmark. 

Step 7 | (Optional) Create More Design Presets

Blocks allows you to create various variations for your widget's design and layout, through design presets. To create another design preset: 
  1. Click the Design tab in the top menu. 
  2. Click + Add Design Preset + in the Design Presets section of the Design pane under App Structure app structure..
  3. Click the ֿMore Actions icon   to rename your preset (you can also duplicate or delete it). 
4. Make some visible changes in your widget, like changing the color of the middle section.
Move back and forth between presets to see the differences.
Changes per preset versus global changes
Note that some design and layout changes impact only your current preset, while others impact all (learn more). 

Step 8 | Catch Your Event in the site editor

Important
This step takes place in the Wix Editor or Studio Editor, not in Blocks. 
Go to your site editor to catch the event from your app. First you need to register an Event Handler for the change event:
  1. Install your widget app. 
  2. Enable Developer Mode. 
  3. Click the Properties and Events  icon.
  4. Change the ID of your widget, for example, to "counter1".
  5. Click onChange( ) under Event Handlers.
  6. Select counter1_change in the box.
Now write the function. It gets the `count` as a parameter and resets the count when it gets to whatever number you decide (in our example: 30). Your function should look like this:
1export function counter1_change({data: count}) {
2 // This function was added from the Properties & Events panel. To learn more, visit http://wix.to/UcBnC-4
3 // Add your code for this event here: 
4 if (count > 30) {
5  $w('#counter1').reset();}
6}
Preview or publish to see your site in action.

Did this help?

|

In This Article

  • Step 1 | Create a new Widget in Blocks
  • Step 2 | Add a Layouter
  • Step 3 | Add Widget Elements
  • Adding the buttons
  • Adding the middle number
  • Changing the IDs
  • Step 4 | Add Code to Your Elements
  • Step 5 | Make Your Widget Customizable with Widget API
  • Define the "step" Property
  • Change Your Code to Consider Your New Property
  • Test Your Property in Preview Mode
  • Add a Public Event to Your Widget API
  • Add a Public Function to Your Widget API
  • Step 6 | (Optional) Configure Your Widget's Edit-Time Behavior
  • Step 7 | (Optional) Create More Design Presets
  • Step 8 | Catch Your Event in the site editor

Hire a Professional

Get matched with a Wix Partner who can help you reach your site goals.
Get Matched