Tutorial | Create a Countdown App Using Blocks

This tutorial shows you how to build a countdown widget, which counts down to a specific date. It also contains a registration widget where site visitors can register and receive an email notification the day before your event. You will also learn how to install your countdown widget on a site and explore all the key features of Blocks.

What you get in the template

To make things easier, we've created a template so that you can get started right away.

The template contains:

• A countdown widget. You need to complete its design and code its functions and properties.
• A registration widget which you need to complete and add to your countdown widget.
• Some public utilities that you can use to implement your widget's functionality.
• Some backend code that you can use to implement the functions of your email notification.

Get the template

Step 1 | Complete the Design of Your Widget

To build this widget, start with this template and edit it under your Wix account. The template has been left incomplete so that you can learn how to add elements to your widget.

The widget is designed with a grid so that you can easily align and place elements.

1. Open the template. 
2. Click Countdown under App Interface. 
3. Click Add Elements  in the top bar.
4. Select Text. Drag and drop a 48px Title box into your widget.
5. Click Edit Text and change the text to SS.
6. Change the text color to white and center the text using the Inspector . 
7. Select the text box and move it into the grid square above the SECONDS label using .
8. Resize it using .

Learn more about designing your widget

Step 2 | Add and Define Your Widget's API Properties

You can define an API for your widget, so that the site builder who installs the widget can interact with it through code. The API can contain properties, events and exported functions.

This widget uses two properties:

• endDate: Defines the end date when the countdown reaches zero. Using this property, site builders can change the end date so that the widget is customized for their site.
• emailId: Determines the email message that will be sent to users when they sign up for a notification.

Learn more about widget API properties

Give your widget elements an ID

First you need to give your widget's elements an ID so that you can easily refer to them in the code.

1. Click on the text box.
2. Give the text box an ID in the Properties & Events panel. In this example, the ID is secondsTxt. Note that the other elements have already been given IDs.

Define the "endDate" and "emailId" properties

1. Click the Widget Public API button.
2. Click Add New Property in the Properties section.
3. Enter the property name, endDate.
4. Select the property type. In this case, Date and Time (the date is displayed in US format mm/dd/yyyy).
5. Select a default value (the site builder will be able to change this when they install your widget in the editors).
6. Hover over Properties and click the icon that appears.
7. Create another property for the triggered email and call it emailId. This is a Text type property with no default value.

Step 3 | Add Code to Make Your Widget Work

To make your widget count down, you need to create a function in the code that calculates the remaining time until the end date. To do this, your template comes with some pre-installed utilities that you can find in the Public & Backend  menu. 

Blocks uses a new global variable, $widget and the property, $widget.props, that holds all the properties that you have defined for your widget.

Blocks also uses Velo autocomplete, so that you can write code more easily.

Learn more about the widget API

Change the code to consider your new function

1. Click on the Code menu.
2. In the code panel for Countdown create a function, updateTime(), so that your countdown widget will update the count. Your new function should look like this:

You also need to set an interval for how often the widget updates the remaining time.
To do this, add the following code in your onReady() function. This updates the widget every second.

Preview your widget and test its API properties

You are ready to preview your widget and its API properties.

1. Click Preview. Your widget should countdown every second to the end date.
2. Click Test API Properties. A panel appears with the default value you set earlier. 
3. Change the date to check if the widget responds and counts down to the new date.

Step 4 | Create and Code a Custom Panel

You can create a custom settings panel so that site builders can change the settings of your widget when they install it on a site. In this example, the custom settings panel allows the site builder to change the end date and define an email ID that determines which email will be sent to users when they register to receive notifications.

Learn more about panels

Create a custom panel

