Creating a new Sitefinity generic content module

So, I heard that the Sitefinity application had this generic content module that was pretty easy to use to create your own module with. Why do you need to create a new generic content based module you ask?  There a few answers to that question.  I created a new generic content based module because I wanted to track all of the discounts that were offered to the Southeast Valley .NET user group and since free time is a something I do not have lately, it was an easy choice.  You might also want to leverage the existing Sitefinity generic content module because you do not have any development resources available to.  As the name implies it is generic, so generic in fact, it is used by the blog feature, news feature and events feature. After a week’s worth of digging into the code and documentation, I was successful. So that you do not have to go through the pain, I will lay out the instructions for you.  This guide will require virtually no coding, just a little HTML markup, and some web.config changes. There are few steps involved in creating a new copy of the generic module. 

The first step is to BACKUP your web.config file and Sitefinity project, just to be safe.

Here is a list of other steps:

• Getting Started
• Modify the web.config file
• Create the new admin section
• Create the new control templates
• Add the data
• Create the Sitefinity page to display the content
• Summary

Document Conventions

Throughout this document, you will see the text <ModuleName>. Whenever you see this text you should replace the <ModuleName> with the new name of your module. For example, I created a discount module and whenever I saw <ModuleName> I replaced it with Discount.

Getting Started

There are two bugs in Sitefinity 3.2 Service Pack 2 hotfix 1616 that cause potential problems with using multiple generic control providers and the ContentView control.  Here are the posted fixes for them.

Multiple Providers Fix

This bug does not allow for you to select multiple generic content providers. To fix this issue, check out the Sitefinity knowledge base article titled Adding a custom provider for Generic Content

The Settings for ContentView controls are reset fix

To fix this issue, check out the Sitefinity knowledge base article titled Settings applied to the Content View based controls are reset

Resource Files

Sitefinity is built on top of the .NET framework, and this coding technology can localize text properties (and other attributes, such as tooltips) Within an ASP.NET page, you will see the string

<% $Resources:SearchItemsBy %>

This code tells the ASP.NET engine to get the resource file text in the key SearchItemsBy. This language is based on the page’s locale. If this text was on the ControlPanelInsert.ascx control, ASP.NET would look within the ControlPanelInsert.ascx.resx file, unless you had localized versions then it would look in ControlPanelInsert.ascx.<_locale_>.resx. For more information, please read Walkthrough: Using Resources for Localization with ASP.NET from MSDN. Keep this in mind while editing your Sitefinity controls later on.

ContentView Control Overview

The ContentView control in Sitefinity does most of the work for displaying generic content on a control or page. The ContentView control displays data on the web control by “looking” for control names that match the Meta field names within the provider. If you have a Meta field called Product then the ContentView control will look for a control on the page with the name Product and populate the control with the value of the Meta field. When the ContentView control sees a control with one of these names it will populate them with special functions.

Control name	Purpose
fullContent1	This will be used to create a hyperlink to the details or “SingleItem” version of this content item.
fullContent2	This is the same as fullContent1.
content	This will be used to display your generic content.
CommentsLink	This will be used to create a hyperlink to view the comments of the content
CommentsCount	This will be used to display the total number of comments on this content.
Category	This will be used to display the category of the content. If this is a hyperlink control, the contentview control, will place a hyperlink on the page that will allow you to view all of the content classified in that category.
Tags	For this you will need an ASP.NET Repeater control and the content view control will place the tags used for that content
Bookmarks	For this you will need an ASP.NET Repeater control and the content view control will place the tags used for that content

The ContentView control has two properties under the appearance section that tell it what control to display on the web page when you are in List mode or Single Item mode. These two properties are ItemListTemplatePath and SingleItemTemplatePath, respectively.

Modify the web.config file

Warning Before you begin, BACKUP your web.config. The smallest error or unclosed angle bracket will cause your Sitefinity application to stop working.

Add the new provider

Locate the section in your web.config file that is titled cmsProvider. It looks something like this

<cmsEngine defaultProvider="Generic_Content">

Copy the element (section) whose name is Generic_Content. It should look something like this

