Advanced Components

Developing advanced components is similar to developing table transformation snippets. The benefit of using components is the editor-friendly form fields that validate the editor's input.

If you are not already familiar with XSL, please review our introduction to XML and XSL before continuing.

StructureLink to this section

Advanced components require XSL. You may have a components.xsl in your /_resources/xsl/_shared/ folder , or somewhere similar. You can also create your own XSL file by modeling it after a snippets.xsl or template-matches.xsl file.

In the component source code, define a name or ID for the component (or wrap the component in a node that the XSL can target). In the XSL file, use <xsl:template match> to target the name or ID you defined.

Unlike table transformations, you have more freedom when creating a component. Table transformations must be compatible with the What You See Is What You Get (WYSIWYG) editor. When editing the source of your component, select "No" to prevent the source from previewing as HTML in the WYSIWYG.

You can write the component source code in XML, with easy-to-target nodes that the XSL transforms.

To prevent component elements from displaying when no content has been entered, use attributes. In this example, we'll use a div with data-ouc-test="" as the attribute. To match this attribute, enter the following in the XSL file:

<xsl:template match="div[@data-ouc-test]"> ... </xsl:template>

This targets any div that has the data-ouc-test="" attribute within it and formats it according to the template you write.

To build the component, assign the form element as the attribute value, as follows:

<div data-ouc-test="[[Image Caption]]">[[Image Caption]]</div>

In the XSL, use

<xsl:template match="div[@data-ouc-test='']"/>

This self-closed element matches when the attribute has no value, and because no template behavior is defined, it won't render anything on the published page.

To clean up the source code, remove the attribute at publish. Use the same self-closing element, but instead target the attribute itself, rather than its value:

<xsl:template match="@data-ouc-test"/>

Step-by-Step ExampleLink to this section

Start with the design you want to turn into editable content, and first decide if it should be a component. If you want to limit the content editor's ability to affect the styling, or restrict how they enter content, then a component is a good option.

Then, when looking at the design, determine where you want editors to enter content. For this example, we're going to create a very simple image with a caption, so the three pieces of content we want the editor to add on the page would be the image itself, alt text, and an optional caption.

Then build the form elements that correspond to these items (an image chooser, a single-line text field, and a multi-line text field).

Then build out your component source code, using either the attribute method or the node method, and drop in the form fields. In this example, we're using the attribute method, so the component source code will look like this:

Save and launch the component, so you can test it on pages as you develop your XSL. If you want to prevent content editors from using it before it's ready, restrict who it's available to, as follows:

1.  Navigate to Content > Components.
2. Check out the component.
3. Click the More Actions  menu for the component.
4. Click Edit > Access Settings.
5. Click the "Available To" dropdown to select "Administrators Only."
6. Click Save.

Next, modify your XSL. In this instance, we're adding the following two rules:

• <xsl:template match="element()[@data-ouc-test='']"/>: This will remove the <p> element if no caption is entered.
• <xsl:template match="@data-ouc-test"/>: This will strip out the data-ouc-test attribute from the rendered page source code.

Simple attribute validation logic can be mimicked with CSS as well, so we will also create some display:none rules in the wysiwyg.css (see the page on tagging editable regions for more information) to enable WYSIWYG preview of optional elements being removed or kept.

• [data-ouc-test=''] { display: none; } : This will hide elements with empty data-ouc-test attributes.

While it is not necessary to directly match the component for simple elements like our caption example, you can define a component template should you need more control over your final output. In order to achieve this, use template-match to target the component name image-caption-optional , as follows:

<xsl:template match="ouc:component[@name='image-caption-optional']"> ... </xsl:template>

You may also need to modify your CSS, depending on the design changes you want to make. Save your XSL, and save and publish your CSS if applicable.

Finally, edit the component access settings and re-launch it so it becomes available for content editors to use.

It's important to know that this is just one example, and it is a simple example to get you started with advanced components. When it comes to creating advanced components, you are only limited by your creativity and XML rules (all components must not break XML rules), so it gives you a lot of freedom to come up with the best solution for your problem.