1. Click on the Custom Panels tab in the Editor Experience menu.
2. Click Create Panel.
3. Name your panel. In this example, use "My settings".
4. Click Create Panel.
5. Click + Add Element.
6. Select Text Input. This will be for the end date.
7. Click Properties & Events . Give your text input an ID - endDateInput.
8. Select the text element and click Settings.
9. Add the name "End Date" in the Field Title field.
10. Delete the text in the Default Text field.
11. Set the placeholder text to "End Date".
12. Add a text divider.
13. Click Settings. Add a title in the Section Title field. In this example, use "Triggered email".
14. Add another Text Input. Give your text input an ID - emailIdInput.
15. Select the text element and click Settings.
16. Add the name "Email ID" in the Field Title field.
17. Delete the text in the Default Text field.
18. Set the placeholder text to "Email ID".

The design of your custom panel is complete. Now you need to implement it by adding code.

Add code to your custom panel

You want your custom panel to display the current end date and email ID when it loads. The site builder uses the panel to change these values. You need to add code to the panel so that when these inputs change, it updates your widget.

Learn more about adding code to your custom panels.

To enable panel elements to interact with your widget and perform actions in the editor, you can use the Velo wix-widget module in your code.

To use the Widget API, import wixWidget from the wix-widget module.

Insert the following code before your onReady() function.

You want your widget to update when the values change, so you need to register an onChange event. You also need to add async to your onReady() function as you will be using some asynchronous functions.

Your onReady() function should look like this:

Click  Run or Preview to check your code

Step 5 | Configure Your Widget

Now that your panel is designed and coded, you need to configure your widget so that your panel connects to one of your widget's action bar buttons.

The Configuration tab within the Editor Experience Panel  enables you to control how your widget behaves when a site builder installs and customizes it on a site. You can give your widget and its elements display names, so that it is clear to site builders what your widget does. You can also make changes to the floating action bars that appear in the editors when site builders select elements in your widget.

Learn more about configuration.

Add your custom panel to your widget's floating action bar

1. Click the Editor Experience Panel icon .
2. Select Configuration. 
3. Select your countdown widget. A floating action bar appears.
4. Click Settings.
5. Click  Action Button Settings. The Main Action Settings panel appears.
6. Select My settings from the dropdown list to select your custom panel.

Step 6 | Add a Second (Inner) Widget and Implement the Registration Logic

The template comes with a second widget called Registration. You can find it under App Interface. 

When you click Layers you can see that it has been created as a multi-state box with three states. It has a button labeled Register, which changes to Submit when the site visitor clicks it. It also has a field box where site visitors can add their email address. A thank-you message appears when a site visitor has registered.

This widget also comes with a design preset which can be used for mobile view.

Learn more about design presets

Add your registration widget to the countdown widget

You're now ready to add your registration widget to your first widget, the countdown widget. In Blocks, you can create lots of different widgets and add them to other widgets. 

Learn more about working with widgets within widgets

1. Working in the Design tab, select your countdown widget.
2. Click More Options and select Add Widget.
3. Select Registration. Your inner widget appears in the middle of your countdown widget.
4. Drag and stretch your inner widget to fit the lower section of your countdown widget.
5. Change its ID to registration in Properties & Events .

Implement the registration logic in the main widget's code

You'll implement the code for user registration in the main widget (Countdown), using functions that are defined in the contactUtils.js and collectionUtils.js files.

The onSubmit() function creates or updates a contact using the wix-crm API via the createContact utility, then stores the subscription data in your app's collection. The function receives the user's email address from the registration form and updates the collection.

1. Create a new async function.
2. Call it onSubmit. It uses the create contact utility from contactUtils.js and the collection name helper from collectionUtils.js.

Your code should look like this:

Register for the onSubmit event

In your onReady(), after your updateTime() function, add the following code:

Step 7 | Release Your App and Give it a Namespace

Now you are ready to release your app for the first time. Your first release will be a major version. Later, when you are working on your app, you can choose a minor or major version. A minor version is updated automatically on all the sites where it appears. You just need to refresh the page. In a major version, the site builder needs to update your app manually. An indication appears next to the name of the app in the Installed Apps panel in the Editor. 

Learn more about versions in Blocks

