Tutorial | Create a Recipes App Using Blocks

This tutorial walks you through building the Recipes app. The app showcases recipes on Wix sites, so site visitors can see an image, description and rating for each recipe. They can also subscribe to get new recipes.  

The app includes:

• Two widgets - Recipes and Subscribe.
• A custom settings panel. 
• A collection for holding the recipes data. 
• A Dashboard page for allowing builders to interact with data in the app. 

Ready to begin? Create your own copy of the app in Blocks. The link leads to a template with most of the design and some of the code ready. 

Step 1 | Create a new Design Preset

Design Presets are Block's way of allowing you to have multiple design and layouts for the same widget. They are often used for adapting the app for different devices, like desktop and mobile. The first thing we'll do is create another preset for when the widget is used on a mobile phone. This preset will be a duplicate Card Layout preset, with a few changes. 

1. In case you missed this first step: click this link to create your own copy of the app.
2. Name your app: go to the top bar and click on the  icon next to the app's temporary name. 
3. Go to the Design Presets menu. The app template already has 3 presets and you'll create a new one now. 
4. Duplicate the Card Layout preset (to do this, hover, then click the  icon). 
5. Rename the new preset to Mobile Layout and make sure it is selected. 
6. Go to the Layout  menu of your widget. 
7. Change the widget's width to 320px.
8. Select your widget's first grid row. Change the first grid row height to 150px.

8.  Click the Design tab. 

9.  Change the title's font site to 18.

10.  Click on the Description, click  and set it to Don't Display, to hide the description in mobile.

11.  Go back to the Card Layout preset and check that the description does appear there.

Step 2 | Build the app

Build the app, to create an initial version of it, which you can install on a site. You'll build the app several times during this tutorial. 

1. Click Build on the top right.
2. You will be prompted to create a namespace first. Your namespace allows your app to interact with data collections and code files in its code.  
3. Build a test version.

Step 3 | Install the app on a site and test it

This steps creates a new Wix site and installs the app on it. Note that installing the app is not enough, you also must add the appropriate widget from the Add  panel. 

1. In another browser tab, create a new Wix site, or Wix Studio site (you can use wix.new or wixstudio.new).  
2. Install the app’s test version on that site: click the App Market icon  -> Custom Apps and find your app in the Available Apps. 
3. The App Widgets section of the Add  panel opens. Click or drag the Recipes widget to add it to your site. There is no need to add the Subscribe widget to the site. 

Now let's do some actions on this widget in the site, just to see how it works.

1. Click the Stretch icon to stretch your widget in the site section. 
2. Go to your desktop   view and change your preset. 
3. Go to your mobile  view and change your preset again to the Mobile Layout preset. 

4.  Right Click on the widget and click Reset Widget, to go back to the original design. 

Step 4 | Add the recipes collection in Blocks

Now, go back to Blocks to continue creating the app.

1. Go back to Blocks.
2. Click the Databases  icon.
3. Create a collection called recipes.
4. Add the following fields (make sure that the names are exactly the same, no caps):
   • image type Image
   • description type Text
   • duration type Text
   • rating type Number
5.  Go to our demo site, search for the words "Collection data" and save the data file to your computer. 
6. Import the data to your collection

7. Copy the collection ID

8. Go to collectionUtils.js file in the Public and Backend  files. This is the file for interacting with the app's collection. 

9. Change the value of collectionName from '@wixBlocks/recipes-app/recipes' to your collection ID.

Step 5 | Add logic to the Recipes widget

This step populates the repeater with the data from the collection, using code. 

1. Click Widgets and Design  to go back to the Recipes widget.
2. Paste the following snippet in your widget code. 

1. Create an initRepeater() function. For now, create the repeater to show 4 items. We'll changes this later. 

1. Await the initRepeater() function in your widget's onReady() function.

This is the full widget code at the moment: 

Step 6 | Create the Recipes widget API

In the previous step we defined the repeater to show 4 items from the database. But what if a site builder who installed your app wants to show a different number of items? Let's add a property to the Recipes widget API. The property will hold the number of items to display in the widget, and will replace the constant number of 4 that we added in the previous step. 

1. Click the Widget API  icon, on the right of your widget's code area. 
2. Click Add New Property
3. Name your property itemsToDisplay and give it a display name (such as: "Items to Display", which is more readable).
4. Give it a type of number and a default value of 3. 

5.  Make the populateRepeater function call send the prop as a parameter instead of the 4.

The onPropsChanged() function is triggered when an event of props changing is detected. You can add custom logic to this function.

6.  Await the initRepeater() function in your onPropsChanged() function:  

Here is the full widget code, after adding the property. 

Step 7 | The "My Settings" panel

When a site builder installs your widget, they can change the value of the properties with an autogenerated Settings panel in your widget's floating menu. However, you can also build a custom panel and add custom logic to it. 

1. Go to your custom panel in the Panels tab. The app has a custom panel names My Settings. Look at the code tab. The code gets the property and sets a slider's value accordingly. 
2. Add an onChange() function inside the onReady(), so that when the property is changed by the slider, the function notifies the panel to set the widget props again. 

This is the full panel code: 

Step 8 | Make configuration changes

The Configuration tab in the Editor Experience  panel allows you to control the editor experience of a site builder who installs your app. 

1. Click Editor Experience .
2. Go to the Configuration tab. 
3. Click the gray part of the widget, to edit the action bar of the Recipes widget. 
4. Click the Settings button.
5. Click Action Button Settings and connect it to the My Settings panel. 

