Using Custom Sitefinity Layout Widgets to Create a Responsive Design Grid System

Out of the box, Sitefinity comes with its own grid system that can be utilized to build the layout of your site or app. You can even use media queries in your theme CSS to mold this grid system into being responsive, if you want. Going this route is tricky though, and your media queries will quickly start to grow, become messy, and you’ll probably run into CSS inheritance issues that could break your layout in unwanted ways.

There is a better way that will solve your own interface development headaches and also provide ease of use for your Sitefinity end user to add layouts that are responsive. They are called Layout Widgets – essentially .ascx file that define the HTML of your responsive grid. You can have as many as you want and they are easy to add to your project via the Toolbox. Since you’re defining your own HTML, you can use any grid system you want – your own, Twitter Bootstrap, Zurb Foundation, or any other interface framework out there – and set any breakpoints you need. In this blog post I’ll walk you through the steps to add your own Layout Widgets, using the Twitter Bootstrap grid as an example.

Step 1: Create Your .ascx Files

These .ascx files can live anywhere in your project. Since the grid is closely tied to your CSS theme, I would recommend placing them in your theme folder. For example, your folder structure might look like this:


In this instance we’re creating a simple 100% width column with Bootstrap (version 3 specifically). The HTML of this file will look like this:

<%@ Control Language="C#" %>
<div runat="server" class="sf_cols row">
    <div runat="server" class="sf_colsOut sf_1col_1_100 col-xs-12">
        <div runat="server" class="sf_colsIn sf_1col_1in_100">

Notice we’re adding the Bootstrap classes (row, col-xs-12) to the already existing Sitefinity classes (sf_cols, sf_1col_1_100, sf_1col_1in_100). I’ve found it to be best to keep the Sitefinity classes intact – otherwise your layout widgets may not render correctly in the Sitefinity admin when editing a page or page template. Also, be careful of any HTML or text you place in these .ascx files, as it will appear on the front-end of your site anywhere you’ve used them.

A more complicated layout widget, with multiple columns and breakpoints, might look like this:

<%@ Control Language="C#" %>
<div runat="server" class="sf_cols row">
    <div runat="server" class="sf_colsOut sf_4cols_1_25 col-xs-12 col-sm-6 col-md-3">
        <div runat="server" class="sf_colsIn sf_4cols_1in_25">
    <div runat="server" class="sf_colsOut sf_4cols_2_25 col-xs-12 col-sm-6 col-md-3">
        <div runat="server" class="sf_colsIn sf_4cols_2in_25">
    <div runat="server" class="sf_colsOut sf_4cols_3_25 col-xs-12 col-sm-6 col-md-3">
        <div runat="server" class="sf_colsIn sf_4cols_3in_25">
    <div runat="server" class="sf_colsOut sf_4cols_4_25 col-xs-12 col-sm-6 col-md-3">
        <div runat="server" class="sf_colsIn sf_4cols_4in_25">

Again, we’re adding our CSS grid classes after Sitefinity’s classes. The difference here is that we have four columns in this layout. We’ve also set three different breakpoints using Bootstrap’s grid — col-xs-12 col-sm-6 col-md-3 — which means the columns will be 100%/one column and stack on a smartphone, be 50%/two columns at tablet sizes, and be 25%/four columns on small desktop and larger screens.

Step 2: Add Your Layout Widgets to the Toolbox

I recommend that you add your Layout Widgets to the ToolboxesConfig.config file manually. The benefit to doing it this way instead of through the Sitefinity admin screens, is that the ToolboxesConfig.config file can be checked into your source control solution, and will ensure your Layout Widgets appear locally, in your staging environment(s), and in your production environment.

The Toolbox file is located in /App_Data/Sitefinity/Configuration/ToolboxesConfig.config. In this file, before the ending tag, is where you’ll be adding your layout widgets. Using our two layout widgets above, the code you’ll need to add is below:

<toolbox name="PageLayouts">
                <add ordinal="1" name="TwoColumns" />
                <add enabled="True" title="Bootstrap 3 Columns" description="Twitter Bootstrap 3 Layout Widgets" ordinal="0" name="Bootstrap3">
                        <add enabled="True" type="Telerik.Sitefinity.Web.UI.LayoutControl" title="100%" description="1 Column (col-12)" cssClass="sfL100" layoutTemplate="~/App_Data/Sitefinity/WebsiteTemplates/MyTheme/LayoutWidgets/Bootstrap/Bootstrap3_1Col_Col12.ascx " visibilityMode="None" name="Bootstrap3_1Col_Col12" />
                        <add enabled="True" type="Telerik.Sitefinity.Web.UI.LayoutControl" title="4x 25%" description="4 Columns (col-3 + col-3 + col-3 + col-3)" cssClass="sfL25_25_25_25" layoutTemplate="~/App_Data/Sitefinity/WebsiteTemplates/MyTheme/LayoutWidgets/Bootstrap/Bootstrap3_4Col_Col3-3-3-3.ascx" visibilityMode="None" name="Bootstrap3_4Col_Col3-3-3-3" />

Here’s the breakdown of the code:

toolbox name=”PageLayouts” and section tags are required, and is the location in which you’ll add all of your layout widgets. The add and tools tags are required to declare your layout widgets.

The first add tag adds a grouping of layout widgets. You can have as many of these as you want, as long as they have a unique name. The ordinal attribute is also important, as that is the sort order if you have more than one set of layout widgets. (In this case, we have two – and we’re telling the build in Sitefinity widgets to come second below our Bootstrap widgets.) The title attribute will correspond to what you see in the Sitefinity admin.

The inner add tags each declare the layout widgets for this group. Again, the title attribute corresponds to the text you see in the Sitefinity admin. Additionally, the description attribute will add a tooltip to the layout widget giving the admin user more clarification. Make sure your path to your layout widget is correct, otherwise you may encounter errors.

If we take the time to add a full complement of responsive layout controls, what appears in the Sitefinity admin will look like the screen capture below:

Sitefinity Layout Options

Since our custom Bootstrap grouping was declared with an ordinal of 0 (zero), it appears at the top and is open by default.


Layout widgets should be a go-to resource for any interface designer working with Sitefinity. We’ve incorporated them into our Sitefinity projects at Mercury with great success — it allows designers to provide our clients with responsive site or app layouts with fewer problems and without sacrificing any control. Additionally, you could provide even more value to your clients by adding in a number of page templates using your custom layout widgets to get them started when they are adding a new page or page template.


No Comments

Leave a Comment

Your email address will not be published. Required fields are marked *