About Templates

All templates make use of Mustache for the templating language. Your template can include static HTML and the following dynamic content:

  • Content fields: You can insert text, button, and image components that the user can edit.
  • Settings: You can access values for settings that the user has set on the element (you create settings in the manifest file).
  • Data: Your template can include the values for the element, user, and site IDs, as well as the path to the element assets.

Templates (.tpl files) are located in an html folder in the root of your element. You need to create at least one template named element.tpl, which will be used for both the placeholder in the editor and the published site.

Editor vs. Published Templates

​Your element is displayed in the editor using an element placeholder. By default, this is the same as your element on a published site, and so uses the same template. However, you can also provide an editor_element.tpl file to be used only within the editor. This allows you to specify a different UI (or an augmented UI) within the editor. This may be necessary when your element requires major interactivity with the user on a published site, as the element placeholder in the editor can handle only basic interaction, such as direct editing.

Add Content Fields

​Content fields are small sections of your element that are directly editable by the user. They make use of existing Weebly components, providing a consistent UI between your element and the Weebly ecosystem. ​Weebly supports four types of content fields:

  • text: Text displayed in the element. The text in the Price Chart element uses text fields.
    Text content fields
  • image: Your template can include images. The Weebly Team Card element allows the user to upload images of people.
    Image content in an element
  • button: You can include buttons in the template to initiate an action. The Price Chart uses a button.
    Button in the Price Chart
  • content: Content fields allows the user to drag elements into your element. The Weebly Accordion element is an example of one that uses content fields.
    Users can drag elements into an accordion pane

Each content field requires a unique name and you can provide a default value. This example shows the syntax for defining a field:

<div class="example">
    {unique_name:field_type default="Default Text Here"}

For example:

<div class="example">
    {name:text default="Put your name here"}

Every content field must have a unique name. If two content fields share a name, only the first one will act as an editable content field, with the other remaining as text within the element. ​

If you want to be able to hide/display different areas of content at a time, then use CSS to set visibility and any content set to visible will be displayed. You can also set a width on the content area, for example, {myContentArea:content width="50%"}. If a user moves or copies a {content} field, all child elements will get moved/copied as well.

Access Settings

Within your template, you can access element settings for your content fields using Mustache tags. Each content field name is made up of the following:

  • A prefix you decide on (like name or field)
  • The name attribute of the setting, specified in the manifest.json
  • The content field you want use
  • A default value if you want to override the value in the manifest

For example: {name_{{setting}}:text default="My Setting"} .

The Team Card app allows users to enter a name into a text field.

Users enter a name in the Team Card element

Here’s the manifest entry for the Name setting of the Team Card:

    "name": "employee",
    "default": "Awesome Name",
    "type": "string",
    "label": "Name"

The template for the Team Card uses this to create the name field:

<div class="name">
        {field_{{employee}}:text default="Name"}

​For any integer settings, we generate a iterable value for you, allowing you to perform loops within your templates. For any integer setting with a value less than 100, we generate an iterable setting item with the same name as your setting, appended with _each. Within your loop, you can access the current index with the setting name appended with _index.

For example, using the above manifest entry for plans, you can iterate over the instances like this:

<div class="example">
    {name_{{plans_index}}:text default="Plan Name"}

Access Additional Data

Within your template, you also have access to additional data. Every piece of data is accessed in a similar way to settings, using mustache tags. You can access the following:

  • assets_path: This is the HTTP accessible root path to your elements’ assets folder, in protocol-agnostic form. The path contains the trailing slash.
   <div class="example">
     <img src="your_image.png" />
  • element_id, user_id, site_id: These are the respective ID’s for the current user, site, and element instance. You can access these in your templates using standard Mustache syntax:
<div class="example">
    {{user_id}} - {{site_id}} - {{element_id}}

Use IFrames

If your element contains an iframe, we will automatically add an additional invisible overlay div for your element.. This div ensures that Weebly users will have a clickable target for accessing settings. Once the settings panel is opened, the overlay is removed so that users can interact with your iframe.

Help make these docs better!