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 knowledgebase 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 knowledgebase 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 namePurpose
fullContent1This will be used to create a hyperlink to the details or “SingleItem” version of this content item.
fullContent2This is the same as fullContent1.
contentThis will be used to display your generic content.
CommentsLinkThis will be used to create a hyperlink to view the comments of the content
CommentsCountThis will be used to display the total number of comments on this content.
CategoryThis 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.
TagsFor this you will need an ASP.NET Repeater control and the content view control will place the tags used for
that content
BookmarksFor 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

Add the new provider

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

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

Paste this element onto the next line of the web config.

Change the following attributes.

AttributeValue
name<ModuleName>
urlRewriteFormatThe way you would like your URLs to look.
defaultMetaFieldThe 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.

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

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:

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 at http://www.sitefinity.com/help/developer-manual/telerik.cms.engine-telerik.cms.engine.metainfo_members.html.

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 nameNew Name
App_LocalResourcesAll 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.ascxProvides a drop down list of categories to choose from.
CategoriesManagement.ascxProvides the ability to add, remove and modify categories that are available to this generic content.
CategoriesSelector.ascxA control to select the categories to filter your records by.
CommandPanel.ascxThis control is what is displayed on the left hand side of the Sitefinity administration console.  You should
not need to modify this.
CommentsEdit.ascxA control that provides the ability to edit the comments of your generic content.
CommentsList.ascxA control that lists the comments for your generic content.
CommentsView.ascxA control that displays the individual comment of your generic content from the comments list control.
ContentSelector.ascxThis control provides a means to let you select generic content.
ContentVersionView.aspxThis is the control that will display the version history when you click on the version tab.
ControlPanelEdit.ascxThis is the admin control that allows you to edit your generic content.
ControlPanelInsert.ascxThis is the admin control that allows you to insert your generic content.
ControlPanelList.ascxThis is the admin control that displays the generic content available.
ControlPanelPermissions.ascxThis control provides the security controls for your generic content.
DesignFolder for the designer templates. I do not think these are used yet.
EditorTemplate.ascxNot sure of purpose.  Not sure of use.
NewContentDialog.ascxWhen you are creating page and you drag the Generic Content Module onto it, this is the dialog when you click
“Share this Content”
SelectContentDialog.ascxSame idea as above, but this is when you click on “Select Shared Content”
TagEditor.ascxThis control allows you to edit an individual tag
TagsManagement.ascxThis 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:

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.

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

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.

NameValue
AllContentItemsAll <ModuleName>
AuthorAuthor
CheckGenericContentFAQCheck <ModuleName> FAQs
Company_NameCompany name
CreateNewItemCreate a <ModuleName>
CreateYourFirstContentCreate your first <ModuleName>
CreateYourFirstContentTooltip<ModuleName>
DeleteDelete
DescriptionDescription
EditEdit
Forfor
NameName
NoContentNo <ModuleName> have been created yet.
Oror
Permissions FAQ
ProductProduct name
SearchSearch
SearchItemsBySearch <ModuleName> by
StatusStatus

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.

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

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.

NameValue
AdditionalInfoAdditional Info
AdditionalInfoNoteThis information is not public. It is for your reference only.
AuthorAuthor
AuthorInputAuthor…
BackToAllItemsCancel and go back
CancelCancel
CategoryCategory
Company_NameCompany name
Company_Name_Inputenter the company name …
Company_UrlCompany URL
Company_Url_Inputenter the company url …
ContentText
ContentEmptyThe text cannot be empty!
CreateThisItemCreate this discount
DescriptionDescription
DescriptionInputDescription…
DiscountDiscount
Discount_CodeDiscount code
Discount_Code_Inputenter the discount code …
Discount_Inputenter the discount …
GenericContentFAQDiscount FAQ
MandatoryFieldsMandatory fields
Oror
ProductProduct
Product_EmptyProduct cannot be empty!
Product_Inputenter the product …
Product_LabelProduct
Product_Logo_UrlProduct Url
Product_Logo_Url_Inputenter the product url …
SaveSave
TagsTags

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

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.

NameValues
AdditionalInfoAdditional info
AdditionalInfoNoteThis information is not public. It is for your reference only.
AuthorAuthor
AuthorInputAuthor…
BackToAllItemsBack to all <
ModuleName>
CancelCancel
CategoryCategory
ChangeLanguageChange Language
Company_NameCompany name
Company_UrlCompany URL
ContentText
ContentEmptyThe text cannot be empty!
DateDate
DescriptionDescription
DescriptionInputDescription…
DiscountDiscount
Discount_CodeDiscount code
EditEdit
EditThisItemEdit this discount
GenericContentFAQDiscount FAQ
HistoryHistory
IsEditingContentis editing this <ModuleName> now!
ItemVersions<ModuleName> Versions
MandatoryFieldsMandatory fields
ModifierModifier
NameName
NameEmptyName cannot be empty!
NameInputName…
Oror
ProductProduct
Product_EmptyProduct name cannot be empty!
Product_InputProduct…
Product_Logo_UrlProduct Url
RollbackRollback
SaveSave
SaveChangesSave changes
TagsTags
VersionVersion
VersionDateFormat{0:dd MMM yyyy, hh:mm}
ViewView

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

FilenamePurpose
ArchiveTemplate.ascxI think this is a holdover from the original News module.  We will not be using it.
CategoriesList.ascxThis is the control that will display the categories for your content.
CommentsList.ascxThis 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.xmlThis contains the different social bookmarking sites available.
TagsList.ascxThis 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 genericConentCommonLayout.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.

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.

<ModuleName>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 link this.

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.

CategoryPropertyValue
AppearanceItemListTemplatePathThis should point to the ContentViewItemList.ascx file that you modified earlier.

Example:

~/Sitefinity/ControlTemplates/<ModuleName>/ContentViewItemList.ascx

AppearanceSingleItemListTemplatePathThis should point to the ContentViewSingleItem.ascx file that you modified earlier.

Example:

~/Sitefinity/ControlTemplates/<ModuleName>/ContentViewSingleItem.ascx

DataProviderName<ModuleName>
Explicit LinksSingleItemUrlThis should point to the name of the page that the control is on.

~/<ModuleName>.aspx

Social BookmarksSocialBookmarkImageFolder~/Sitefinity/ControlTemplates/<ModuleName>/SocialBookmark/
Social BookmarksSocialBookmarkTemplate~/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.

The source can be downloaded at http://www.josephguadagno.net/documents/NewGenericContentSource.zip

This document can be downloaded at http://www.josephguadagno.net/documents/CreatingANewGenericContentModule.doc

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

Leave a Reply