Pages & Templates

Widgets

Widgets are reusable building blocks for your pages. They can range from simple HTML snippets to complete, configurable components with their own logic and styling. You can use Widgets in several ways:

Drag Widgets from the flyout to insert them into your pages
Create page templates from Widgets to provide starting points for new pages
Configure Widgets with variables that are filled in when inserting them
Make Widgets appear as suggestions in the context menu for specific element types
Share Widgets across applications using remote Widget servers

Using Widgets

To add a Widget to your page, drag it from the Widgets flyout into the page tree. If the Widget has configuration options, a dialog appears where you can fill in the required values before the Widget is inserted.

Widgets can also appear in the context menu as suggested Widgets. When a Widget’s selector matches the current element, it appears under “Suggested Widgets” and can be inserted directly as a child element.

Page Templates

Widgets with the “Is Page Template” flag enabled appear in the “Create Page” dialog. When you create a page from a template, Structr imports the complete Widget structure including content, repeaters, permissions, and shared components. This provides a quick starting point for common page layouts.

How it works

Widgets are stored as objects in the database with an HTML source code field. When you insert a Widget into a page, Structr parses the source code and creates the corresponding page elements. If the Widget contains template expressions in square brackets like [variableName], Structr checks the configuration for matching entries and displays a dialog where you fill in the values before insertion.

Widgets can contain deployment annotations that preserve Structr-specific attributes like content types and visibility settings. Enable processDeploymentInfo in the Widget configuration to use this feature.

The Widgets flyout

The Widgets flyout is divided into two sections: local Widgets stored in the database, and remote Widgets fetched from external servers.

Local Widgets

Local Widgets are stored in your application’s database. Click the plus button in the upper right corner of the flyout to create a new Widget. The Widget appears in the list and can be dragged into the page tree. Right-click a Widget to open the context menu, where you can edit the Widget or select “Advanced” to access all attributes, including paths for thumbnails and icons.

Categorizing Widgets

Use the treePath attribute to organize Widgets into categories. The attribute contains a slash-separated path that defines nested categories. The string must begin with a slash, and categories can contain spaces. For example: /Forms/Input Elements creates a category “Forms” with a subcategory “Input Elements”.

Remote Widgets

Remote Widgets are fetched from external Structr servers. The Widgets on the remote server must be publicly visible. Use the “Configure Servers” dialog to add servers. The dialog shows a list of configured servers, with the default server that cannot be removed. Below the list, enter a name and URL for a new server and click save.

Editing Widgets

The Widget editor has five tabs: Source, Configuration, Description, Options, and Help.

Source

The Source tab contains the HTML source code of the Widget, which can include Structr expressions.

The easiest way to create this source is to build the functionality in a Structr page and then export it. Add the edit=1 URL parameter to view the page source with Structr expressions and configuration attributes intact, without evaluation. For example:

Create your Widget in the page “myWidgetPage”
Go to http://localhost:8082/myWidgetPage?edit=1
View and copy the source code of that page
Paste it into the Source tab

Configuration

The Configuration tab allows you to make Widgets configurable by inserting template expressions in the Widget source. Template expressions use square brackets like [configSwitch] and can contain any characters except the closing bracket. When a corresponding entry exists in the configuration, Structr displays a dialog when adding the Widget to a page.

Elements that look like template expressions are only treated as such if a corresponding entry is found in the configuration. This allows the use of square brackets in the Widget source without interpretation as template expressions.

The configuration must be a valid JSON string. Here is an example:

{
    "configSwitch": {
        "position": 2,
        "default": "This is the default text"
    },
    "selectArray": {
        "position": 3,
        "type": "select",
        "options": [
            "choice_one",
            "choice_two",
            "choice_three"
        ],
        "default": "choice_two"
    },
    "selectObject": {
        "position": 1,
        "type": "select",
        "options": {
            "choice_one": "First choice",
            "choice_two": "Second choice",
            "choice_three": "Third choice"
        },
        "default": "choice_two"
    },
    "processDeploymentInfo": true
}

The reserved top-level key processDeploymentInfo (boolean, default: false) allows Widgets to contain deployment annotations.

Configuration elements support the following attributes:

Attribute	Applies to	Description
`title`	all	The title displayed in the dialog. If omitted, the template expression name is used.
`placeholder`	input, textarea	The placeholder text displayed when the field is empty. If omitted, the title is used.
`default`	all	The default value. For input and textarea, this value is prefilled. For select, this value is preselected.
`position`	all	A numeric value for sorting options. Elements without a position appear after those with a position, in natural key order.
`help`	all	Help text displayed when hovering over the information icon.
`type`	all	The input type. Supported values are `input` (default), `textarea`, and `select`.
`options`	select	An array of strings or an object with value-label pairs. Arrays render as simple options. Objects use the key as the value and the object value as the displayed text.
`dynamicOptionsFunction`	select	A function body that populates the options array. The function receives a `callback` parameter that must be called with the resulting options. If provided, the `options` key is ignored.
`rows`	textarea	The number of rows. Defaults to 5.

Description

The Description tab contains text that is displayed when the user adds the Widget to a page. It can contain HTML and is typically used to explain what the Widget does and how to use the configuration options. The description is only displayed when the Widget is a page template.

Options

The Options tab contains two settings:

Selectors: Controls under which elements the Widget appears as a suggested Widget in the context menu. Selectors are written like CSS selectors.
Is Page Template: Check this box to make the Widget available as a page template when creating a new page.

Widgets can define Shared Components

Widgets can define reusable Shared Components that are created when the Widget is inserted. Use <structr:shared-template name="..."> to define a Shared Component, and <structr:template src="/structr/docs/..."> to insert a reference to it.

The Widget source has two parts: first the definitions of the Shared Components, then the structure that references them.

Example:

<!-- Define Shared Components -->
<structr:shared-template name="Layout">
    <div class="layout">
        ${render(children)}
    </div>
</structr:shared-template>

<structr:shared-template name="Header">
    <header>
        ${render(children)}
    </header>
</structr:shared-template>

<!-- Reference and nest them -->
<structr:template src="/structr/docs/Layout">
    <structr:template src="/structr/docs/Header">
	    <h1>Welcome</h1>
    </structr:template>
</structr:template>

This Widget defines two Shared Components: “Layout” and “Header”. At the bottom, it references them and nests “Header” inside “Layout”. When you insert this Widget again, Structr reuses the existing Shared Components instead of creating duplicates.