Content Placeholder

WEM Widgets Extension: Placeholder for content elements

The Content Placeholder in Widgets provides a way to let WEM-Users include WEM Template Editor content and elements within a Custom Widget - where the Placeholder in the Widget will be replaced with all content added to the Widget in the WEM Template. With this powerful feature you can nest Widgets and Template Content in a way which is similar to other container-elements in the Template Editor (panels, alerts, repeaters etc.).

1. Create a Content Placeholder

Select the "Placeholders" tab in the Widget Editor;
Click on "New placeholder" in the tabbar;
Enter a name (which must be unique within the collection of placeholders for this specific widget);
Press "Create";

Optionally, you can provide a label and a description; this information can be displayed in the Template Editor, in the "preview" of this widget where it is added to the Template.

2. Add WEMScript to render Placeholder content

To display the content (that will be added in the WEM Template Editor when using this widget) of the Content Placeholder at Runtime, you need to use the render statement in the Widget WEMScript (2nd tab). You can see the available Placeholders (and other properties) in the tree to the left. From here you can drag the placeholder onto the WEMScript canvas.

// as simple as this:
<? render @BodyContent ?>

You can even use the render statement within HTML elements and even in loops, for example to create placeholders within an HTML Bullet-List or Numbered-List Element based on a number of items in a runtime-list:

<ol class="my-list">
    <? loop @MyList ?>
        <li><? render @MyListItemContent ?></li>
    <? end ?>
</ol>

3. Add Template Editor Script (optional)

Default Preview

If you provide NO Template Editor Script (to show your specific content when Widget is placed on a Template Canvas), then the WEM Default Widget-Preview will be used to display your Widget in the WEM Template Editor, this will actually be good enough for most standard situations. It will automatically show the Placeholder's Label and Description value if provided - and will show the specific space where custom content can be dropped:

Custom Preview

If you want to change the way your Widget is displayed in the WEM Template Editor, you can create your own custom Widget-Preview using the Template Editor Script. In this case, the Content Placeholders need some special care, so we added the createPlaceholderElement utility function and the placeholders object. In the tree to the right, you can see the available utility functions and other elements that you can use in this script. The createPlaceholderElement and the placeholder's properties can be inserted into the script at the cursor position by double-clicking on the elements in the right-hand tree (to avoid typos...).

The screenshot below misses the name, label and description properties in the tree, but that will soon be available!

const rootEl = utility.createElement("div");

//manually add the Label and the Description values
const descriptionEl = utility.createElement("div");
descriptionEl.textContent = placeholders.BodyContent.label;
//description-value will appear on mouse-over as tooltip
descriptionEl.title = placeholders.BodyContent.description;

rootEl.append(
	descriptionEl, 
	utility.createPlaceholderElement(placeholders.BodyContent.name)
);
return rootEl;

With these 3 steps, you've created a Widget with a Placeholder. These are the basic steps to take to enable the Placeholder feature in your Widget.

Next screenshots show the "Simple Content Placeholder Example" widget in use on a WEM Template. An Alert Element has been added and a Label showing how many records in a list is available. In the Runtime you'll see the Alert and the actual number of records in the Products list.

5. Example Widgets (source)

Below we provide a collection of basic examples (sources) of Widgets with Placeholders, a "simple" example like described on this page, and examples that mimic the standard Alert, Datagrid, Panel and Repeater elements, just to give a few basic ideas of how this feature can be used.

7KB

ContentPlaceholderExamples.zip