Tutorial | Create a Counter Widget Using Blocks

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. 

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  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  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  icon in the Inspector panel  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 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  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.  Go to the bottom part of your screen to add code to your widget. 

2.  Add the following code before your onReady() function.

3.  Add the following code in your onReady() function. 

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  icon to open the Widget API panel.
2. Click Add New Property in the Properties section (or hover over the section and click the  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). 

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

5.   Now, your addToCount() function should look like this: 

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  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  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: 

5.  Update the JSDoc. Note: you must keep the function's annotation in this format.  

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

The Configuration tab within the Editor Experience Panel  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  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  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 Widget and Design  panel . 
2. Go to the Design Presets section.
3. Click + Add Design Preset + .
4. 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.

Step 8 | Catch Your Event in the site editor

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:

Preview or publish to see your site in action.