Skip to main content

Writing My Own Custom REL Tag

This walkthrough describes an implementation of an SDL Tridion custom REL tag. The tag has been written in SDLTridion 2013, but it is also applicable to Tridion 2011.

Tridion comes with a number of default REL tags, but you can also add your own custom tags. A REL tag can appear inside a Page or Component Presentation content, and it has to be published to the Content Delivery Database. These tags are executed on the Content Delivery side (presentation server) in one of the following situations:
  • using the ComponentPresentationAssembler: when retrieving the content of a DCP;
  • using the PageContentAssembler: when retrieving the content of a Page;
  • using Content Delivery Web Service (OData), when retrieving either a Page or a DCP;

Prerequisites

In my approach, I chose to use the Content Delivery Web Service (OData) approach. This means I had to install and configure an OData service. You can do so by following the installation guide from SDL Live Content.

I also needed a Deployer that publishes everything to the CD DB. I went on and installed and configured one. For details about Deployer installations, you could consult the online documentation portal as well.

Good Part First -- The Code

A custom REL tag has to implement interface com.tridion.tcdl.TagRenderer. The example tag I implement is located in package com.tridion.extensions.customrenderer, and it only outputs the string "Hello, world!". The code below shows just that. Yes, it is Java!

public class HelloWorld implements TagRenderer {

    @Override
    public String doEndTag(Tag tag, StringBuffer content, TransformContext transformContext,
            OutputDocument document) throws TCDLTransformerException {
        content.append("Hello, world!");
        return content.toString();
    }

    @Override
    public int doStartTag(Tag tag, StringBuffer content, TransformContext transformContext,
            OutputDocument document) throws TCDLTransformerException {
        return Tag.CONTINUE_TAG_EVALUATION;
    }

    @Override
    public boolean requiresCodeBlock(TransformContext transformContext,
            OutputDocument document, Tag tag) {
        return false;
    }
}

Next, compile this class into a JAR and place it in the /lib folder among your other JARs part of your Content Delivery stack. In my case, as I'm running an OData service as a Java web application, I copied it to the [ODataWebRoot]/WEB-INF/lib folder.

The Configuration

First we need to define a mapping between a certain namespace, a tag name and its implementing class. This is used by the TCDL rendering mechanism to know that whenever it encounters that namespace and tag name, it should execute the mapped implementation class.

Create an XML file, name it my-custom-tag-bundle.xml and copy the following XML snippet in it:

<TCDLEngine>
    <Tags>
        <Tag Namespace="rel" Name="HelloWorld">
            <Handler Class="com.tridion.extensions.customrenderer.HelloWorld"
                AllowCodeBlock="false" />
        </Tag>
    </Tags>
</TCDLEngine>

Place this file among the other Tridion CD configuration files in your web application. In my case, I copied it to [ODataWebRoot]/WEB-INF/classes.

Next, we need to reference the XML above in the configuration file cd_dynamic_conf.xml. Edit this file in your web application, and add the highlighted line directly inside the existing TCDLEngine node.

NOTE: There is a bug in cd_dynamic_conf.xsd, which omits to specify TagBundle as a valid child element of TCDLEngine. The example below works, though. Use it!

<TCDLEngine>
    <TagBundle Resource="my-custom-tag-bundle.xml" />

    <Renderer Class="com.tridion.tcdl.TCDLRenderer">
        <Properties>
            <Property Name="prop1" Value="value1" />
            <Property Name="prop2" Value="value2" />
        </Properties>
    </Renderer>
</TCDLEngine>

The CM Part

Create a Dreamweaver TBB that outputs the custom REL tag. You can choose an arbitrary name and namespace. I chose name HelloWorld and namespace rel.
Snapshot of a custom REL tag in a Dreamweaver TBB

Place the Dreamweaver TBB on a compound Page Template called REL PT.

I needed a simple Page that would output my custom REL tag. Create a simple Page, with no Component Presentations on it. Make use of the REL PT.
Snapshot of an SDL Tridion Page using the REL Page Template

Next I needed to publish the Page, so I needed a Publication Target for that. This target would have to be configured to use REL language.
Snapshot of an SDLTridion Publication Target with Target Language REL

At this stage, we can publish the Page and it would end up in the Content Delivery DB. There will be a record basically containing the page content in a CLOB column:

My custom REL tag: <rel:HelloWorld />

Testing it All...

In a browser, fire a request to the CD Web Service, requesting the Page Content for the Page you just published. My URL looks something like this:

http://localhost:8080/odata/odata.svc/Pages(ItemId=974,PublicationId=5)/PageContent

The response is following:
Snapshot of CD Web Service response with executed custom REL tag

Notice the text inside the d:Content element: "My custom REL tag: Hello, world!". It shows how the call to the custom REL tag has been replaced by the value we output from the tag code.


Comments

Popular posts from this blog

Toolkit - Dynamic Content Queries

This post if part of a series about the  File System Toolkit  - a custom content delivery API for SDL Tridion. This post presents the Dynamic Content Query capability. The requirements for the Toolkit API are that it should be able to provide CustomMeta queries, pagination, and sorting -- all on the file system, without the use third party tools (database, search engines, indexers, etc). Therefore I had to implement a simple database engine and indexer -- which is described in more detail in post Writing My Own Database Engine . The querying logic does not make use of cache. This means the query logic is executed every time. When models are requested, the models are however retrieved using the ModelFactory and those are cached. Query Class This is the main class for dynamic content queries. It is the entry point into the execution logic of a query. The class takes as parameter a Criterion (presented below) which triggers the execution of query in all sub-criteria of a Criterio

A DD4T.net Implementation - Custom Binary Publisher

The default way to publish binaries in DD4T is implemented in class DD4T.Templates.Base.Utils.BinaryPublisher and uses method RenderedItem.AddBinary(Component) . This produces binaries that have their TCM URI as suffix in their filename. In my recent project, we had a requirement that binary file names should be clean (without the TCM URI suffix). Therefore, it was time to modify the way DD4T was publishing binaries. The method in charge with publishing binaries is called PublishItem and is defined in class BinaryPublisher . I therefore extended the BinaryPublisher and overrode method PublishItem. public class CustomBinaryPublisher : BinaryPublisher { private Template currentTemplate; private TcmUri structureGroupUri; In its simplest form, method PublishItem just takes the item and passes it to the AddBinary. In order to accomplish the requirement, we must specify a filename while publishing. This is the file name part of the binary path of Component.BinaryConten

Scaling Policies

This post is part of a bigger topic Autoscaling Publishers in AWS . In a previous post we talked about the Auto Scaling Groups , but we didn't go into details on the Scaling Policies. This is the purpose of this blog post. As defined earlier, the Scaling Policies define the rules according to which the group size is increased or decreased. These rules are based on instance metrics (e.g. CPU), CloudWatch custom metrics, or even CloudWatch alarms and their states and values. We defined a Scaling Policy with Steps, called 'increase_group_size', which is triggered first by the CloudWatch Alarm 'Publish_Alarm' defined earlier. Also depending on the size of the monitored CloudWatch custom metric 'Waiting for Publish', the Scaling Policy with Steps can add a difference number of instances to the group. The scaling policy sets the number of instances in group to 1 if there are between 1000 and 2000 items Waiting for Publish in the queue. It also sets the