Wix Blocks: App and Widget Installation Settings
7 min read
Wix Blocks is open to all Wix Studio users. To get access to Blocks, join Wix Studio.
When you create a Blocks app, it's important to determine what happens when a site-creator installs your app. How do you want your app and widgets to be added to the site? For example:
- Show all the widgets in a site's Add panel, or hide some of them?
- Add the app to a new page in the site?
- Does a widget appear on the site page automatically, or only when added manually?
- What default preset should show upon installation?
The answers to all of these questions depend on your specific app and can be customized in the Installation Settings.
Notes:
- 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-creator removes and reinstalls the app.
- Access to the installation settings can be found under the App menu in Wix Blocks. The options panel itself is in the Wix Developers Center dashboard.
- 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.
Options for adding your widgets
There are four options to choose from for adding each of your widgets to a Wix site.
For each widget, you also choose:
Not added automatically
This is the default setting for a site creator who installs your app.
With this option, your widget is:
- Not added to a page automatically.
- Shown in the Add Apps panel as available to install. If you do not want your widget to appear in the Add Apps panel (for example, if it is an inner widget), deselect this option.
With this option, for your Presets:
- The preset you define will apply to both desktop and mobile.
- By default, the first preset created for that widget is selected.
Added to current page
This option means that your widget is automatically added to the page the site creator is on, without having to drag and drop it from the add panel.
Consider using this option when you have a primary widget that you want to direct your users to.
With this option, your widget:
- Is added to the page the site creator is on.
Note: If a site creator installs your app from the Wix App Market, the installation will be on their site's homepage. - Is shown in the Add Elements panel as available to install. If you do not want your widget to appear in the Add Elements panel (for example, if it is an inner widget), deselect the Add panel checkbox in the Preset visibility section.
With this option, for your Presets:
- You can define one preset for desktop and one for mobile.
- By default, the first preset created for that widget is selected.
Notes:
- When you use the Add to current page option for one widget, you cannot use it for another widget on the same page. Only one widget per app can be configured in that way.
- If you change this option in an updated version of your app, users who already installed it won't get this update.
Added as a new page
Use this option when you want your widget to appear as a new, separate page in a website.
There are additional settings to consider when installing your widget using this option.
The additional settings are:
- Page Name: This will 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 (see note below).
- 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. One example of its use is an app creator who wants to add code to their app to navigate to this page. The app creator can use an element such as a button in a widget to take the user to this page. For this purpose, the code needs a unique ID to work properly.
With this installation option, your widget:
- Is added to a new page on the visitor's site.
- Is shown in the Add Elements panel. If you do not want your widget to appear there, deselect the Add panel checkbox in the Preset visibility section.
With this installation option, for your Presets:
- You can define one preset for desktop and one for mobile.
- By default, the first preset created for that widget is selected.
Added as a Lightbox
Use this option when you want your widget to appear as a lightbox. There are additional lightbox settings to consider when installing your widget using this option.
The additional Lightbox settings are:
- 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).
Note:
The Lightbox ID value becomes part of the URL for the new lightbox that this widget is installed on. This is so it can be used in code as a unique URL. One example of its use is if you want to add code to your app to navigate to this lightbox. You can use an element such as a button in a widget to take the user to this lightbox. For this purpose, the code needs a unique ID to work properly.
With this option, your widget:
- Is added to a new page on the visitor's site.
- Is also shown in the Add Elements panel. If you do not want your widget to appear there, deselect the Add panel checkbox in the Preset visibility section.
With this option, for your Presets:
- You can define one preset for desktop and one for mobile.
- By default, the first preset created for that widget is selected.
openLightbox()
To open the lightbox from the app code, use the wix-application openLightbox() function
Showing your widget in the Add panel and Design panel
When a site creator installs your app on a site, you might want them to install some widgets, and not install other widgets. For example, a common scenario is that an app has one main widget, and other inner widgets that are embedded in it. In this case, you want the site creator to install only the main widgets. All the others are already included, and will lead to confusion if they all appear in their "My Widgets" list in the Add Elements panel.
You can also make your widget's design presets available within the My Widgets list in the Add Elements panel in the Editor. To do so, select the Add panel checkbox in the Preset visibility section.
To make your widget's design presets available within the Design panel in the Editor, select the Design panel checkbox in the Preset visibility section.
Creating thumbnail images for your presets
When site creators browse through the design presets of your widget in their Add Elements or Design panels, they see a thumbnail image of the widget. Click Preset Settings to choose whether to use an auto-generated image or create your own.
Setting your widget's default preset
When you built your widget, it is likely that you used presets to set how the widget will appear on mobile as well as desktop. You may have several options for both environments. In this case, you can select your preferred option by enabling the Add a different preset for mobile toggle. By default, the first preset created for that widget is selected.
Notes:
- If you select this option, the desktop preset is the one that appears in the Add Elements panel.
- When a widget is auto installed, the mobile preset is installed in the mobile and tablet views.
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-creator removes and reinstalls the app.
Did this help?
|