TCDL – Tridion Content Delivery Language – Basics I

The final HTML rendered by the browser has links to images, other internal/external pages , besides other functionalities in the standard HTML format such as anchor tags used to represent links. However, The Links ( links to Pages, MultimediaItems, Components ) created within Tridion Content Manager are in there own language which must be processed and transformed to standard HTML tags.

Within a normal DWT, for example, we create a link to another Page simply by inserting the corresponding component used in destination page into some ComponentLink field, similar to something below:

<a tridion:href="@@Component.Fields.ProductLink@@" class="productSection" 
    target="_blank" title="@@Component.Fields.ProductLinkText@@">
    @@Component.Fields.ProductLinkText@@
</a>

code sample-1

Same way we can also create a link to a multimedia component by setting the tridion:href attribute appropriately.

Ever wondered how such attributes like: tridion:href is resolved to point to the correct Page/Multimedia item present on the presentation server. How is the attribute tridion:href being used and transformed/changed to point to a valid Page URL?.

So, what happens when the above DWT code is finally processed ? Is the processing different while previewing the Page in CMS and when the Page is published ?

And one last question, How does the above DWT code gets transformed to a valid HTML displayed finally in a browser ?

Let’s checkout…

Understanding What is Dynamic Link Resolving:

The Content Manager allows you to create links, that is, references from one Content Manager item to another Content Manager item.Dynamic Link Resolver can only resolve links between Content Manager items. Links to external resources cannot be resolved.

Page Links:

Links between different Pages. Usually Page links are created within  Page Templates to create navigation structures.

Binary Links:

Binary links point to binary files such as images, PDF documents. In the Content Manager, these binary files are represented as Multimedia Components.  These links are often created in Components as Multimedia Component link fields, or in format areas(RTF) as Multimedia Component links.

Component Links:

Links to any Component. These links are created in a Component in various ways: as Component link fields; as Component links in format areas(RTF) etc…

Dynamic Link Resolver resolve these links in several ways:

  1. It resolves Component links by linking to a published Web page that contains the target Component.
  2. If multiple published Web pages contain the target Component, Dynamic Link Resolver identifies the best target by looking at the priority settings of Component Templates, and then at the directory hierarchy of the published site, also called Proximity.
  3. It ensures that links are valid when the target item is renamed or moved to a different location on the Web site.
  4. It manages dead links ( Pages NOT published ) by letting you choose to display the link text of the dead link, or just omit the link text.

With this knowledge on Dynamic Link Resolving and types of Links, read on to understand how the DWT code(code sample-1 above) is transformed to  intermediary TCDL tags and then finally to a valid HTML displayed in browser.

Publishing a Page:

When a page is published, it helps to break the processing in 3 stages.

Stage I: Processing by the Link Resolver  Template

The Link Resolver TBB rewrites these links to Components in the Tridion Content Delivery Language (TCDL) format.

Thus, the above code sample-1 when rewritten in TCDL format by the Link Resolver TBB will look like:

<tcdl:Link type="Componentorigin="tcm:123-250233-64" 
      destination="tcm:123-654674" templateURI="tcm:0-0-0"
      linkAttributes=" class=&quot;productSection&quot; 
      title=&quot;Product&quot; " textOnFail="true" addAnchor="false" 
      variantId="">Product</tcdl:Link>

Stage II: Processing by the Deployer

And , Finally when the above TCDL tag is processed by the deployer, the final Asp.Net code generated will be :

<tridion:ComponentLink runat="server" pageURI="tcm:123-250233-64" 
         componentURI="tcm:123-654674" templateURI="tcm:0-0-0" addAnchor="false" 
         linkText="Product" linkAttributes=" class="productSection" 
         title="Product" " textOnFail="true"></tridion:ComponentLink>

IMPORTANT NOTE:

  1. The above final Asp.Net code can be seen in the Page deployed/present on the CDA server , in the Website’s appropriate folder. Open the page in Notepad to view such tags.
  2. Deployer will create these Custom Control tags (Asp.Net  based Controls ), if the below settings are present in the cd_deployer_conf.xml file.
    <TCDLEngine>
    <Properties>
    <Property Name=”tcdl.dotnet.styleValue=”controls“/>
    <Property Name=”tcdl.jsp.styleValue=”tags” />
    </Properties>
    </TCDLEngine>
  3. In case, settings as in point 2 above is NOT present, then deployer will generate Inline Code to render the standard HTML corresponding to the TCDL tags. NO Asp.Net Custom Web Server Control will be generated. See an example below for Inline Code.

The tridion:href attribute ( used in DWT Code) value is placed into the ComponentURI attribute on transforming into TCDL format. The other attributes like: class,title are placed into the LinkAttributes atribute. A separate blog post of mine will cover these in full details.

Stage III: Runtime Processing