<add name="Generic_Content"
  urlRewriteFormat="[Publication_Date]/[Title].aspx"
  urlDateTimeFormat="yy-MM-dd"
  urlWhitespaceChar="_"
  visible="True"
  defaultMetaField="Name"
  securityProviderName=""
  allowLocalization="False"
  allowVersioning="True"
  allowWorkflow="False"
  allowComments="false"
  commentsModeration="true"
  versioningProviderName=""
  connectionStringName="GenericContentConnection"
  type="Telerik.Cms.Engine.Data.Providers.DefaultProvider, Telerik.Cms.Engine.Data"/>

Paste this element onto the next line of the web config. Change the following attributes.

Attribute	Value
name	<ModuleName>
urlRewriteFormat	The way you would like your URLs to look.
defaultMetaField	The name of the default meta field. Note: This must match a value in the meta field that you create later; otherwise you will get a difficult to debug “The given key is not present in the dictionary” exception.

The urlRewriteFormat field can comprise of any of your Meta field names.  It my case, I created the following.

urlRewriteFormat="/[Company_Name]/[Product].aspx"

All of the other fields you are free to do with as you choose.  Here is the sample Discount provider.

<add name="Discounts"
  urlRewriteFormat="/[Company_Name]/[Product].aspx"
  urlDateTimeFormat="yy-MM-dd"
  urlWhitespaceChar="_"
  visible="True"
  applicationName="/Discounts"
  defaultMetaField="Product"
  securityProviderName=""
  allowLocalization="False"
  allowVersioning="True"
  allowWorkflow="False"
  allowComments="false"
  commentsModeration="true"
  versioningProviderName=""
  connectionStringName="GenericContentConnection"
  type="Telerik.Cms.Engine.Data.Providers.DefaultProvider, Telerik.Cms.Engine.Data"/>

Add the new Meta fields

Further down in the web.config file, you should find an element, add Meta keys for each field for your new module. For the discount module, here is what I added:

<add key="Discounts.Product" valueType="ShortText" visible="True" searchable="True" sortable="True" defaultValue=""/>
<add key="Discounts.Company_Name" valueType="ShortText" visible="True" searchable="True" sortable="True" defaultValue=""/>
<add key="Discounts.Company_Url" valueType="ShortText" visible="True" searchable="False" sortable="False" defaultValue=""/>
<add key="Discounts.Product_Logo_Url" valueType="ShortText" visible="True" searchable="False" sortable="True" defaultValue=""/>
<add key="Discounts.Discount" valueType="ShortText" visible="True" searchable="False" sortable="False" defaultValue=""/>
<add key="Discounts.Discount_Code" valueType="ShortText" visible="True" searchable="False" sortable="True" defaultValue=""/>
<add key="Discounts.Category" valueType="ShortText" visible="True" searchable="True" sortable="True" defaultValue=""/>
<add key="Discounts.Author" valueType="ShortText" visible="True" searchable="True" sortable="True" defaultValue="Joseph Guadagno"/>

Please note that the name of the module and the word before the period must match the module name. For the Discounts Module provider I discussed, the name should be Discounts as shown below this sentence: The important part is for each property/field you want you to need to add a line. You will notice the format is “PropertyName”. For more information on the attributes, check out the Sitefinity developer’s documentation. Save your web.config and this completes all necessary changes to the file.

Create your new admin section

Create the folder structure

So you can interface with the Discounts Module, you will now need to create the template files by following these steps:

1. Open the Windows Explorer (or within Visual Studio).
2. Navigate to your website’s root directory.
3. Go to ~/Sitefinity/Admin/ControlTemplates folder.
4. Select the Generic_Content folder and paste it into the ~/Sitefinity/Admin/ControlTemplates directory.
5. Rename that folder to <ModuleName>. In my example, I renamed it to Discounts.

File List

