Configure Blocks Installation Settings
When you create a Blocks app, it's important to determine what happens when a site-builder installs your app. How do you want your app and widgets to be added to the site? 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?
Notes:
- 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 site-builder 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 use a test version when you apply different installation options, before releasing a new version.
To access the installation settings:
- Click the WixBlocks menu.
- Click App -> Installation Settings.
- This takes you to the Wix Dev Center to define the settings.
See screenshot
Options for adding your widgets
There are four options to choose from 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:
- Select the site page extension to add your widget to.
- 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.
- Set the default preset for your widget. If you want a different preset for mobile, select it.
- 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 as a Lightbox
Use this option when you want your widget to appear as a Lightbox.
To add the widget as a Lightbox:
- Click + Add new lightbox
- 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).
- 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
The preset visibility section lets you define what widgets and presets appear in a site-builder's Add+ and Design panels.
Add panel visibility
When a site builder installs your app on a site, you might want to control the widgets that they see in their My Widgets list in the Add + panel. For example, when you have inner widgets that are already included within another widget. This option applies only if your widget is not added automatically to a page.
See Add panel with two widgets
Similarly, you might also want only some of the design presets to appear, while others shouldn't appear there. This option in all cases, meaning also when your widget is added to a page or a lightbox.
See Add panel with one widget and three presets
Design panel visibility
The Design panel is where a site builder can choose between the various presets of a widget. This option lets you determine which presets should appear in the design panel.
See Design panel
Creating thumbnail images for your presets
When site builders browse through the design presets of your widget in their Add + or Design panels, they see a thumbnail image of the presets. Click Preset Settings to choose whether to use an auto-generated image or create your own. Make sure follow our UX guidelines for the thumbnail 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 extension - not if you add it automatically, to the homepage or as a lightbox.
With this toggle on:
- Your widget cannot be deleted. Deleting the widget will un-install the app from your site.
- You widget cannot be duplicated. A site builder 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 site-builder removes and reinstalls the app.