By continuing to use this site, you agree to the storing of first- and third-party cookies on your device to enhance site navigation; analyze site, product, and service usage; and assist in our marketing and promotional efforts. Cookie Policy

 
Skip to Content

Advanced Components

Developing advanced components is similar to developing table transformation snippets. The information entered by the page editor is stored in HTML, which the XSL then takes and renders on page publish into a more complex content. The benefits of using components over snippets are the ease-of-use of the form editor and input validation capabilities.

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 to make this transformation. You may already have a components.xsl in your /_resources/xsl/_shared/ folder or somewhere similar that you can modify, or you can create your own 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, potentially wrapping the component in a node, that the XSL can target. Then use a template match in the XSL to target the name or ID you defined.

Unlike with table transformations, you have much more freedom with how the source code looks when creating a component. Table transformations must be compatible with WYSIWYG, but as long as the component is not set to render in the WYSIWYG (e.g., it displays as the blue placeholder), it can be composed however you want.

If you opt for this strategy, you can write the component source code in straight XML, with easy-to-target nodes that the XSL transforms. Here, you can choose your own syntax; you create the rules that work for what you are trying to achieve.

Another method is to write out the component source code using attributes for the XSL to target. These attributes act as rules or logic statements that the XSL then uses to determine how the component displays. This is especially useful if you have elements of the component that you don't want to show if no content has been entered for that element, allowing for flexibility and optional elements.

In this example, we'll use a div with data-ouc-test="" as the example attribute. To match this attribute, in the XSL enter <xsl:template match="div[@data-ouc-test]"> ... </xsl:template>. This targets any div that has that attribute within it and formats it according to the template you write.

When building the component, insert the form element as the attribute value as well as where you want to place it in the actual component structure, like so: <div data-ouc-test="[[Image Caption]]">[[Image Caption]]</div>. This allows you to hide that element if that form field has no content entered into it. 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.

Additionally, the XSL can strip out that attribute on publish, to clean up the source code if so desired. 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 element you want to turn into editable content, and first decide if it should be a component at all. If you want to limit the 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. We then build the form elements that correspond to these items (an image chooser, a single-line text field, and a mult-line text field).

A list of three form elements: Image Chooser, Single-Line Text Field, and Multi-Line Text FieldThen 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:

A screenshot of the source code for the Image with Caption, with the form fields dropped into the source code and a data-ouc-test attribute used.

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 in Component Properties > Access.

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 logics 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 like so: <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.