Using conditional templates in your custom widgets

Using conditional templates in your custom widgets

April 20, 2012 0 Comments

The content you're reading is getting on in years
This post is on the older side and its content may be out of date.
Be sure to visit our blogs homepage for our latest news, updates and information.

As Sitefinity gets bigger as a software project, many small features that get implemented may stay unnoticed. While trying to solve problems, developers often provide solutions that may be used elsewhere, and not just the specific feature they are implementing. This is how design patterns are born. We do have a lot in the Sitefinity codebase that may not be very well known and used.

One such not-so-famous feature is called Conditional Templates and this blog post is an attempt to explain when and how you can use it in your custom development.

The problem

When implementing functionality as a separate widget, we often have a requirement of providing different user interface, depending on how the widget is used. This is very similar to having multiple widget templates. The different requirement is that you should be able to switch between them dynamically. Let me give a few examples.

  • A weather widget, which may display its user interface in several modes: current temperature, the current weather as an image, the current weather as text
  • A widget that displays a different chart: bar chart or pie chart
  • A widget that can display a value or be used to edit that value

All these cases can be generalized to something, which we will call modes. A mode is just one way of displaying the user interface of a widget.

The solution

I assure you we’ve had many cases like the above in Sitefinity. The solution that was implemented is called conditional templates. They give you the ability to work with multiple widget templates, but let you change them at runtime, depending on a property in the widget. They are not “real” widget templates, but rather different markup from the same template.

The reason this is not very well known is that out of the box it is only supported in the so called field controls, and those work only in the backend. Sitefinity custom development usually leans towards the frontend of a site, not extending Sitefinity’s backend itself. That’s quite normal, but it’s also very easy to use conditional templates for any kind of custom widget. Here’s how.

Create a custom widget and inherit from SimpleView

Let’s take the weather widget example mentioned above.

We recommend that you inherit from SimpleView when implementing custom widgets to be used in Sitefinity. There are a couple of methods and properties you need to override. Those include LayoutTemplateName and LayoutTemplatePath, and also InitializeControls. Instead of doing this manually, alternatively you can use Sitefinity Thunder and it will generate a widget with those overridden by default. For more info on Thunder, head over to the documentation. The final code for the newly created widget is the following:

Implement the property used as a condition

Instead of using strings, I’ll also implement an enumeration with all the modes our widget supports.

Once we have the enumeration, we add a property, whose value will represent the condition in our conditional templates. It will use the enum created above as a type.

Include a ConditionalTemplateContainer in the widget template

Now that we have a property showing the mode, we need to include the markup for each mode in the widget template. This is done by placing a conditional template container inside the template. You also need to register the required namespace Telerik.Sitefinity.Web.UI. Once we have the container on the page, adding a template for each mode is very similar to adding item templates in data-bound controls like the repeater. Here is the final markup

The three important attributes to remember for each conditional template are Left, Operator and Right. Those represent the condition to which the template corresponds. The case above could be translated in plain English as “If Mode is equal to Temperature” (then load the first template) or "If Mode is equal to Text” (load the second template). By setting the value of the Mode property, we can control which markup gets rendered by our widget. This approach is more readable, easier to debug and more structured than manually showing and hiding controls through code or CSS.

Override the CreateContainer method

Up until this point we have implemented our conditional templates. The only thing left to do is hook up the logic to make use of them. As I said above, this has already been done for field controls in Sitefinity. In order to do it in your widgets, you need to override the CreateContainer method. Inside its implementation, you should only call Evaluate() on the conditional template container. That call takes care of everything to initialize the template depending on the condition.

Once you are able to show conditional templates, you can put any markup inside them. The example displays static data, but you can easily use the Sitefinity API to bind to data inside the CMS or implement your own business logic. Then you can switch between the different markup by just setting the value of the Mode property.

You can download the source code of the example shown above from here.

I hope this feature makes you life easier when you encounter a similar need in your future Sitefinity development projects.


The Progress Team

View all posts from The Progress Team on the Progress blog. Connect with us about all things application development and deployment, data integration and digital business.

Comments are disabled in preview mode.
Latest Stories
in Your Inbox

Subscribe to get all the news, info and tutorials you need to build better business apps and sites

More From Progress
ProgressNEXT: Premier Event for Modern Application Development
Read More
Seven Reasons to Check Out Sitefinity 11.1
Read More
Getting Started with Your Omnichannel Content Strategy
Read More