Now, whenever a site builder clicks "Settings", they will see your custom panel. 

Another change you can do in the Configuration tab, is prevent layout elements from being selected. A site builder has no reason to select the repeater in your widget. 

4. Select the repeater and uncheck Element can be selected box. 

Step 9 | Check the app on your site

Let's check that the app works on your site. 

1. Build a test version of your app in Blocks.
2. Go to your Wix editor. Wait to see that the version updated automatically in the Custom Apps panel.  

Now let's add data to the collection in the site, to check the app functionality. You need to add data because when a Blocks app is installed on a site, the collection structure is copied to the site, but not the data  (learn more). 

3.  Go to the CMS  and add the CMS to your site. 

4. Find your collection. 

5. Click on the collection name and open it. See that the default data from Blocks was imported.

6.  Click on your widget's Settings button and change the number of items to display. 

7.  Go to preview and see that the number of items changed. If it did, your test is complete! 

Step 10 | Add the Subscription widget

Blocks allows you to create another widget and insert it inside the main widget. For example, let's say that you want to allow people to subscribe to an email list through your Recipes app. To this, we created another widget, named Subscription. However, this is just a dummy widget for the purpose of this tutorial - we didn't implement the code. This is how you add the Subscription widget to your Recipes widget: 

1. Go to Blocks. 
2. Open the Add  panel.
3. Click My Widgets. Here you can see all the widgets and their presets. Scroll until the end of the list. 

4. Drag the Subscribe widget to be on the top part of your Recipes widget.

Step 11 | Make layout changes

Let's make some layout changes to adapt the Subscribe widget to the Recipes widget. 

1. Click the Subscribe widget (make sure that you select the entire widget and not any internal element). 
2. Go the Layout  tab of the Inspector . 
3. Change the margins to 42px on the top and left. 

5. Right click on the Subscribe widget and select Use on All Presets. Now your layout changes apply to all presets.

Let's make some more changes in the mobile preset. 

1.  Go back to the Design Presets section of Widgets and Design  and click your Mobile Layout preset.

2.  In the inspector, change the Width to 86%.

3.  Align to center - both vertically and horizontally. 

Step 12 | Create a Blocks Dashboard Page

Now we want an easy way for users to interact with the collection of recipes, so they can add and manage their recipes. For this, we have the app's Dashboard (learn more). When a site builder installs your app on a site, the Dashboard page will be added with it.  

1. Go to your app's Dashboard page. 

1. Let's look at the Dashboard page. The Dashboard is made out of a large multi-state box (you can see this easily in the Layers  panel).  The multi-state box has two states, one to manage all the recipes and one to manage individual recipes. You can click on each state and see the difference between them. 

1. Look at the recipes state. It has two buttons:
   • Add Recipe: changes the state of the multi-state box to the form state.
   • Manage Collection: navigates to the CMS page in the Dashboard.
2. Look at the Dashboard's code tab to see the buttons' code: 

1. Look at the form state. I has two buttons: 
   • Cancel cleans the form
   • Save uploads the image and updates the repeater.

4. Look at the Dashboard's code tab to see the buttons' code: 

5. In the Dashboard page, go to Preview and try adding another recipe.

Step 13 | Connect the dashboard to an action button

1. Go back to the Recipes widget. 
2. Go to the Configuration tab. 
3. Click the secondary action button, which is Change Design. 
4. Click Action Button Settings. 
5. Set the button to open a Dashboard instead of a panel. 
6. Set the main action button text to Manage Recipes instead of Change Design. 

Now that we finished building our app, it's time to build a major version (learn more about versions in Blocks).

7.  Click Build and select Major Version.

Step 14 | Check the app on your site again

1. Go to your site's editor and update the app's version. 

2.  Open the sites' dashboard.

3.  You'll see new dashboard page with your app's name. Click on it. 

4.  Click Add Recipe and add  an item in the dashboard.

5.  Click Manage Collection. Open the collection and view the item you just added.

6.  You can also go back to the site editor and change the number of items again. 

Step 15 | Installation settings

Blocks installation settings determine how this app is installed for other people's websites. 

1. Go back to Blocks. 
2. Click WixBlocks -> App.
3. Click Installation Settings. A Wix Developers page opens for setting how your app is installed on sites. 
4. Click the Subscribe widget.
5. Set it as Not added automatically (to a site's Add  panel). This is because people will install the main widget and get the inner widget in it. 

6.  Click the Recipes widget. Set it to be Added to current page.

7.  As a default preset, choose the Editorial Layout.

8.  Choose the Mobile Layout preset to be the default for mobile. 

9.  Click Save.

10. Go back to Blocks and click Build again to apply the installation settings. 

11. To see the installation settings in action, you need to uninstall and reinstall the app. 

Step 16 | Publish your app in the Wix App Market

Blocks apps can be used on your own sites and save you lots of copy-and-paste. They can also be published and sold in the Wix App market and earn money. The last thing we'll do is simulate how to publish your app, in case you want to publish your own app in the future.  

1. Click WixBlocks -> App.
2. Click Publish App. This takes you to Wix Developers. 
3. Click Pricing. Create a Premium plan and decide on its pricing. 
4. Build your app in Blocks again. 

Now your app has a premium plan. The next step is to configure what happens in Blocks according to the different plans that a user purchased. What extra abilities do you want them to have? For example, in our app, we might want the subscribing option to be disabled until a user paid. Learn more about adapting your app to a pricing plan.