Wix.Settings

addComponent

Allows users to install add-ons in your app, directly from the App Settings panel. Users are then directed to the page where the component was added.

Use this method for add-ons that aren’t added automatically when users install your app, or to allow users to add a page component again. Note that for page components, you need to first allow users to add your page component more than once.

Syntax:

Parameters:

WIDGET EXAMPLE

PAGE EXAMPLE

closeWindow

Closes the settings/modal endpoint.

Syntax:

Parameters:

Example:

getCurrentPageAnchors

Retrieves the anchors on the current page.

Syntax:

Parameters:

Value passed to callback:

An array of unordered objects. 

Each object represents an anchor on the current page, and contains the following properties:

Example:

getCurrentPageId

Returns the page ID of the current page.

Syntax:

Parameters:

Example:

getDashboardAppUrl

Retrieves the URL of your app’s Dashboard component within the user’s site (the URL is fully qualified). Use this URL to direct the user from the App Settings to your app’s Dashboard component.

To open your Dashboard as a modal in the Wix Editor, use Wix.Settings.openModal.

Syntax:

Parameters:

|Name |Type |Description|
|---|---|---| 
|callback (required)|Function|A callback function to receive the URL of the app in the dashboard|

Example:

getSiteInfo

Retrieves information about the host site in which the app is shown.

Syntax:

Parameters:

Value passed to callback:

json Object containing the site info:

Example:

getSiteMap

Returns all items in the site structure, including:

• Items in the site’s menu – pages (including subpages), links, and menu headers.
• Hidden pages – pages that are in the site, but not in the site menu. For example, a “Thank You” page that’s shown only after a site visitor makes a purchase.

Syntax:

Parameters:

Value passed to callback:

An array of objects, where each object represents an item in the site structure.

Each object contains data about the item. The data sent depends on the item – check out our examples below.

Here’s an example of an array passed to the callback:

Example:

getStateUrl

This method returns the full URL of one of your internal pages on the live site, including the app’s state.
For example: mysite.com/my-store-app/product1.
As you can see, the URL includes the app state.

Use this method if you have a page component and you need the URL of an internal page.

Syntax:

Parameters:

Example:

getWindowPlacement

Gets the position of a fixed position widget in an editing session. Read more about position placement in the Editor.

Syntax:

Parameters:

Example:

isApplicationInstalled

Allows you to check if another one of your apps is installed.

Syntax:

Parameters:

Value passed to callback:

A boolean indicating if the app is installed or not:

• true if the app is installed
• false if the app isn’t installed

Example:

isComponentInstalled

This method is for multicomponent apps. Use it to check if one of your app’s components is installed in the user’s site.

Syntax:

Parameters:

Value passed to callback:

A boolean indicating if the component is installed or not:

• true if the component is installed
• false if the component isn’t installed

Example:

isFullWidth

Indicates if the user extended the component to full width.

Syntax:

Parameters:

Value passed to callback:

A boolean indicating if the component is set to full-width:

• true if the component is set to full-width

• false if the component isn’t set to full-width

Example:

openBillingPage

Opens the Wix billing page from the settings panel in a modal window.

Syntax:

Example:

openLinkPanel

This method opens the Editor’s link settings panel, where users can add a link to content in your app (an image, text, etc.).

How to use this method:

1. Call this method when a user is adding a link in your app. Users will be able to link to an anchor on their site, an external link, and more.
2. Save the return object. This method returns a link data object – save the object on your database, without changing it in any way.
3. Use the return object to navigate to the link target. In the live site/preview, use the Wix.navigateTo method to navigate to the link target.
4. Use the return object the next time you call openLinkPanel. This will open the panel with the current link settings displayed.

Syntax:

Parameters:

Value passed to callback:

A link object with information about this link.

Here’s when to use the link object object:

• To navigate to the link target in the live site/preview (use the Wix.navigateTo method)
• The next time you open the link panel with the user’s settings.

Here’s an example of a link object for a page:

Example:

openMediaDialog

This method opens the Wix Media Manager, which allows users to choose an existing item from the Wix media galleries or upload a new file.

Once the user selects a media item, a callback function retrieves a metadata descriptor with details about it.

To access the media item, use one of the Wix.Utils.Media.get* methods to construct the item’s full URL. You’ll need the item’s relativeUri, which is returned in the callback function.