Old name	New Name
App_LocalResources	All of the application resource files are found here. These files contain most notably the text properties for all of the controls on the template.  There should be one .resx for each .ascx file.  This is how .NET allows you to create localized versions of your applications.
CategoriesField.ascx	Provides a drop down list of categories to choose from.
CategoriesManagement.ascx	Provides the ability to add, remove and modify categories that are available to this generic content.
CategoriesSelector.ascx	A control to select the categories to filter your records by.
CommandPanel.ascx	This control is what is displayed on the left hand side of the Sitefinity administration console.  You should not need to modify this.
CommentsEdit.ascx	A control that provides the ability to edit the comments of your generic content.
CommentsList.ascx	A control that lists the comments for your generic content.
CommentsView.ascx	A control that displays the individual comment of your generic content from the comments list control.
ContentSelector.ascx	This control provides a means to let you select generic content.
ContentVersionView.aspx	This is the control that will display the version history when you click on the version tab.
ControlPanelEdit.ascx	This is the admin control that allows you to edit your generic content.
ControlPanelInsert.ascx	This is the admin control that allows you to insert your generic content.
ControlPanelList.ascx	This is the admin control that displays the generic content available.
ControlPanelPermissions.ascx	This control provides the security controls for your generic content.
Design	Folder for the designer templates. I do not think these are used yet.
EditorTemplate.ascx	Not sure of purpose.  Not sure of use.
NewContentDialog.ascx	When you are creating page and you drag the Generic Content Module onto it, this is the dialog when you click “Share this Content”
SelectContentDialog.ascx	Same idea as above, but this is when you click on “Select Shared Content”
TagEditor.ascx	This control allows you to edit an individual tag
TagsManagement.ascx	This control allows you to edit the tags available for your content.

Modify the admin files

There are three files that you are going to want to modify to accommodate your new Meta fields. They are ControlPanelList.ascx, ControlPanelInsert.ascx, and ControlPanelEdit.ascx.  I listed them in the order that they should be modified for testing.

ControlPanelList.ascx

As mentioned previously, the ControlPanelList.ascx control is used to display the generic content in the admin panel. Of the three controls, the List control is the least likely to need modification. This control has two divs called ToolsAll and workArea, which break up the workspace for listing the generic content.

ToolsAll contains the createNewButton, which allows you to create a new generic content item and the searchInputs section which allows you to search for generic content. The choices for the search criteria depend on whether you make the Meta data “searchable” in the web.config file. Here is an example:

<add key="Discounts.Product" searchable="True">

The div named “workArea” is broken up into three sections; gridTitle which provides the title for the grid, the GridView1 which will display the grid of generic content items, and an ASP.NET PlaceHolder control named emptyWindow, which displays text when there are no content items in this provider. If you would like to add a new provider with additional Meta fields, then you would need to add additional columns to GridView1 because this grid displays the meta fields.  These additional columns would help you narrow down the generic content that you want to modify.

<asp:GridView ID="GridView1">

To add a column to the grid control looks the Columns element, use the sample below this sentence:

<asp:BoundField DataField="Company_Name"
  SortExpression="Company_Name"
  HeaderText="<%$Resources:Company_Name %>"
  HeaderStyle-CssClass="GridHeader_SiteFinity" />
<asp:BoundField DataField="Author"
  SortExpression="Author"
  HeaderText="<%$Resources:Author %>"
  HeaderStyle-CssClass="GridHeader_SiteFinity" />

In this sample, I removed the Description field because I am not using it. I added a Company_Name column because this was a new meta field I added to the web.config file. Be sure to remove any unused Meta data fields or else you will get a runtime exception.

ControlPanelList.ascx.resx

Here are the contents of the resource file with some modifications.

Name	Value
AllContentItems	All <ModuleName>
Author	Author
CheckGenericContentFAQ	Check <ModuleName> FAQs
Company_Name	Company name
CreateNewItem	Create a <ModuleName>
CreateYourFirstContent	Create your first <ModuleName>
CreateYourFirstContentTooltip	<ModuleName>
Delete	Delete
Description	Description
Edit	Edit
For	for
Name	Name
NoContent	No <ModuleName> have been created yet.
Or	or
	Permissions FAQ
Product	Product name
Search	Search
SearchItemsBy	Search <ModuleName> by
Status	Status

ControlPanelInsert.ascx

As mentioned previously, the ControlPanelInsert control is used to insert new generic content items for this provider.

Just like the ControlPanelList control, this control is broken up into two divs, ToolsAll and divWorkArea. The ToolsAll contains the “back to …” link and the divWorkArea contains everything else.

