Configure Blocks Installation Settings

Editor compatibility

Wix Blocks apps aren't supported in the Wix Harmony editor. Existing Blocks apps remain available for purchase on the Wix App Market for Wix Editor and Wix Studio sites. To learn more, see About Wix Harmony and Blocks.

The widget installation settings let you configure what happens when a site builder installs your app. For example, should all widgets be visible in a site's Add panel? Should any of them be added automatically to a site? What will be the default preset?

Important:
  • Installation settings apply only for the first install on a site. This means that in any further update, the settings won't be updated unless the user removes and reinstalls the app. 
  • The installation settings you apply for your Wix Blocks App are specific to a version of the app. The best practice is to test your app on a site, before releasing a new version.

Access Installation Settings

There are two ways to access your widget's installation settings. First, make sure your widget is selected in the App Interface in Blocks.

Method 1: From the WixBlocks Menu

  1. Click the WixBlocks menu.
  2. Click Dashboard to open the app dashboard.
  3. In the app dashboard, click Installation Settings and then select Manage Settings.
  4. To switch to another widget, return to the Extensions page in the app dashboard and select the widget you wish to manage.

Method 2: From the Editor Experience

  1. Hover over the widget name in the App Interface.
  2. Click the three dots and select Editor Experience > Edit Installation Settings.
  3. Hover over the widget name.
  4. To switch to another widget, select a different widget and repeat the process.

Configure how your widget is added

There are several options for adding each of your widgets to a Wix site.

Not added automatically

This is the default setting for Installation Settings. With this option, your widget is:

  • Not added to a page automatically.
  • Shown in the Add + panel as available to install on a site. If you do not want your widget to appear in the Add + panel (for example, if it is an nested widget), deselect this option in the Preset Images in Add Panel section.

In this example, the app has two widgets, both are defined as Not added automatically, and therefore seen in the Add+ panel. 

Added to the site homepage

This option means that your widget is automatically added to the homepage of a site, without having to drag and drop it from the Add + panel.

You can also set the default preset for your widget and define a different default preset for mobile. 

Added to a site page

Use this option when you want your widget to appear on a different Site Page Extension of your app. A site page extension means that whenever your app is installed of a site, another page comes with it.

To add the widget to a page extension:

  1. Select the site page extension to add your widget to.
  2. If you want to add the widget to a new site page extension, (meaning that you want to create this extension now), provide the following information: 
    • Page Name: Create a name to appear in the site menu.
    • Page ID: This will be used to refer to this page in code, and will also become the default page URL slug. The Page ID is filled in automatically based on the page name, but you can edit it. It cannot be changed once it has been saved.
  3. Set the default preset for your widget. If you want a different preset for mobile, select it.  
  4. Set how the widget appears on the page:
    • Original size: This option is selected by default. Your widget appears at the size it was created.
    • Stretched: Select this option to stretch the widget to fill the page.

Note: The Page ID value becomes part of the URL for the new page that this widget is installed on. This is so it can be used in code as a unique URL. You'll use this if you want to navigate to the page from your app.

Added to a site page as a popup

Use this option when you want your widget to appear as a popup.

Note: The terms popup and lightbox refer to the same element. While the editor and dashboard now refer to it as a popup, the API methods continue to use the term lightbox for backward compatibility. The documentation uses both terms accordingly.

To add the widget as a popup:

  1. Click Added to site page.
  2. Click + Select popup extension.
  3. If you want to add the widget to an existing popup extension, select the name of your popup.
  4. Or, if you want to create a new popup, provide the following information:
    • Popup name: This will appear in the site menu.
    • Popup ID: This is used to refer to this popup in code, and also becomes the default page URL slug. It is filled in automatically based on the popup name, but you can edit it. It cannot be changed once it has been saved (see note below).
  5. Set the default preset for your widget. If you want a different preset for mobile, select it.

Note: The Page ID value becomes part of the URL for the popup this widget is installed on. This is so it can be used in code as a unique URL. You'll use this if you want to navigate to the popup from your app.

openLightbox() To open the popup from the app code, use the wix-application openLightbox() function.

Configure preset images and visibility

The preset images section lets you define what widgets and presets appear in a user's Add +   and Preset panels.

Shown in Add Panel

Control the widgets users see in their App Widgets list in the Add + panel. For example, if you have inner widgets that are already included within another widget, you'll need to hide them from the Add panel. You can define Add panel visibility for each design preset separately.  

See an Add panel with two widgets

Add panel

See an Add panel with one widget and three presets

add panel

Shown in Preset Panel

The Preset panel is where users can choose between the various presets of a widget. This option lets you determine which presets should appear in the Change Preset panel. 

See a Preset panel

Change Preset panel

Choose image

When users browse through the design presets of your widget in their Add or Preset panels, they see a thumbnail image of the presets. We recommend that you upload your own images, to make sure that they represent the design and functionality of your widgets. If you started building from a Blocks template, this is crucial, or else your thumbnail images will be the template's images.

Click Choose Image to upload your images. Make sure to follow our UX guidelines for these images. 

Select Use a different preset for mobile if you want a different preset to show on users' mobile view.

Configure widget as essential to your app

Set a widget as essential to your app if it is a main widget and your app has no meaning without it. 

Note that you can set a widget as essential only if you add it to a page or a page as a popup. You cannot set it as essential if you add it automatically or to your homepage. 

With this toggle on:

  • Your widget cannot be deleted. Deleting the widget will un-install the app from your site. 
  • Your widget cannot be duplicated. A user can't add it twice from the Add + panel, and cannot copy and paste it. 

Reminder Installation settings only apply for the first install on a site. This means that if your app is already installed on a site, the settings won't be updated unless the user removes and reinstalls the app.

Did this help?