Syntax:

Parameters:

Value passed to onSuccess callback:

An object or an array of objects (for multiple media items).

Each object contains metadata about a specific media item.

Example:

openModal

Opens a lightbox-style modal window over the Wix editor. You can only open this modal from the settings endpoint.

Here’s how the modal works:

• The modal is a runtime widget, so it’s not part of the site structure.
• The modal is a singleton – every new modal closes the previous one.
• Users can close the modal by clicking the lightbox or pressing the close button. You can close the modal by calling Wix.Settings.closeWindow from within the modal iframe.

Syntax:

Breaking change for the openModal method

We’ve deprecated the bareUI parameter, which means that the modal now has a header, border, shadow, etc. If your app is using the bareUI parameter:

1. Remove bareUI from Wix.Settings.openModal.
2. Now that the modal style changed, we recommend adding a title and changing your design if needed.

Parameters:

Example:

openReviewInfo

Opens your app’s Reviews tab as a modal within the Wix Editor.

Syntax:

Example:

openSiteMembersSettingsDialog

Opens the settings for the Wix’s site members component, directly from your app. This method first closes all other open dialogs or panels in the editor.

This method is relevant for apps that require site visitors to log in as members of the site.

Syntax:

Example:

refreshApp

Reloads the app. Use this method when the user makes a change that affects the entire app – and it requires server-side rendering. For example, when the user connects an account.

Don’t use this method when:

• The change only affects one of your app’s components. In this case, use refreshAppByCompIds instead.
• The user made a small change in your app – like customized text. In this case, use the triggerSettingsUpdatedEvent instead.

This method accepts a single optional argument, an object. Each of the object’s properties will translate into a query parameter in the iframe URL.

Syntax:

Parameters:

Example:

refreshAppByCompIds

Reloads the component. Use this method when the user makes a change that requires server-side rendering, and this change only affects specific components.

Don’t use this method when:

• The change affects all of your app’s components. In this case, use refreshApp instead.
• The user made a small change in your app. In this case, use the triggerSettingsUpdatedEvent instead.

Syntax:

Parameters:

Example`

resizeComponent

Sets the width and/or height of a component, displaying it over other components in the page.

Syntax:

Parameters:

Example:

revalidateSession

Verifies that the session is secure. If the session is secure, this method retrieves a newly-signed app instance.

Use this method before displaying sensitive information or performing an action that requires a secure session.

Syntax:

Parameters:

Example:

setFullWidth

Sets the widget/page component to the full-width of the browser.

Syntax:

Parameters:

setWindowPlacement

Sets the placement for fixed position widgets in an editing session.

A position placement is a predefined set of locations where a popup will be placed. The position placement is defined under Wix.WindowPlacement and can have the following values:

1. Wix.WindowPlacement.TOP_LEFT
2. Wix.WindowPlacement.TOP_CENTER
3. Wix.WindowPlacement.TOP_RIGHT
4. Wix.WindowPlacement.CENTER_RIGHT
5. Wix.WindowPlacement.CENTER_LEFT
6. Wix.WindowPlacement.BOTTOM_LEFT
7. Wix.WindowPlacement.BOTTOM_CENTER
8. Wix.WindowPlacement.BOTTOM_RIGHT

Syntax:

Parameters:

Example:

triggerSettingsUpdatedEvent

Triggers a Wix.Events.SETTINGS_UPDATED event in a component iframe. It should be used in an editing session when a developer wants to reflect editing changes but avoid refresh/reload of the component’s iframe.

Syntax:

Parameters:

Example:

Deprecated

getSitePages

A page can be:

• An item in the site’s menu – a page, subpage, external link, link to a page anchor, or menu header.
• A hidden page/subpage – these pages are part of the site, but they’re not part of the site menu. For example, a “Thank You” page that’s shown only after a site visitor makes a purchase.

Parameters:

Value passed to callback:

An array of objects, where each object represents a page in the site.

The objects are ordered according to the site’s structure shown in the Pages menu of the Wix Editor. If a page has subpages, they are returned as an array of objects nested inside the page object.

Each page/subpage object contains the following properties:

Example:

getStyleParams

Retrieves the style parameters from the hosting Wix platform. The parameters includes colors numbers, booleans.

Parameters:

Example: