Zach Winnie
May 14, 2015

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

Zach Winnie

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:

/App_Data/Sitefinity/WebsiteTemplates/MyTheme/LayoutWidgets/Bootstrap/Bootstrap3_1Col_Col12.ascx

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">
        </div>
    </div>
</div>

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>
    </div>
    <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>
    </div>
    <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>
    </div>
    <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">
        </div>
    </div>
</div>

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">
            <sections>
                <add ordinal="1" name="TwoColumns" />
                <add enabled="True" title="Bootstrap 3 Columns" description="Twitter Bootstrap 3 Layout Widgets" ordinal="0" name="Bootstrap3">
                    <tools>
                        <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" />
                    </tools>
                </add>
            </sections>
        </toolbox>

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.

Conclusion

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.

Resources

5 Comments

  1. 5 Donald Bickel 14 May
    Using the Layout Widgets with Bootstrap and living soundly within the powers of Sitefinity has been a nice move forward for us.  Keeping the markup and CSS cleaner but bringing RWD, Bootstrap, grid layouts and Sitefinity has been a big win.
  2. 4 Chris 14 May
    The Sitefinity Layout Widgets are awesome and the additional template flexibility is consistently appreciated by our clients.
  3. 3 Whitney Gainer 14 May
    I've grown quite fond of Layout widgets. Particularly for their usefulness with custom layouts. 

    You can make a layout for a particular list or unique page reusable by adding classes and a certain amount of extra's (i.e. text/content, extra divs for layout purposes). 

    This makes it easier for clients to duplicate more complex page and content layouts on the fly, and is particularly useful for more interactive pieces that require certain classes to function properly.

    I may go over an example of this in a future blog post, but this post is a great resource for understanding the basics and for getting started with adding your own layout widgets.
  4. 2 AJ 14 May
    Great Post! Not only are the custom layout widgets fantastic for interface design, App Dev's can benefit greatly from these too. Creating them as user controls allows both the .ascx file for design and .cs file for backend development. This allows for various ways to affect the widgets placed in the layout like hiding them from search indexes or altering their functionality at the template level. 
  5. 1 Britton 18 May
    The ability for a non-technical end-user of a Sitefinity site to be able to control columns and layouts while continuing  to customize their own content for responsive is one of the biggest advantages of Sitefinity over its competitors. 

Comment

  1. RadEditor - HTML WYSIWYG Editor. MS Word-like content editing experience thanks to a rich set of formatting tools, dropdowns, dialogs, system modules and built-in spell-check.
    RadEditor's components - toolbar, content area, modes and modules
       
    Toolbar's wrapper 
     
    Content area wrapper
    RadEditor's bottom area: Design, Html and Preview modes, Statistics module and resize handle.
    It contains RadEditor's Modes/views (HTML, Design and Preview), Statistics and Resizer
    Editor Mode buttonsStatistics moduleEditor resizer
      
    RadEditor's Modules - special tools used to provide extra information such as Tag Inspector, Real Time HTML Viewer, Tag Properties and other.
       

Subscribe to Our Blog

Get the latest blog posts sent right to your inbox so you never miss an informative post from Mercury.

 

Get Your Share On!

 

Tags