Develop a Business Solution Item Page with Blocks

When you build a business solution on top of the Wix eCommerce platform, you need at least one page in your app that exposes eCommerce functionality and allows site visitors to make purchases. This is known as an item page.

When a site owner installs your app on their site, any item pages you create are included in the installation and displayed to site visitors on the site. An item page displays information about your item, including images. It uses the Wix eCommerce frontend API to allow site visitors to view their cart and navigate to checkout from the item page.

An example of an item page is the Wix Stores product page. This page lets a customer on a site view details about a product, and updates the customer’s cart or navigates to checkout when the customer clicks certain buttons. The product page is installed automatically whenever a user adds Wix Stores to their site.

This article explains how to create an item page in Blocks as part of your business solution.

Before you begin

Before getting started, make sure that you:

Step 1 | Design a site widget in Blocks

  1. In the Custom Apps page, select the app you want to add the item page to and go to Extensions.

  2. Click + Create Extension and in the modal that appears, search for the Widget extension labeled Wix Blocks.

  3. Click + Create on Blocks. This opens the widget extension in a new page on Wix Blocks.

  4. Use the Blocks Editor to design your widget to match your app’s needs. For example, if you want to create an item page that displays all available items on a site, you can add a repeater element. Or, you can combine basic elements like buttons and images to create a product page similar to Wix Stores’.

  5. Connect your item catalog to the widget. If you’re hosting the catalog externally, fetch the data from the external service to populate the widget.

Alternatively, create a collection in Blocks to act as the catalog.

This completes the design of your site widget.

Step 2 | Add code to the widget to support eCommerce functionality

At a minimum, your item page code should do the following:

We’ll show you an example of some basic code that does this below. To add code to your item page in Blocks:

  1. At the bottom of the Blocks Editor, open the code section for your widget.

  2. At the top of the code section, add the following import statements:

    Copy

    These lines import 2 modules that are necessary for your item page:

    • The currentCart module from the Wix eCom backend API. This module lets you update the current cart on a site and create the checkout.

    • The Wix eCom frontend API: This API lets you update the cart UI and navigate to the cart or checkout page.

  3. Call addToCurrentCart() to add an item to the current site visitor’s cart. As part of the method arguments, pass it an object containing a reference to your item catalog. Here’s an example of what that looks like:

    Copy

    The important part of this function is the catalogReferenceObject that is passed to addToCurrentCart(). Whenever your code uses the Wix eCommerce flow, you need to pass the eCommerce platform a catalog reference so it can retrieve the item information. The code above uses hard-coded values as an example, but normally you collect these values dynamically. For example, you might retrieve values from a repeater item.

    The object contains 3 required parameters:

    • The appId is the ID of your custom app. You can find this in your app’s dashboard page. The app ID tells the eCommerce platform which app it’s working with, so it can look up the URI of your catalog implementation.

    • The catalogItemId tells Wix eCom which item in the catalog to request information for. The ID can take any format you choose, as long as it matches an ID in your item catalog.

    • quantity indicates the requested number of items.

    Include an optional options parameter to request information for different variants of an item. For example, if an item can come in different sizes and colors, your catalog reference might look something like this:

    Copy

  4. Add a clickable element such as an Add to cart button, and call addToCurrentCart() in the element’s onClick() handler.

    Inside the provided onReady() function, add logic that navigates customers to the checkout or cart pages using the eCom frontend API. For example, if your widget contains a View Cart button, call navigateToCartPage() when it’s clicked.

    Before navigating to the cart view, make sure to call the refreshCart() function. This function updates the cart UI with the latest data, and ensures that all items selected by the customer appear in the cart view.

    Here’s an example of logic that adds an item to the cart and then navigates to the cart page:

    Copy

Here’s a complete example:

Copy

Use this code as a starting point for your own logic. Here are a few suggestions for building upon the example code:

  • Add a Buy Now button to your widget and implement a flow to take the customer directly to the checkout page. A "Buy now" flow skips the cart view, so you don’t need to call refreshCart(). When a customer clicks the Buy Now button, create a checkout directly to get a checkout ID, then pass that ID to navigateToCheckoutPage().

You now have a fully functional site widget.

Step 3 | Add your widget to a site page extension

You want your item page to be added automatically to a site whenever a user installs your app. To make sure this happens, do the following steps:

  1. In the Wix Blocks editor, go to the Wix Blocks menu in the top left corner and select Dashboard. This opens your app dashboard.

  2. In your app dashboard, go to the Extensions page.

  3. Click + Create Extension. In the modal that opens, select the Site Page extension.

  4. Give your page a name and ID. The name is visible to users on a site. The ID is not visible to users and is used to refer to the page in code. Configure the other settings as necessary.

  5. Under Add widgets to this page, click + Add Widgets and select the site widget you created in the previous steps. Click Save to save the site page extension.

  6. Return to the home page of your app dashboard. Under Building your app, click Installation settings > Manage Settings.

  7. Under Installation, select Added to a site page and make sure your widget is added to a page. Select the site page extension you created.

Finish configuring the remaining settings and click Save.

Now, when a user installs your app, the site page extension with the widget you created will be added automatically to the site.

Step 4 | Test your item page on a site

Now that you have a complete item page with code, you can test it on a site to make sure it works. We recommend installing and testing on a premium test site.

  1. Return to your app in the app dashboard.

  2. Click Test App > Editor.

  3. Select a site to install and test the app on. Wix takes you to the selected test site. Click Add to Site to add your app and agree to the terms of use. This adds the app, along with the item page, to your site.

  4. Publish your site and go to your item page. Test your widget by clicking on various buttons. Make sure that it navigates to the correct pages, and that the cart updates appropriately.

See also

Did this help?