When you click build for the first time, Blocks prompts you to give your app a namespace. This namespace is used to refer to your collection in Velo code in the editors and in the app’s code in Blocks.

Learn more about the app namespace

Your first release

1. Click Release.
2. Enter a namespace for your app and click Next.
3. Select Major Version and click Release.
4. You get a message that Version 1.0 is built. Click Got it to continue working on your app.

Step 8 | Add a Collection to Your Widget

Now you need to create a collection to store all of the subscriptions. Collections in Blocks are empty placeholders that you design in Blocks, which will be filled with data once the app is installed on a site. Learn more about collections in Blocks

The template has a pre-installed utility called getSubscriptionsCollectionName(), in collectionUtils.js under Public & Backend. It constructs the full name of the collection so that you don't have to add your full app namespace every time you refer to it in the code.

Configure your collection utility

To configure your collection utility:

1. Click collectionUtils.js under Public & Backend.

2. Add your app's namespace. Your code should look like this, with your own namespace:

   Copy

Create your collection

To create your collection:

1. Click CMS.
2. Click + Create collection.
3. Give your collection a meaningful name. In this example, use Subscriptions.
4. Click Create. 

Add fields to your collection

1. Click Add Item to add a field to your collection.
2. Enter Title, for example Subscription.
3. Click Add Field.
4. Select Date, click Choose Field Type.
5. Enter endDate in the Field Name field. This will be the last date up until which people can register.
6. Click Save.
7. Now click Add Field and create a Text type field and call it emailId for the triggered email.
8. Add another Text type field and call it contactId. This will store the contact details of registered users.
9. Now create a Boolean type field and call it notified. This ensures that subscribers will be notified only once.

Set permissions for your collection

You want any site visitor to be able to add content to your collection by subscribing. 

1. Click More Options for your collection from the CMS menu.
2. Select Permissions & Privacy. 
3. Select the dropdown menu Who can view this content?.
4. Select Anyone.
5. Click Save.

Step 9 | Install Your App on a Site in the Wix Editor

You can install your widget on any of the editors. The following example uses the Wix Editor. Before you install your app, you need to release your app a second time. This will be a major release, because you have created a collection.

1. After releasing your app, open your website.
2. Click Add apps . 
3. Click Custom Apps. A list of all your apps appears.
4. Select your app from the Available apps list.
5. Click Install App.
6. Click Add Elements .
7. Select My Widgets.
8. Double click your widget to add it to your site. 

Your widget is fluid and you can select its elements so that you can customize the widget to your site. You can also open the settings panel and change the default end date. 

Set an Email ID

Users can register for an email notification. You need to create the email that will be sent and get an ID for it so that the widget API can identify which email needs to be sent.

1. Open My Dashboard from the Site menu in the top bar.
2. Go to Triggered Emails in Developer Tools.
3. Click Get Started. 
4. Enter a subject.
5. Design the email using the editor tools.
6. Click Save & Continue.
7. Add the sender details, the From name and the Reply-to email, and click Save.
8. Click Got it.
9. Click Save & Publish again. You get a generated identification code that links to the email that you have designed so that it will be sent to anyone who registers. 
10. Enter this code in your custom panel in the Email ID field.

Use Backend Code in Wix Editor to Notify Subscribers

Backend code is included with your app in Blocks, but you need to invoke the notification in the editor.

Invoke your notify function

1. Click + New web module under Backend in Public & Backend in the Wix editor.
2. Call it backend.web.js.
3. Import the backend function in your site's code section under backend.wb.js.

Your code should look like this:

Now create an export function invokeNotify in backend.jsw in your site's code section.

Your code should look like this:

Now you need to create a scheduled job. The widget's frontend code only runs when someone is on the page. You need a backend process that runs even when no one is visiting to check who should be notified and send emails. A Scheduled Job is the built‑in way to do that.

1. Click Add in Backend
2. Click Add scheduled jobs. Add the following code under jobs.config in your site's code section. In this example, the notify function is invoked at 10 minutes past the hour, every hour.

Your code should look like this: