Configure Blocks Installation Settings

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. It is best practice to test your app on a site, before releasing a new version.

Important Content

Manage installation settings 

Open your App Dashboard to manage your installation settings:

  1. Click the WixBlocks menu.
  2. Click Dashboard. This opens your App Dashboard. 
  3. Click Installation Settings -> Manage Settings.

To move to a different widget, go back to the Extensions page and select the desired widget.

Options for adding your widgets

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 inner widget), deselect this option in the Preset Visibility section of your Installation Settings.

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 Lightbox

This is another sub-option of adding a widget to a site page. Use this option when you want your widget to appear as a Lightbox. 

To add the widget as a Lightbox:

  1. Click Added to site page.
  2. Click + Add new Lightbox, or select an existing Lightbox.
  3. Provide the following information for your Lightbox:
    •  Lightbox name: This will appear in the site menu.
    • Lightbox ID: This is used to refer to this Lightbox in code, and also becomes the default page URL slug. It is filled in automatically based on the Lightbox name, but you can edit it. It cannot be changed once it has been saved (see note below).
  4. 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 lightbox 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 lightbox from your app.

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

Preset visibility and images

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

See an Add panel with one widget and three presets

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

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. 

Set 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 Lightbox. 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?