Wix.Settings

addComponent

addComponent(options, onSuccess, [onFailure])

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 – here’s how.

Parameters:

NameTypeDescription 

closeWindow

closeWindow([options])

Closes the settings/modal endpoint.

Parameters:

NameType Description

Example:

getCurrentPageAnchors

getCurrentPageAnchors(callback)

Retrieves the anchors on the current page.

Parameters:

NameType Description

Value passed to callback:

An array of unordered objects. 

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

NameTypeDescription
Note:

If there are no anchors on the current page, returns just one default anchor – the top of the page.

Example:

getCurrentPageId

getCurrentPageId(callback)

Returns the page id of the current page.

Parameters:

NameTypeDescription

Example:

getDashboardAppUrl

getDashboardAppUrl(callback)

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.

Important:
To open your Dashboard component, add an href attribute with the Dashboard URL. Don’t use window.open – if you use window.open in a callback of an asynchronistic call, the browser blocks the window from opening.

Parameters:

NameTypeDescription 

Example:

getSiteInfo

getSiteInfo(callback) 

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

Parameters:

NameType Description

Value passed to callback:

JSON Object containing the site info:

NameTypeDescription 

Example:

 
getSiteMap

getSiteMap(callback)

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.
Note:
Use this method instead of getSitePages, which is now deprecated.

Parameters:

NameTypeDescription

Value passed to callback:

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

Warning:
To use this object later (for example, if you want to navigate to a link on the user’s site), save this object in your database as is – don’t change it in any way.

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

NameTypeDescription

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

Example:

getStateUrl

getStateUrl(sectionId, state, callback)

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

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.

Note:
This method won’t work if the user didn’t save the site since installing your app (you’ll get an error in the response).

Parameters:

NameTypeDescription

Example:


 

getWindowPlacement

getWindowPlacement(compId, callback)

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

Parameters:

NameTypeDescription

Example:

Note:
Use this for fixed-position widgets only – otherwise, an error will be thrown.
isApplicationInstalled

isApplicationInstalled(appDefinitionId, callback)

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

Parameters:

NameTypeDescription

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

isComponentInstalled(componentId, callback)

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

Parameters:

NameTypeDescription

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

isFullWidth(callback)

Indicates if the user extended the component to full width.

Parameters:

NameTypeDescription

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

openBillingPage( )

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

Example:

openLinkPanel

openLinkPanel([options], onSuccess, [onCancel])

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.
Note:
Want to learn more? To see how the link panel works inside the Wix Editor, check out this video.

Parameters:

NameTypeDescription

Value passed to callback:

A link object with information about this link.

Warning:
Save this object in your database as is – don’t change it in any way.

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

openMediaDialog(mediaType, multiSelect, onSuccess, [onCancel])

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.

 
Warning:
Use the Wix.Utils.Media.get* methods each time you access the media item, to prevent broken links.

Parameters:

NameTypeDescription

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

openModal(url, width, height, [title], [onClose])

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.

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:

NameTypeDescription

Example:

openReviewInfo

openReviewInfo( )

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

Example:

openSiteMembersSettingsDialog

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.

Example:

refreshApp

refreshApp([queryParams])

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.

Parameters:

NameTypeDescription

Example:

refreshAppByCompIds

refreshAppByCompIds(compIds, [queryParams])

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.

Parameters:

NameTypeDescription

Example:

resizeComponent

resizeComponent(options, onSuccess, [onFailure])

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

Parameters

NameTypeDescription

Example:

revalidateSession

revalidateSession(onSuccess, [onFailure])

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.

Parameters:

NameTypeDescription

Example:

setFullWidth

setFullWidth(fullWidth, [options], onSuccess, [onFailure])

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

Parameters:

NameTypeDescription

setWindowPlacement

setWindowPlacement(compId, placement, [verticalMargin], [horizontalMargin])

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

Parameters:

NameTypeDescription

Example:

triggerSettingsUpdatedEvent

triggerSettingsUpdatedEvent(message, [compId])

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.

Parameters:

NameTypeDescription

Example:

Deprecated

getSitePages

Note:
Now that this method is deprecated, use the getSiteMap method instead.

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:

NameTypeDescription

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:

NameTypeDescription

Example:

 

 

getStyleParams

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

Parameters:

NameTypeDescription

Example:

 

 

Was this page helpful?

What can we do to improve it?

What did you like about it?