Widgets & Components

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:

• Right-click any element to see suggested Widgets that fit the current position in the page tree
• Use Widgets as page templates that provide starting points for new pages
• Configure Widgets with variables that are filled in when inserting them
• Drag Widgets from the flyout as an alternative way to insert them into your pages
• Share Widgets across applications using remote Widget servers

The component type system, suggested Widgets, and the widget replacement mechanism all work with local Widgets only. Remote Widgets can be inserted via drag and drop but do not participate in the component type logic.

Using Widgets

The primary way to insert a Widget is through the context menu. When you right-click an element in the page tree, Structr checks which Widgets have selectors that match the current element and shows them under “Suggested Widgets”. This approach respects the component type system and only offers Widgets that are compatible with the current position in the page tree.

As an alternative, you can drag a Widget from the Widgets flyout directly into the page tree. This method does not enforce the component type rules, so you are responsible for placing the Widget in a valid position.

If the Widget has configuration options, a dialog appears where you can fill in the required values before the Widget is inserted.

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.

In their simplest form, Widgets contain plain HTML. Structr parses the markup and creates the corresponding elements directly in the page tree. The resulting elements have no connection to the Widget source. They are independent copies, and inserting the same Widget twice creates two separate sets of elements.

Widgets can also define Shared Components using <structr:shared-template> tags. In that case, Structr creates the Shared Components only once. When you insert the Widget again, Structr recognizes that the Shared Components already exist and reuses them instead of creating duplicates. This is the mechanism behind widget libraries, where each Widget should produce consistent Shared Components across all pages. See the Building a Widget Library section for details.

Widget source code can contain template variables in square brackets like [variableName]. Structr only treats a square bracket expression as a template variable when a key with the same name exists in the Widget configuration. All other square bracket expressions are left unchanged. When a Widget has at least one recognized template variable, Structr displays a dialog where you fill in the values before insertion. See the Configuration section below for details on defining these variables.

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.

Remote Widgets can only be inserted via drag and drop. They do not appear as suggested Widgets, and they are not available for widget replacement.

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:

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

Setting Structr Attributes in Widget Source

Widget source code is plain HTML, but Structr elements have attributes that do not exist in HTML, such as componentType or contentType. To set these attributes during widget import, use data-structr-meta- prefixed HTML attributes.

The naming convention is: take the Structr attribute name in camelCase, convert it to kebab-case, and prefix it with data-structr-meta-. When Structr imports the widget, it strips the prefix, converts the remainder back to camelCase, and sets the corresponding attribute on the element.

This mechanism works for any Structr attribute, not just the ones listed above.

Configuration

The Configuration tab defines template variables for the Widget. Template variables use square brackets in the Widget source, for example [configSwitch]. Each variable needs a corresponding key in the configuration JSON. Only square bracket expressions with a matching key are treated as variables; all others are ignored.

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:

Description

The Description tab contains text that is displayed when you add 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: CSS selectors that control under which elements the Widget appears as a suggested Widget in the context menu. For example, [type='container'] makes the Widget appear inside any element with componentType container. Multiple selectors can be combined: [type='container'], [type='form'].
• Is Page Template: Check this box to make the Widget available as a page template when creating a new page.

Shared Components vs. Widgets