Create Element Settings

Your element can include settings that the user configures when including it on a web page. You create these settings as property keys in the manifest.json file. When a user interacts with your element in the editor (in most cases by clicking on it), Weebly generates an interface that allows the user to update the settings.

Properties Structure

Properties are one of the child objects to Elements, and are the objects that hold the settings information. Every setting property must belong to a parent group property. A group is used to structure the UI dialogs that we will provide to users for updating settings for your elements. Members of a group are displayed together on the dialog page, using the group's name as the heading for that section.

For example, in the Price Chart sample element, the Table Settings group holds the plans and features settings, the button position, and the text alignment. The Advanced group holds the currency and color settings.

Settings that rely on a selection (like Sign Up Button and all the advanced settings, above) take the user to another page in the dialog. You can also nest groups to create another page.

Create a Group

To create a group, set the following:

nameThe internal name of your group. This name will be used to access the group from within your element code.

labelThe visible label for the group. This will be presented to users as the group heading in the settings dialog.

typeSet to group.

propertiesCreate the array of settings for your element.

Create a group

Setting Properties

To create the element's setting properties, you define the following:

nameThe internal name of your setting. This name will be used to access the setting from within your element code.

labelThe visible label for the setting. This will be presented to users in the settings dialogs.

typeThe type of the setting. This dictates how the setting will appear in the UI, and what validations can be applied to it. See Setting Types, below, for allowed options.

defaultThe default value for this setting.Tip: Use " " for null.

hiddenWhether or not the setting should appear in generated interfaces (default is false). Setting this to true will cause the auto-generated UI to not show this setting. If you set this to true, you must supply a default value.

Note: If you want to have all of your settings managed via an external URL (see below), you can set hidden to true on all settings. When the dialog appears to edit settings, it will simply contain a button to open the iframe.

privateWhen set to true, the setting is not available to the published site (default is false). In some cases, settings may contain private information (such as API Keys). This ensure that the data is not available to visitors of the site, and can only be used within the editor.

tooltipA string that displays when the user hovers over the setting in the modal. Max length is 100 characters. No HTML is allowed.

Setting Types

Each setting must specify one of the following types. Each type creates a specific Weebly element in the dialog. Some types allow additional data.

stringA single-line text input. You may specify both min and max properties to indicate minimum and maximum string length.

textA multi-line text input. You may specify both min and max properties to indicate minimum and maximum string length.

intA single-line text input, validated to allow only numeric input. You may specify both min and max properties to indicate minimum and maximum values. You may also specify a step property, which will add "Stepper" buttons, and auto-round any input to an appropriate step value. Default, step, min, and max properties are all integers.

sliderA slider selection. You may specify both min and max properties to indicate minimum and maximum values. You may also specify a step property, which will cause the slider to move in steps of that size. Default, step, min, and max properties are all integers.

toggleA toggle selection of on/off. The value will be returned as a boolean true/false, respectively.

radioA radio group selection. You must specify a values array. This array can either be a simple array of strings as values, or an array of objects that provide both name and value properties.

selectA separate dialog page that allows the user to select an option. You must specify a values array. This array can either be a simple array of strings as values, or an array of objects that provide both name and value properties.

colorA color picker input.

alignA series of buttons, indicating left, center, and right.

groupDon't use for settings - use only when creating a group.

Create properties

External Settings

If your application or element requires external data, or you feel that your customized settings panel will provide a better experience for users, you can provide some configuration options in an iframe that allows users to edit certain settings directly on your site, while others are kept in the Weebly modal. We'll provide a button in the modal to open your site in an iframe.

Note: Your server must be appropriately configured to send the right headers to allow us to load up the iframe. Please read the documentation about the X-Frame-Options HTTP header for more information.

​By default, the dialog that is opened for editing settings is an 800x600 Modal. You can change this with the height and width properties. The Modal that we generate will never grow beyond the page bounds, regardless of the size specified in your manifest. You can instead choose it to be set to be fullscreen.

Note: Your iframe settings panel should be constructed to expect requests from differently sized clients, as many users may not have the screen real estate expected.

​If your element does not have any visible settings or settings that use the Weebly modal (they are all in the iframe), then only the iframe is displayed.

Set the following properties:

urlA URL that contains a self-hosted page for editing settings. The URL must use the https protocol.

​Note: All URLs must use the HTTPS protocol. You will not be able to upload an app that uses HTTP.

We use a JSON web token (JWT) to inject information, including their user id, site id, element id, element uuid, iat (Issued at timestamp - i.e. the time the token was generated), and the jti (JWT token ID).

NOTE: Weebly automatically appends the JWT string to the end of the URL, including any necessary operands (like ? and &). If you want the JWT to be placed in a specific part of the URL, you can use :jwt, and Weebly will replace that with the JWT (without adding any operands - you'll need to include those).

​Example URL: https://www.example.com​Below is an example of how to decode the JWT hash:

labelThis string will be used as the label for button displayed in the modal to open the iframe. Below shows what might be displayed if you set this to "Edit Your Map."

heightThe height the modal should be set to. Your iframe will be placed inside this modal size. Do not set if you want the modal to be fullscreen.

widthThe width the modal should be set to. Your iframe will be placed inside this modal size. Do not set if you want the modal to be fullscreen.

modalSet to true to have your iframe display in a modal. If you would like the user to be able to interact with the Weebly editor in the background, you can set this to false.

fullscreenSet to true to have your iframe display in the entire screen area.

Note: Fullscreen should only be used when absolutely necessary, as it breaks the design flow for the user.

The following shows an example of an external setting using a modal:

External settings

Combine External and Native Settings

Your element can use both external and native settings. Simply create the external settings as children to the config element (as usual) and create native settings as children to the properties element (also as usual), as shown in the following example.

External and Native Settings Together

Data Communication

To pass data between your external settings page and our system, we leverage the postMessage API. All messages are in the form of objects containing "action" and "data" keys.

Message format for postMessage API

We support four different actions:

settings:loadThis event is sent to your iframe once it is loaded and initialized. The data key has two sub-keys. First, config, which contains information about the current configuration of the element (such as user_id, site_id, and element_id). The second is settings, which is an object that contains key/value pairs of settings. We do not pass the entire settings structure (including minimums, maximums, etc.).

settings:updateThis is an event you send to us. The data key should be a key/value hash of the settings and the value you hope to set them to. This object is a modified copy of the data.settings key provided to you by settings:load. If the settings are invalid, you will receive a settings:invalid postMessage back. If the settings are successfully saved, you will receive the settings:updated event.

settings:invalidIf you try to save settings but they are invalid, we will postMessage back an action of settings:invalid. The data key will contain setting names as keys, each having an array of errors as the value. Only invalid settings will appear in this object.

settings:updatedThis is returned to your external frame after your settings are successfully saved after a settings:update call. This event should be used to auto-close the settings dialog if you would like to to disappear after a successfully save.

dialog:closeYou may trigger this action at any time to tell our system to close the settings dialog.

When sending messages to us, you must ensure that you are sending them to the correct domain endpoint. The easiest way to do this is to listen for the initial settings:load event and store the origin URL for later use (see example below).

Store Origin URL

Note: You must remain on the same host/domain that you specify in your manifest.json. Any redirects will cause the postMessage protocol to fail. Additionally, all URLS must use the HTTPS protocol.

Accessing Settings

You can access your settings from anywhere within your application code, including JavaScript, CSS, and Templates. Please see the various sections for Templates, Javascript, and Stylesheets for information on how to access them in each location.