TCDL-Basics II : Understanding Tridion Custom Web Controls

The way any custom web control is developed in Asp.Net, same way Tridion has few custom webcontrols to offer . An understanding of these Custom Web Controls will help gain more control over developing Tridion Templates . They  are  built with a rich set of features that provides greater control over linking , Taxonomies , displaying Component Presentations and they can be extended further to meet our requirements.

Most of these Tridion’s Custom Web Control inherit the abstract class: LinkControlBase which inherits the WebControl class. The LinkControlBase class implements a WriteLinkTag() method which writes the final valid standard HTML tag.

These Custom Web Controls simply make a call to this WriteLinkTag() method when overriding the Render method.

Let’s see how to use one such Tridion’s Custom Web Control:  ComponentLink

In Content Manager, we create  link between pages usually through linking of components used in those two pages.  The Template code used to create such links looks like:
<a tridion:href ….. ></a>.

This very same task can be achieved through ComponentLink Web Control.

Below is the markup of the ComponentLink  Web Control :

TCDL_2

You can use such markups in your DWT.

So, based on this markup, we can indeed guess the way ComponentLink class is constructed.

Disclaimer: The class constructed below is mostly from the observations done using 
Visual Studio like: selecting properties option, categorization of properties as seen 
using visual studio, check for DataBindings, testing for default values etc...

public class ComponentLink : LinkControlBase
 {
    private string _pageUri;
    private string _componentUri;
    private string _templateUri;
    private bool _addAnchor;
    private string _linkText;
    private string _linkAttributes;
    private bool _textOnFail;

  public bool AddAnchor
 { get{ return this._addAnchor;}
   set{ this._addAnchor = value;} }

 public bool TextOnFail
 {  get{return this._textOnFail;}
    set{this._textOnFail = value;} }
 
 public string LinkAttributes
 {  get{return this._linkAttributes;}
    set{this._linkAttributes = value;} }

 public string LinkText
 { get{return this._linkText;}
   set{this._linkText = value;} }
 
 public string PageUri
 {  get{return this._pageUri;}
    set{this._pageUri = value;}  }
 
 public string ComponentUri
 {  get{return this._componentUri;}
    set{this._componentUri = value;} }
 
 public string TemplateUri
 { get{return this._templateUri;}
   set{ this._templateUri = value;} }

// And as usual this class MUST override the RENDER Method.

 protected override void Render(HtmlTextWriter writer)
   {
      // here the render method calls the GetLinkAsString() method
     if (HttpContext.Current != null && HttpContext.Current.Application != null)
       {
         using (ComponentLink componentLink = new ComponentLink(
                                      new TcmUri(this._componentUri).PublicationId))
           {
             string linkAsString = componentLink.GetLinkAsString(this._pageUri,
                                   this._componentUri, this._templateUri,
                                   this._linkAttributes, "",
                                   this._textOnFail, this._addAnchor);
             // WriteLinkTag() method is present in the base class LinkControlBase
             // The below method actually writes the standard HTML Tag 
             base.WriteLinkTag(writer, linkAsString, this._textOnFail, this._linkText);
            }
        } 
     }

}

Now, let’s see what’s the purpose of these different class properties are :

AddAnchor:

This attribute basically determines creation of HTML Anchor Link.

These are of two types:

Link to Anchor on Same Page :
<a href=“#example>Example Section</a>

OR Link to Anchor on Another Page:
<a href=”../sample.aspx#generator>HTML link Sample</a>.

Here, in our ( Tridion ) case, setting this attribute to true will append #1, #2, #3 to the href and it represents the Ordinal(index) position of the Component on the target( destination ) Page.

Set this to true only in case the destination page is having sections such as <a id=”1″>a>  for the Component Presentations present and you need to create links to these sections directly.

Set this to false as in most cases we only need to create a simple link to some other page.

The default value of this attribute is false.

LinkAttributes:

Any attributes we define for the tags in DWT such as for example: class=”productSection” and title=”Products” , as in :
<a class=”productSection” title=”Products” target=”_blank”>View Products</a>

Such attributes will be placed inside the LinkAttributes and the rendered  TCDL tag by Link Resolver TBB will be:

 <tridion:ComponentLink runat="server" PageURI="tcm:123-250247-64" 
       ComponentURI="tcm:123-654754" TemplateURI="tcm:0-0-0" AddAnchor="false" 
       LinkText="ViewProducts" 
       LinkAttributes=" class=&#34 ;productSection&#34 ;" title=&#34 ;Products&#34 ; " 
           TextOnFail="true"/>

TemplateURI:

More Appropriately, this property should have been named ExcludeTemplateURI

This is used to specify, or better to say exclude , a particular Component Template and hence a particular Page, to NOT link to.

Suppose you have a single  Component named: Product , inserted( used ) by two different Pages in Content Manager , let’s say, MiniProducts and LargeProducts. Now there is a 3rd Page BrowseProducts where we want to place/create a link to say LargeProducts page. [ You will simply link the initial ‘Product’ Component to one of the components used in BrowseProducts page ]

Assuming both the Pages: MiniProducts and LargeProducts are published, Can you Guess whose link will appear/be created by tridion on the BrowseProducts page ?

Factors such as Proximity, Template Priority and Publish date will determine how the links are resolved here.  So what if unintentionally a link gets created to MiniProducts page ( just an examplebecause this page was published most recently and other factors failed to resolve link )

So, how can you be always sure that a link is created – or more better to say NOT created –  to a particular page in any case ?

That’s where this TemplateURI attribute comes to rescue. Assuming the Component Template used is different in the two pages, specify the URI of the Component Template used in the Page to NOT link to in this attribute: TemplateURI. ( read again to understand )

Note: This attribute value is usually set to tcm:0-0-0.

LinkText:

This is the standard text to be displayed for the Link.

TextOnFail:

Set this to a boolean value true / false. In case the Dynamic Link Resolver fails to resolve the link to destination page ( such as Page is NOT published ), the value of this attribute determines what to do next.

true:  Show the plain text without a hyperlink even if link resolving fails.

false: Removes the link text in case link resolving fails.

The default value for this attribute is true.

ComponentURI:

The Content Manager URI of the Component being used for linking.

PageURI:

This is the Source PageURI ( URI of the page where the component link will appear ) and NOT the  Destination PageURI.

This marks the end of our first look at Tridion’s Custom Web Controls.Tridion offers more such controls  to your ease like: BinaryLink, ComponentPresentation, PageLink etc.. as seen below. TCDL_3

 NOTE:

To check these controls ( and their markup ) using visual studio , follow below steps so that visual studio intellisense will detect and display these controls on the go as you type.

    1.  Add a reference to Tridion.ContentDelivery.dll to Visual Studio solution.
    2. Add below entry in web.config
<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.


One thought on “TCDL-Basics II : Understanding Tridion Custom Web Controls

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