Comment on page
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.).
- 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";
Creating a new placeholder
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.
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
renderstatement 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:
<? loop @MyList ?>
<li><? render @MyListItemContent ?></li>
<? end ?>
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:
Widget Preview default display in Template Editor without custom Template Editor Script.
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
createPlaceholderElementutility function and the
placeholdersobject. In the tree to the right, you can see the available utility functions and other elements that you can use in this script. The
createPlaceholderElementand 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!
Custom Template Editor Script for Placeholder
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;
Widget Preview Custom display in Template Editor with custom Template Editor Script.
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.
Content Placeholder Widget in WEM Template
Content Placeholder Widget in Runtime
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.