There are three parts to the “divWorkArea,” the sfMsg:MessageControl control which displays messages based on the success or failure of saving the content, the mainForm which provides the editing surface, and the info div, which displays the FAQ text.

The mainForm again provides the area for which you insert your generic content. Some things that you need to know.  All of the Meta data fields need to be within the control sfGCn:ContentMetaFields and the <ItemTemplate> sub element otherwise the Sitefinity engine will not save the values. The fieldset classes are used to group the content together. Here is a sample fieldset with the Meta data fields for the discount content provider.

<h3><asp:Literal runat="server" Text="<%$Resources:Discount %>"></asp:Literal></h3>
<fieldset class="set">
  <div class="setIn">
    <ol>
      <li class="author">
        <asp:Label ID="Label5″ AssociatedControlID="Company_Name" runat="server">
        <asp:Literal ID="Literal7″ runat="server" Text="<%$Resources:Company_Name %>"></asp:Literal>
        <em id="Em2″ runat="server"></em></asp:Label>
        <asp:TextBox ID="Company_Name" Text="<%$Resources:Company_Name_Input %>" runat="server"></asp:TextBox>
      </li>
      <li class="author">
        <asp:Label ID="Label6″ AssociatedControlID="Company_Url" runat="server">
        <asp:Literal ID="Literal8″ runat="server" Text="<%$Resources:Company_Url %>"></asp:Literal>
        <em id="Em3″ runat="server"></em></asp:Label>
        <asp:TextBox ID="Company_Url" Text="<%$Resources:Company_Url_Input %>" runat="server"></asp:TextBox>
      </li>
      <li class="author">
        <asp:Label ID="Label10″ AssociatedControlID="Product_Logo_Url" runat="server">
        <asp:Literal ID="Literal12″ runat="server" Text="<%$Resources:Product_Logo_Url %>"></asp:Literal>
        <em id="Em7″ runat="server"></em></asp:Label>
        <asp:TextBox ID="Product_Logo_Url" Text="<%$Resources:Product_Logo_Url_Input %>" runat="server"/>
      </li>
      <li class="author">
        <asp:Label ID="Label8″ AssociatedControlID="Discount" runat="server">
        <asp:Literal ID="Literal10″ runat="server" Text="<%$Resources:Discount %>"></asp:Literal>
        <em id="Em5″ runat="server"></em></asp:Label>
        <asp:TextBox ID="Discount" Text="<%$Resources:Discount_Input %>" runat="server"></asp:TextBox>
      </li>
      <li class="author">
        <asp:Label ID="Label9″ AssociatedControlID="Discount_Code" runat="server">
        <asp:Literal ID="Literal11″ runat="server" Text="<%$Resources:Discount_Code %>"></asp:Literal>
        <em id="Em6″ runat="server"></em></asp:Label>
        <asp:TextBox ID="Discount_Code" Text="<%$Resources:Discount_Code_Input %>" runat="server />
      </li>
    </ol>
  </div>
</fieldset>

Each of the individual field is wrapped in a li HTML tag. There is a label, and a TextBox for each Meta data field.

In order to display the categories for your specific generic content you will need to modify the

<sfCtg:CategoriesField ProviderName="<ModuleName>" ID="Category" runat="server" />

tag.  You will need to add the ProviderName attribute tag and add the name of your generic provider.

ControlPanelInsert.ascx.resx

Here are the contents of the ControlPanelInsert.ascx.resx file for the custom module. As you will notice, I created a resource entry for each of the Metadata fields created in the web.config file.

Name	Value
AdditionalInfo	Additional Info
AdditionalInfoNote	This information is not public. It is for your reference only.
Author	Author
AuthorInput	Author…
BackToAllItems	Cancel and go back
Cancel	Cancel
Category	Category
Company_Name	Company name
Company_Name_Input	enter the company name …
Company_Url	Company URL
Company_Url_Input	enter the company url …
Content	Text
ContentEmpty	The text cannot be empty!
CreateThisItem	Create this discount
Description	Description
DescriptionInput	Description…
Discount	Discount
Discount_Code	Discount code
Discount_Code_Input	enter the discount code …
Discount_Input	enter the discount …
GenericContentFAQ	Discount FAQ
MandatoryFields	Mandatory fields
Or	or
Product	Product
Product_Empty	Product cannot be empty!
Product_Input	enter the product …
Product_Label	Product
Product_Logo_Url	Product Url
Product_Logo_Url_Input	enter the product url …
Save	Save
Tags	Tags