This is where the Dynamic Link Resolver plays its role. The Asp.net based server control tags are resolved at runtime – on server side  – when a user requests the Page.

  1. The Dynamic Link Resolver  processes these custom control tags  thus converting them to the Standard HTML anchor tags.
    <a target="_blank" href="http://www.testWebsite/product.aspx">
       ProductSection
    </a>
  2. Additionally the Dynamic Link Resolver makes use of the configuration settings from file: cd_link_conf.xml , if required .
  3. In case resolving fails for some reasons, then either no link is generated, or plain text without a hyperlink is displayed, based on value of attribute: TextOnFail
  4. The dynamic Link resolving functionality is provided by the classes present in cd_Linking.jar  package. This jar package is present inside the ‘lib’ folder inside ‘bin’ folder of the website.

Inline Code Sample:

You can also write some Inline code directly in your Template (DWT), or, write this inline code directly in an aspx page present on a server to create a Link:

<%@ Import namespace="Tridion.ContentDelivery.Web.Linking"%>
 <%
     ComponentLink componentLink = new ComponentLink();
 %>
 
 <!-- A sample component link -->
     <% Response.Write(componentLink.GetLinkAsString("tcm:123-250233-64", 
       "tcm:123-654674", "tcm:0-0-0", "class=\"productSection\"",
        "SampleLink",true,false));%>
 <!-- end of component link -->
 
 <%
 componentLink.Dispose();
 %>

Note:

  1. The above code sample creates a link to a destination page containing the Component with URI: tcm:123-654674
  2. There are other versions of GetLinkAsString() method to create links to Binaries, Pages to Pages.
  3. Such Inline codes are generated by Deployer as an alternative to Custom Web Server Controls.

Previewing a Page : 

However, when a Page is previewed in CMS, such as when you select a page and click the Preview button, then in this case Dynamic Link Resolver  plays NO role and the Link Resolver TBB detects the Preview mode and will render/rewrite these links in its Preview Skeleton defined as:

<a href="CME_PREVIEW_URL#id=tcm:123-654674"></a>

Where CME_PREVIEW_URL will be the Preview URL of your Tridion installation and will be something similar to: /WebUI/Editors/CME/Views/Popups/Preview/Preview.aspx

As a last note, make sure below web.config settings are in place for such TCDL tags to be rendered correctly:

<pages>
 <controls> 
 <add tagPrefix="tridion" namespace="Tridion.ContentDelivery.Web.UI" 
      assembly="Tridion.ContentDelivery" /> 
 </controls>
</pages>

Hope you enjoyed this post. Comments and Suggestions are welcome.


13 thoughts on “TCDL – Tridion Content Delivery Language – Basics I

    1. Hi Chakresh,

      Thank you for your comment.

      Only when you open the page in any text editor such as Notepad++ you can see these TCDL tags. However, if the page is opened in any browser ( by navigating to the URL ) these TCDL tags can’t be seen.

      Like

  1. At stage 2 you mentioned some Control getting generated : Where can i get more detils on these control? is there any dll which is referred by the control ?

    Like

      1. @braddy: The Controls like: tridion:ComponentLink are basically custom web controls developed in Asp.Net Language, same as any other Custom Web Server Controls/ User Controls developed in .Net. And Yes, the DLL/Assembly which contains such controls is Tridion.ContentDelivery.dll. you may refer below links for more detailed reading on such Web Controls offered by Tridion:

        https://tridionbasicscity.com/2015/05/07/tcdl-basics-ii-understanding-tridion-custom-web-controls/

        http://tridionnut.blogspot.in/2013/01/tridion-and-net-user-controls.html

        Like

  2. Nitesh,

    I directly tried placing the Inline code sample you have given in one of my ASPX pages on server, with the proper TCM Uris of the Websites publication/items. However there seems some issue and Nothing seems to be displayed on page. I can’t find anything useful in my Logs too. Could you please guide me what went wrong ?

    Let me know if you want to see the Inline Code I created. I am sure that all TCM URIs used in code are correct and items does exist.

    Like

    1. @ Chad E : Make sure the Configuration settings are in place and the Tridion’s Content Delivery DLLs are in the bin folder of your website.

      Are the Pages published from Content Manager, linking properly to other published Pages, in case there is any page that links internally to another page through some Component linking ?

      Like

  3. yes, I have checked and configuration settings are fine and the DLLs for content delivery are also present.

    Also, I checked and there are many pages that internally linked to each other and those links are working fine. BTW, I just forgot to mention that I had placed the Link tag and a ComponentPresentation tag on the ASPX page. Its the latter that won’t works.

    Like

    1. @ Chad E:

      When using ‘ComponentPresentation’ tag/inline codes , make sure you use a Dynamic CT only. Embedded CTs are never rendered at Content Delivery side by using Inline codes or Custom Web Controls.

      Try specifying TCM URI of a Dynamic Component Presentation and check if it renders.

      Like

      1. Perfectly right Nitesh ! Specifying the TCM URI of a Dynamic CT indeed worked !!

        Thanks a million for your time in helping me understand the issue at hand. I Think I now got the point that this is the way Tridion has designed this particular control.

        Bookmarked and subscribed your blog. Keep sharing such nicely explained Tridion topics :)

        Like

  4. Again an excellent article ! Thanks for sharing such an In depth view on the TCDL concept in Tridion.

    The Deployer Stage Processing detailed above are excellent and the notable ones. Do keep sharing such Insights

    Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s