Monday, February 1, 2010

Sublayouts and Web Controls

Previously I explained what Sitecore's presentation controls are and why they are important. At this point you're probably ready for some technical details. These controls can be written using .NET for XSLT. In this post I will discuss presentation controls written using .NET.

When creating presentation controls using .NET you have two choices: user controls (which are called sublayouts in Sitecore) and web controls. For both user controls and web controls, the advantages and disadvantages inside Sitecore are the same in a regular ASP.NET application. Which you use depends on what you're trying to accomplish. (Microsoft has a good article that describes the differences between user controls and web controls)

And the user controls and web controls are plain old ASP.NET controls. There is no special Sitecore class to extend or interface to implement.

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="HelloWorldSublayout.ascx.cs" Inherits="mysite.HelloWorldSublayout" %>

[Hello, world.]

Example of an ASP.NET user control.

All of your development can be done in Visual Studio. Inside Sitecore, you simply need to register the control. After the control is registered it can be used inside placeholders.

Creating a sublayout using Sitecore.

The video above demonstrates how a sublayout is created inside Sitecore. The user creates a sublayout item, and then Sitecore generates the ascx file. But there's a little more to it than that.

When the user creates the sublayout, Sitecore creates a definition item for the sublayout. A definition item is the object inside Sitecore that maps a logical component to a physical one. Definition items are used in several places in Sitecore.

In this case, the logical component is the sublayout and the physical component is the ASP.NET user control (ascx file). The definition item merely points to a file on IIS. The location of the file was specified on one of the screens in the "create sublayout" wizard and can be changed at any time using the Content Editor.

The important thing to note is that the physical file can be edited outside of Sitecore. After this happens, Sitecore doesn't need to be notified. All Sitecore cares about is that it is able to locate a file at a certain location when a specific resource is requested.

Pretty much everything I just wrote about sublayouts is also true of web controls. In order to create a web control you use a different branch of the content editor (Layout\Renderings instead of Layout\Sublayouts). The configuration of the definition item for a web control is slightly more manual than that of a sublayout (you need to point Sitecore to a specific .NET class rather than a file). But I see these as minor differences.

What's next?
Presentation controls can be written using another technology as well: XSLT. My next post will describe how XSLT can be used to create presentation controls.

Want to learn more?


  1. Nice post, Adam. I'm really enjoying reading you Getting to Know Sitecore blog!

    I just want to make a few comments about Web Control items and classes in Sitecore.

    If you want your Web Control to be a Sitecore Web Control, the class needs to inherit from Sitecore.Web.UI.WebControl. There are many reasons for this, like getting access to control parameters, etc. Remember to override the DoRender() method.

    You can use the Sitecore Developer Center to create the Web Control definition item, or, just like in your video, select an insert option to create the definition item.

    Some people may be scratching their heads and asking "Where do I do this? There is no WebControls folder item, but there is a Sublayout item"

    You'll find the option in the Renderings item (path is"/sitecore/Layout/Rendering/").
    In the dialog, enter the name of the control. There are many fields to edit here, but I'll just focus on the important ones. I'll leave the blogging on this topic to you :-)

    The Editor Options field Section
    Description Field: Always enter a description, even use screenshots. In Page Editor Design Pane, business users will see this Rich Text Description.

    The Data Field Section
    Namespace: This is the namespace of the control. Copy it verbatim from visual studio. Do NOT type it in.

    Tag: This is the Class name of the control. Copy it verbatim from visual studio. Do NOT type it in.

    TagPrefix: Whatever you want it to be. Usually, we see a company tag prefix, like "og" or “pop”. Do NOT use sc, as this is for out-of-the-box Sitecore Web Controls.

    Assembly: This is usually the assembly name for the project. Copy it verbatim from visual studio. Do NOT type it in.

    Once you have created your definition item, you’re ready to go. For example, you’ll be it able to dynamically add the control to a placeholder using Page Editor Design Pane.

    Lastly, always remember to compile your control!

  2. Thanks for the feedback, Seth. One thing about web controls, though. I think a better way for me to have explained it is to say that even though you don't _have_ to, you _want_ to extend Sitecore.Web.UI.WebControl.

    By extending Sitecore.Web.UI.WebControl you get extra functionality, like what you described. Using a web control inside Sitecore without this functionality in most cases probably doesn't make a lot of sense. Surely you're not taking advantages of the strengths of the product this way.

    But Sitecore doesn't prevent you from using a web control that inherits from System.Web.UI.WebControls.WebControl.

    I think this is a good thing. This could be useful is you have a web control that doesn't interact with Sitecore. For example, a web control that monitors site traffic or one that generates ads.

    Granted, neither of those is the best example because both could benefit by interacting with Sitecore, but hopefully you get the idea!

  3. And another comment on WebControls, if you want to use Sitecore Caching on them, make sure to inherit from Sitecore.Web.UI.WebControl and override GetCachingID() method.
    No need to do anything with Sublayouts, though.

  4. Really enjoying the blog so far Adam, its really helping me fully understand some of the fundamentals after training last week. Quick question though.

    Is there anything to be lost if you do not use renderings (WebControls) and just stick to nested SubLayouts (UserControls)? Im personnely not a great fan of UserControls as you usually end up with HTML in code which confuses the CSS team!

  5. Hi Steve. I don't think the decision to use web controls or sublayouts is really any different than the decision to use web controls or user controls in a regular ASP.NET site.

    As far as there being any specific Sitecore advantage to choosing one or the other, one thing that comes to mind is that with web controls you extend Sitecore.Web.UI.WebControl. This provides easy access to some values that might be hard to get to from a user control. But I think this advantage is only relevant in certain highly specialized cases.

  6. Hi Adam,

    I enjoy reading your post. So based on my understand that the components of a sublayout is .NET web user control file and not a .net web form file.


  7. I have a question regarding this topic. We have certain items stored in our proprietary databases that we need to grab and display to users in Sitecore sites. We have built a webcontrol (or series of) to handle this.

    What is the difference between dropping these controls into a layout/sublayout withouth adding them to Sitecore versus putting them in the sitecore Layout/Renderings folder?

    Also, since this data has nothing to do with Sitecore and simply returns a list of items to be displayed in some sort of grid/table etc, what would be the benefit of inheriting Sitecore. I guess what I'm really asking is what extra advantages do you get by inheriting Sitecore?



Note: Only a member of this blog may post a comment.