Folder Widgets

Web Pages CMS comes with a number of folder widgets, and it is expected that more folder widgets will be made available over time. Folder widgets are used for managing dynamic HTML and for injecting content that requires <script> tags into a page safely. 

Placing folder widgets

Click the Place Folder Widgets link and choose a folder widget from the dropdown list.

Choose widget

You will be presented with a series of dropdowns and inputs so that you can canfigure the folder widget.

Configure Widget

When you select a layout, you may also be presented with additional inputs depending on whether the widget allows further configuration. The standard Footer widget does not. It simply contains a copyright mark and the year is generated dynamically. The Google Analytics widget on the other hand, requires a value (or an "argument") that represents the ID of the web property that the analytics code should track. Accordingly, an extra field appears to capture this information.

Google Analytics Widget

Some widgets, like the Flash Video widget, require considerably more information to be provided so that they can work.

Certain fields are common to all folder widgets: you must select a layer and a zone so that the widget can be placed in the correct position on the required pages. You can also specify a display order so that it appears in the correct order alongside other widgets. Widget are displayed in ascending order.

Creating folder widgets

You may have noticed that there is no Create Folder Widget link in the administration panel, like there is for HTML widgets and Menu widgets. This is because folder widgets are not stored in the database like HTML widgets and Menus. They are created completely outside of Web Pages CMS and then added to the Widgets folder.

A folder widget consists of the following elements:

  • A housing folder
  • A .cshtml file
  • Optionally, a widget.info file

You can name the folder anything you like so long as it is a valid Windows directory name. It will be used to identify your widget. By way of example, here's how to create a footer that includes a copyright and the name of a site, which can be set dynamically through an argument. The folder widget can be called "Custom Footer", so this is the name to give to the actual folder. 

The .cshtml file is a partial Razor file. It contains a snippet of HTML and Razor syntax that represents what is to be rendered to the browser. You can learn more about Razor syntax and the ASP.NET Web Pages Framework at www.asp.net/web-pages. Since the file is a partial, the file name should be prefixed with an underscore which prevents it from being browsed directly. The file can be called anything, but it makes sense to name it after the folder, removing any spaces. In this case, the file will be called _CustomerFooter.cshtml

The content of _CustomFooter.cshtml is as follows:

@{
    var args = HttpUtility.ParseQueryString((string)Page.Args);
    var siteName = args["siteName"];
}
&copy; @DateTime.Now.Year @siteName. All rights reserved.

Since this widget requires an argument, it also requires a widget.info file. Here is the content of that:

<?xml version="1.0" encoding="utf-8" ?>
<widget>
    <name>Custom Footer</name>
    <description>Footer incorporating copyright notice and site name</description>
    <params>
        <param>
            <name>siteName</name>
            <fieldname>Site Name</fieldname>
            <type>string</type>
            <default></default>
            <description>Your site name</description>
            <required>true</required>
        </param>
    </params>
</widget>

This is a standard XML file. It contains a root element - widget - and a name and description of the widget. Then it contains a collection of param nodes. In this case, there is only one. It has a "name" which is used in code. Conventionally, Camel Casing is used for argument or parameter names. The first letter is lower case, then if other words are used in the name, these are concatentated together but start with an upper case letter. The "fieldname" node value is used as a  label on forms for the argument.

The data type of accepted values is described in the "type" node. Valid types are string, int and bool. If the type is set as int, it will be validated when the form is submitted for numbers only. If you choose bool as the type, the form field will be rendered as a checkbox.

Any default value can be provided in the "default" node. If you specify that a bool has a default value of true, the checkbox will be checked by default when rendered.

If you provide a value for the "description" node, this will be used as helper text when the form field is rendered. It will appear as a note just under the corresponding input.

Finally, if you specify that the parameter is required by setting the "required" node's value to "true", the presence of a value will be checked when the form is submitted.

Going back the the .cshtml file, the param values provided when configuring the widget are stored in name/value pairs in a variable called Page.Args, which are then retrieved using the HttpUtility.ParseQueryString() utility method. Finally, Razor syntax is used to generate the rendered output.