Weebly Element - Hello World Tutorial

Learn how the Weebly Element Hello World app is structured, with links to additional information for developers.

Welcome to Weebly Element Hello World Tutorial!

Learn how the Weebly Element Hello World app is structured, with links to additional information for developers.

The tutorial's navigation controls are located above this text. Use to move to the next step of the tutorial. Use to move to the previous step of the tutorial (if there is one). Use to see an overview of all the steps in the tutorial.

Manifest.json

The first file we'll look at is manifest.json..

NOTE: We'll be referencing a template manifest.json.tmpl file in this tutorial. Before deploying your Hello World Element, you will rename this file to manifest.json.

A Weebly app requires exactly one manifest.json JSON data file that lives at the root of the ZIP file you will upload to Weebly (more about this later). The manifest describes the app and also provides much of the UI functionality for an element. The manifest.json file the we've pre-defined for this tutorial defines a single element. But you can define multiple elements within a single manifest.json (app), if you choose.

Let's learn about the first three properties used to define this basic Hello World Element app:

manifest (string): Required The version of the Weebly Platform API your app implements, currently must always be set to "1".
version (string): Required The version of your app. This must follow Semantic Versioning guidelines.
elements (array): Required for Apps with Elements The list of element objects associated with this app.

To learn more about manifest.json, read Create the App Manifest in the Weebly Developer Docs.

Now, let's look inside the elements property to learn how the Hello World Element definition works.

Manifest.json - `elements`

The elements property must be an array that contains element objects. elements property is optional within a manifest.json file, but must be defined if you intend to create an element while you develop your app.

Element Objects

name required : The name of the Element that appears in the Weebly Editor Sidebar and setting dialogues, in our case, Hello World
path required : The relative file path to the element's asset directory within the app bundle
version required : This element's version, must follow Semantic Versioning guidelines, and be equal to or lower than the parent app version value
settings required : User-configurable properties for the element respectively

Full list of properties available to define your elements.

element.settings can be confusing, let's review our hello world element settings in the next step...

element.settings.config

The element settings property is required for each element in your manifest that will use the native Weebly configuration dialog.

Each element's settings object requires:

config (object): Required Element behavior object defining how settings are presented when an instance of the element is dropped onto a page in the editor by a user.

element.settings.config

The config object has two properties which can be set: autopop and external.

autopop (boolean): Required Developer-configured value indicating how the Settings modal should display to users.

true === Show immediately after instance of element is dropped on a page in the editor.

false === Shown only when user clicks on the element instance after it has been dropped on a page in the editor.
external (object): When set, defines iframe content to load external configuration settings loaded into the client from your server and communicates using PostMessage API. External settings are outside the scope of the Hello World example, but you can learn to use external settings.

Next, you'll learn more about an element's settings.properties...

The element settings.properties is the parent element for all settings.

NOTE: For demonstration purposes and to help you understand how settings work, the hello world element intentionally implements the most basic type of settings. However, it is important to understand that elements can contain complex groups of properties to define their settings.

Each element's settings must contain:

`properties' (array): Required Defines setting group(s) of user-configurable properties for each instance of the element dropped onto a page in the editor by a user

element.settings.properties.group

The first element which must be defined within any element.settings.properties array is a Group object.

Groups define organized sets of element setting properties together which are displayed to users while configuring an instance of your element in the Weebly Editor.

You can have more than one group defined within element.settings.properties if your element needs additional settings groups displayed to users, but that is outside the scope of this tutorial.

A Group consists of an object with the following properties:

name (string): Required The internal name of your group, can be used to address properties from within setting templates (more on this later)
label (string): Required Visible label presented to users as the group heading in the settings modal
type (string): Require Must be set to group
properties (array): Required The array of element setting objects, defines schema and metadata for each setting of the element within this group

Each object within the Group's properties array is an individual Setting for the respective element...

element.settings.properties.properties (we know, that is horrible).

Each item in this array defines one specific element setting property object.

You can include multiple setting definitions if needed, but that is outside the scope of this tutorial.

Setting Definition Properties Available

name (string): Required The internal identifier of your setting, can be used when addressing properties from within setting templates (more on this later)
label (string): Required Visible label of this setting presented to users in the settings modal
type (string): Required The Weebly-specific type for this setting. See below for more information on setting types
default (array): Required The default value for this setting, use an empty string for null.
hidden (boolean): Default === false, indicates if the setting is displayed for user-configuration of element instances, if set to true you must define a default value
private (boolean): Default === false, Flag indicating if property data is available to visitors of published sites, helpful for private data only used during configuration of the element instances such as API Keys
tooltip (string): Help string displayed to users during configuration when mouse hovers over this setting, max length is 100 characters, no markup allowed

To learn about the complete list of element settings available and their capabilities, read the Weebly Developer Docs. NOTE: If you want to have all of your settings managed via an external URL, you can set hidden to true on all settings. When the element's settings modal is displayed during user-configuration, it will simply contain a button to open the iframe referenced in the URL as defined in external settings.

To ask questions about this tutorial, or the code contained, please either: