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


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


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

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

Show screenshot

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

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


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. 

Show screenshot

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

Copy
1

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

Copy
1

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).
Show screenshot

3.  Name your property "step", give it the type Number and a default value of 1

Show screenshot

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

Copy
1

Test Your Property in Preview Mode

  1. Click Preview to move to preview mode. 
  2. Click Test API Properties
Show screenshot

3.  Change the step to a different number and see how your widget works. 

Show screenshot

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
Show screenshot

4.  Add this line to your addToCount() function, to fire the event when the count changes. 

Copy
1

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

Copy
1

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

4.  Paste the following code instead of the function default code: 

Copy
1

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

Copy
1

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

Show screenshot

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

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


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). 
Show screenshot

4. Make some visible changes in your widget, like changing the color of the middle section.

Show screenshot

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

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:

Copy
1

Preview or publish to see your site in action.

Was this helpful?
Yes
No