Element Types

How an element behaves when dropped onto a page is an important user interaction, so try to emulate the Weebly elements, as closely as possible. Weebly elements generally fall into one or a combination of one of the following user flows:

  • Simple: There are no settings. Weebly examples include Title and Text.
  • Settings: The element has configurable settings. The user either has to click on the dropped element to launch the settings modal(s) or, if configured to autopop, the modal displays when the element is dropped onto the page. The Weebly Map and Button are examples of elements that use settings.
  • Connect: The element connects to external data. The user is presented with a popup dialog (optionally auto-pop) in order to find or create the data needed for the element. The Weebly Product element is an external element. It connects to a product in the store’s catalog.

Design the Element Settings

When determining settings for your element, try to use the same setting metaphors that you see in Weebly elements. Use the Weebly settings UI (the default) and try to not call out to an external site, which might be confusing to our users as they are used to the way Weebly elements and their settings behave. By remaining consistent with Weebly, your element will likely become more popular, garner positive reviews, and may even be featured in the App Center!

​Always use the OAuth process to gain access to our APIs and authenticate users at your site, or to create accounts for them, rather than creating a login page in an iFrame. Once OAuth is performed, you can access the user’s email address which you can use to determine if an account already exists, or to prefill a registration form.

Here are some questions to think about before you start coding. You’ll need the answers in order to create your element:

  • Should the element dialog display automatically when the element is dropped onto the page? Or will the user need to click the element to open the dialog?
  • Will the element’s settings display in the native Weebly dialog using Weebly components (preferred) or will the user be presented with an external site displayed in an iframe?
  • What type of display (such as text, integer, color picker) is needed for each setting? The Weebly dialog supports these types.
  • What settings can be grouped together and displayed on one dialog page? What settings will need their own section?
  • Do the settings require tooltips to help the user configure them correctly?
  • Is configuring and using the element complicated and so might need a tutorial? Should the tutorial be include a set of steps or a video?
  • What needs to be handled if a user copies the element to another page? Users can copy elements and place the copy on other pages in their site. All setting values are also copied over.
  • Will your element need to behave differently in the editor than on the published site? If so, you may want to create two sets of JavaScript, HTML, and/or CSS files.

Element Icon

​You need to create an svg file to represent your element in the element tray. It must be named icon.svg, and must live in the root folder of your element. Follow our element icon guidelines when creating your icon.

Element Placeholder

​Your element is displayed in the editor using an element placeholder. By default, this is the same as your element on a published site. However, it really should allow only minimal interactivity. For example, when dropped onto a page, the placeholder might allow users to directly edit content or forms in the content, but there shouldn’t be any navigation or any wizard-like behavior to configure the element. Have the element’s settings handle this type of interactivity. To provide the different functionality between the placeholder and the published element, you create different HTML templates, Javascript, and CSS for each.


Help make these docs better!