ControlPanelEdit.ascx

As mentioned previously, the ControlPanelEdit control is used to edit existing generic content items for this provider.  You are also redirected to this control once the insert is successful. This control will need to be edited to include controls (textboxes, drop-down list, etc.) to edit the Metadata fields.

The ControlPanelEdit is very similar to the ControlPanelInsert except the ControlPanelEdit editing is wrapped in a radTS:RadMultiPage control. This RadMultiPage control allows you to display multiple pages or tabs on a single page by displaying one page and hiding the others.  The RadMultiPage page with the id of ViewPage displays the content and Metadata fields separately in a read-only mode. You will not need to edit this portion of the control or “page”.  The RadMultiPage page with this id of EditPage contains the editable part of the control.  This part of the control needs to be edited to add in the edit controls for each of your Metadata fields.  You will need to edit list similarly to the way the ControlPanelEdit.ascx file was updated.

In order to display the categories for your specific generic content you will need to modify the

<sfCtg:CategoriesField ProviderName="<ModuleName>" ID="Category" runat="server" />

tag.  You will need to add the ProviderName attribute tag and add the name of your generic provider.

ControlPanelEdit.ascx.resx

Here are the contents of the ControlPanelEdit.ascx.resx file for the custom module. As you will notice, I created a resource entry for each of the Metadata fields created in the web.config file.

Name	Values
AdditionalInfo	Additional info
AdditionalInfoNote	This information is not public. It is for your reference only.
Author	Author
AuthorInput	Author…
BackToAllItems	Back to all <ModuleName>
Cancel	Cancel
Category	Category
ChangeLanguage	Change Language
Company_Name	Company name
Company_Url	Company URL
Content	Text
ContentEmpty	The text cannot be empty!
Date	Date
Description	Description
DescriptionInput	Description…
Discount	Discount
Discount_Code	Discount code
Edit	Edit
EditThisItem	Edit this discount
GenericContentFAQ	Discount FAQ
History	History
IsEditingContent	is editing this `` now!
ItemVersions	<ModuleName> Versions
MandatoryFields	Mandatory fields
Modifier	Modifier
Name	Name
NameEmpty	Name cannot be empty!
NameInput	Name…
Or	or
Product	Product
Product_Empty	Product name cannot be empty!
Product_Input	Product…
Product_Logo_Url	Product Url
Rollback	Rollback
Save	Save
SaveChanges	Save changes
Tags	Tags
Version	Version
VersionDateFormat	{0:dd MMM yyyy, hh:mm}
View	View

Create the new control templates

The control templates are used for displaying the generic content on a user-facing page.

Create the folder structure

• Open up Windows Explorer (or within Visual Studio).
• Navigate to where your website files are.
• Then navigate to ~/Sitefinity/ ControlTemplates folder.
• Select the Generic_Content folder.
• Copy it
• Paste it into the ~/Sitefinity/ ControlTemplates folder. Windows Explorer will give it a new name.  Rename it to <ModuleName>.
• Copy the ~/Sitefinity/ControlTemplates/Events/SocialBookmark folder to ~/Sitefinity/ControlTemplates/<ModuleName> folder. For some reason, this was left out of the Sitefinity Generic_Content folder.

Here comes the fun part. Depending on your liking, you can rename some of the files in the ~/Sitefinity/ ControlTemplates/<ModuleName>.  Here is a list of the files that I would rename.

File List

Filename	Purpose
ArchiveTemplate.ascx	I think this is a holdover from the original News module.  We will not be using it.
CategoriesList.ascx	This is the control that will display the categories for your content.
CommentsList.ascx	This is the control that will display the comments.
ContentsViewItemList.ascx or <ModuleName>ItemList.ascx	This is the control that displays the content in a list form (multiple).
ContentsViewSingleItem.ascx or <ModuleName>SingleItem.ascx	This is the control that displays the content in a single item (details).
genericContentCommonLayout.css or <ModuleName>CommonLayout.css	This file contains the CSS rules for this module.
socialBookmarkTemplate.xml	This contains the different social bookmarking sites available.
TagsList.ascx	This control displays all of your tag for the content.

