Fixed Position

Overview

A Fixed-Position Widget component is a regular widget that is fixed to the browser window, using the position property set to fixed.

A fixed-position widget retains its position when the page is scrolled, so it is always available for site visitors to interact with. Its position is placed relative to the viewport, and it is not part of the page layout, so the Wix user can’t resize or change its position by dragging it.

User Experience
  • Users can see your app in the App Market and then add it to their website.
  • Users will have to grant permission for your app once they add it.
  • The Fixed-Position Widget component will be added to all pages at the position you defined when you registered your app.
  • A Fixed-Position Widget component is added and customized by the user, but is used by the site visitors.
  • Deleting the app will revoke the app permission.
Architecture

A Fixed-Position Widget consists of two parts:

  • The Fixed-Position Widget iframe: The Fixed-Position Widget’s content is provided as an iframe embedded in a Wix website by the user, and is displayed in both the Wix Editor and the published website.
  • The App Settings iframe: The App Settings iframe allows users to register, customize, and configure the app for their website. The App Settings iframe is embedded in the Wix Editor and is used only by the user.
Link the App to a Site

When a user adds your app, we’ll generate a unique ID for your app in this specific site – the App Instance ID. Use the App Instance ID to link your app to this site.

This ID is sent you as part of the App Instance query parameter, which is a signed parameter that allows you to identify the website and the Wix user, and verify that the calling party is indeed Wix.

All of your app’s endpoints in this site will have the same App Instance ID, so each request sent to the widget endpoint and to the App Settings endpoint includes the same App Instance ID in the iframe URL.

App Settings

Use the App Settings panel in our UI-lib starter template as a base to create your App Settings panel.

Updating the App with the User’s Changes

When users change a setting in your app, update the app right away in the Wix Editor – but don’t change the app on the live site until the user publishes the site.

Here’s how:

  1. Store two sets of data. Store both the data that’s visible in the Wix Editor and settings panel, and the data in the live site.
  2. Update the app in the Wix Editor immediately. Show the app with these latest changes in the Wix Editor (including the App Settings panel). There are two ways to do this, depending on whether the user changed the color/font, or other values like numbers/text/booleans.
  3. Wait for the user to publish the site before updating the app in the live site. Listen for the SITE_PUBLISHED event in the addEventListener method. When SITE_PUBLISHED is issued, update the app in the live site.

Updating the Color & Font

For color and font settings, use our custom wix-param attribute in both the site component and in the App Settings panel.

When users change your app’s font or color, we’ll automatically update the app with these changes.   

Updating Numbers, Booleans, Text & Other Values

When users change your app’s settings (except the color & font), here’s how to update your app right away in the Wix Editor:

1. Detect changes that the user makes in the App Settings panel. Here’s what to do in the settings panel:

    • For Wix UI controls that use wix-param to save a number or boolean: listen for the STYLE_PARAMS_CHANGE event in the addEventListener method.
    • For Wix UI controls that don’t use wix-param: use the onChange or onClick function.

2. Update your database/backend server immediately. This is only relevant for UI controls that aren’t using wix-param. (If the UI control uses wix-param, the change is already saved in the Wix site – so there’s no need to update your server.)  

3. Show the changes in the app. For better user experience, don’t refresh your app. Here’s what to do instead:

    1. In the App Settings panel, use triggerSettingsUpdatedEvent to send an update event to the component.
    2. In the component itself, use addEventListener and listen for these events:
      1. SETTINGS_UPDATED event – for UI controls that don’t use wix-param
      2. STYLE_PARAMS_CHANGE – for UI controls that use wix-param
    3. Update the app with the new settings.
Support Multiple Copies of the App

Users can copy the fixed-position widget as many times as they want on their website.

Here’s what you should do:

  1. To distinguish between the widgets, use the compId parameter (a unique string that identifies the component, specified in the iframe query parameters).
  2. When a user copies the widget, make sure the copied widget has the same settings as the original widget. Use the originCompId query parameter to retrieve the original widget’s settings.
  3. Link each widget to its own settings, so that when a user changes the settings of one widget, it doesn’t affect other copies of the widget in the site:
    Use the getOrigCompId method to identify the widget that opened the App Settings panel. The method returns the compId of the widget, so you can open the right settings panel.
Copy App Content in Duplicated Sites

Users can duplicate their site, which means that apps should be added to the duplicated site with their existing content and settings (not the default data).

Here’s what you should do:

  1. Check if the app is being copied from another site. When your app endpoint is called, check if the instance parameter has an originInstanceId property. If it does, this means that the app is being copied from another site. The value of originInstanceId is the instanceId of the app in the original site.
  2. Copy the content and settings of each Site component. Get the correct settings of the original app using its instanceId (the originInstanceId property) together with the compId query parameter (a unique string that identifies the component, specified in the endpoint URL). The compId has the same value in both the duplicated and original sites.
Note:
In some cases, there may be content that shouldn’t be copied over between sites. Not sure if something should be copied? Talk to your account manager.
Widget Position

When a Fixed-Position Widget component is added by the user, it will be placed in the position you set when you registered your app. The user will be able to change the position of the app only if you provide this option from the App Settings. Use the dock UI control to automatically bind the fixed-position widget placement to the control in the App Settings.

Define your app’s default position in the Dev Center. You can place it in one of these areas of the website:

  • TOP_LEFT
  • TOP_CENTER
  • TOP_RIGHT
  • CENTER_RIGHT
  • CENTER_LEFT
  • BOTTOM_LEFT
  • BOTTOM_CENTER
  • BOTTOM_RIGHT

If you placed the widget in one of the four centered areas, you can set it to be relative to the center or fixed to the edge of the screen.

  • Vertical margin: This margin offsets the widget vertically from its center placement.
  • Horizontal margin: This margin offsets the widget horizontally from its center placement.

Once the component has been added to its default position, the user can control its position from the App Settings (if you provided that option).

Note: The app layout should fit all the positions you support, you may have more than one layout.

Examples

Set widget placement and margin (App Settings)

Get widget placement and margin (App Settings)

Placement change event (Editor, Widget)

Widget Size

You’ll set the default size for the fixed-position widget in the Dev Center, and users won’t be able to resize it in the Wix Editor.

Follow our UI/UX guidelines – we’ll show you how to decide your app’s default size, and how to create the right user experience when site visitors interact with your app.

For example, you can  resize the app when a site visitor interacts with it in the live site. Make sure to reset the widget back to the default size when the user switches back to Edit mode, or when the site visitors clicks out of your app.

Example

Resize widget

Iframe Query Parameters

Query parameters for the Widget iframe:

NameValueComments

Query parameters for the App Settings iframe:

NameValueComments

Was this page helpful?

What can we do to improve it?

What did you like about it?