Most of the files do not need to be modified unless you want to.  We will concentrate on the ItemList and SingleItem files.  These files will need to be modified to display your Metadata fields.Modify the control template files

<ModuleName>ItemList.ascx

As mentioned above in the file list section above, the ItemList control will be used to display the content items in a “repeater” or list view. As a suggestion, I would print out or keep handy the web.config section so you type the Metadata field names.

Let’s get started. If you renamed the genericContentCommonLayout.css you will need to update the FileName attribute of the sfWeb:CssFileLink element to match the new name. It should look something link this.

<sfWeb:CssFileLink ID="CssFileLink1"
  FileName="~/Sitefinity/ControlTemplates/Discounts/discountsCommonLayout.css"
  Media="screen"
  runat="server" />

The rest of the changes pretty much come in the asp:Repeater control. You can change the display to look how you wish. If you want to use any of the special fields like Tags or Categories, refer to the ContentView control overview earlier in this document.

‘SingleItem.ascx'

As mentioned above in the file list section above, the SingleItem control will be used to display the content item. As a suggestion, I would print out or keep handy the web.config section so you type the Metadata field names.

Let’s get started. If you renamed the genericConentCommonLayout.css you will need to update the FileName attribute of the sfWeb:CssFileLink element to match the new name. It should look something like this.

<sfWeb:CssFileLink ID="CssFileLink1"
  FileName="~/Sitefinity/ControlTemplates/Discounts/discountsCommonLayout.css"
  Media="screen"
  runat="server" />

Everything will display within the first div. You can change the display to look how you wish. If you want to use any of the special fields like Tags or Categories, refer to the ContentView control overview earlier in this document.

Add the Data

With all of the pages saved you should be able to load the Sitefinity administration section, click on the Generic Content section to start your work.

Click the change group dropdown list and you should see the new content group available. Select the new <ModuleName> item and you will see the ControlPanelList.ascx control displayed to the right.

Click on the “Create a new content item”, the name might be different if you changed the CreateNewItem item in the ControlPanelList.ascx.resx file. You will then be displayed with the ControlPanelInsert.ascx control which will allow you to add the content.

Create the Sitefinity page to display the content

Please refer to the Sitefinity user guide section titled “Working with Web Pages” for details on how to add a page to Sitefinity. This section will cover the ContentView control specific changes, please review the Sitefinity use guide section “Working with user controls” for more information on adding controls to a page. In my sample, I created a page called <ModuleName>.aspx and added a ContentView control to the page, which can be found on the left-hand side of the Add Controls toolbox typically in the section named Generic Content. Once you do this click the Edit hyperlink to set the properties of the ContentView control.

Category	Property	Value
Appearance	ItemListTemplatePath	This should point to the ContentViewItemList.ascx file that you modified earlier. Example: ~/Sitefinity/ControlTemplates/<ModuleName>/ContentViewItemList.ascx
Appearance	SingleItemListTemplatePath	This should point to the ContentViewSingleItem.ascx file that you modified earlier. Example: ~/Sitefinity/ControlTemplates/<ModuleName>/ContentViewSingleItem.ascx
Data	ProviderName	<ModuleName>
Explicit Links	SingleItemUrl	This should point to the name of the page that the control is on. ~/<ModuleName>.aspx
Social Bookmarks	SocialBookmarkImageFolder	~/Sitefinity/ControlTemplates/<ModuleName>/SocialBookmark/
Social Bookmarks	SocialBookmarkTemplate	~/Sitefinity/ControlTemplates/<ModuleName>/socialBookmarkTemplate.xml

All of the other properties you can set to your liking.

Summary

As you can see, building your own generic content provider using the Sitefinity generic content module is easy.  Follow this guide and you could have your new module like Sponsors, Products, or Books built. This should be everything that you need to get started expanding the generic content module of the Sitefinity product to meet your needs.

If there are any questions or comments, shoot me an email at jguadagno@hotmail.com.

Thanks to Joseph Anderson of Telerik for providing some helpful comments on this document.