Custom Item Generator

As our first official Velir blog post we wanted to introduce a tool that we’ve recently committed to the Sitecore shared source repository, the Custom Item Generator.  If you want to skip the introduction you can find the module here at http://marketplace.sitecore.net/en/Modules/Custom_Item_Generator.aspx

When we started developing for Sitecore we ran into the common issue of how best to structure our project code, specifically how to organize code used for accessing items and the content stored in their fields. Putting this code in code behinds, which seems to be a somewhat common practice, often leads to sites that are not well structured and are very difficult to maintain.  Around this time we happened upon a blog post by Alexey Rusakov talking about the Sitecore provided custom item classes.  Reading through the blog post we realized this approach solved many of the issues we were trying to solve (I would link to said post here, but I cannot seem to find it any more). Custom items are used by Sitecore in the API to wrap access to various Sitecore provided templates, two examples would be MediaItem and TemplateItem. We took this idea, expanded it a bit for our own uses, and created a tool to generate the custom item class files and thus the Custom Item Generator was born.

Introduction to Custom Item Pattern

Below is a very basic example of accessing an item using a field name.  Say we have a Publication item with a Title field that we want to display, without a custom item it might look something like this

Item pubItem = sitecoreDb.GetItem("{PubGuid}");
litTitle.Text = pubItem[“Title”];

Whereas with a custom item, the code would look like this

PublicationItem pubItem = sitecoreDb.GetItem("{PubGuid}");
litTitle.Text = pubItem.Title.Rendered;

The above example, while simple, highlights some of the advantages of using custom items to wrap templates and the fields contained within them.

• Code Structure - One of the main benefits of using custom items to wrap access to templates is that it creates a sensible structure for template based code.  This structure is extremely valuable in team based development and allows new Sitecore developers to come up to speed quickly.
• Field Name Safety - In the above non custom item example we need to know the exact name of the title field.  If that field name was changed in the Sitecore template, the project will still compile, but we would receive a runtime error when accessing the field.  By wrapping the reference to the field in a custom item we only need to update the field name in one location.
• Convienent Type Casting - Often times it is helpful to cast field values to a specific type.  Easy examples would be casting an Integer field value to an int, or returning a List of items from the many list based Sitecore fields.
• Ease of Maintenance - Centralizing template logic helps eliminate duplicate code and reduces the guess work needed to determine where certain code is located in the system.  This dramatically eases maintenance over the long term, especially when bringing in less experienced Sitecore developers.

Velir Custom Item Overview

At a base level our approach to the custom items is similar to Sitecore's, however we have also made some additions to our custom items to make them even easier to work with.

Field Access

For each kind of field we have created custom field classes to provide alternate ways to get at a field’s value. For example the Publication item mentioned earlier will have the following options:

• FieldName.Rendered – This will access the field through the Sitecore field renderer, in most cases where you are displaying a field’s content on the front end you would want to use .Rendered.
• FieldName.Raw – This will return the underlying value that is being stored in the field.
• FieldName.Field – This will allow you to access the underlying Sitecore provided field object.

In addition to the above we also provide a convenience property based on the type of field.  A good example of this can be seen accessing an Image URL

String imageUrl = pubItem.Image.MediaUrl;

Partial Classes

For a variety of reasons we break our custom items down into partial classes, the breakdown is this:

• .base.cs – This is where the auto generated code goes.  No custom code should be placed in these classes since if they are regenerated the custom code would be overwritten.
• .instance.cs – Contains code related to a single instance of an item of the template.
• .interface.cs – Contains all interface implementations related to the template.
• .static.cs – Contains static methods related to the template.

By breaking the classes up this way we end up with much cleaner/smaller .cs files.  This setup also provides guidance as to where certain kinds of code should go.  Say for example a new developer comes into a project and needs to implement an interface for a specific custom item, with these partial class files there is no question as to where that code should be placed.

The Custom Item Generator (CIG)

When we first started working with custom items we were creating the class files by hand.  This process is both time intensive and very error prone.  As you might guess this sometimes lead to custom items that were out of sync with their related templates.  We realized that to fully integrate custom items into our development process, we were going to need a tool to generate the class files.

Version 0

The first version of the CIG was a basic web form held in a utilities folder in the web root.

Initially we just copied and pasted the generated code into a single manually created class file.  This process was still too slow, so we quickly replaced that with auto generating the class files. The main issues with this approach being:

• You had to leave Sitecore to generate the class files.
• You had to be careful not to overwrite code when you regenerated the custom items.
• It was not straightforward to create/recreate custom items for folders full of templates.

Version 1

To solve some of the issues we made the following changes to the CIG:

• Added the ability to create the custom items from the Sitecore UI.
• Broke the custom item classes into partial classes.  This allows us to recreate the .base.cs file without worrying about overwriting custom code.

Now to create custom items it is simply a matter of going to the templates folder, right clicking on the template/folder of templates we wish to create, and click generate.

Where We Go From Here

We have been developing sites using custom items with the Custom Item Generator for the last few years, and we have found this setup to work very well.  Using the tool makes the code creation simple and quick, and the structure provided by this approach has helped us to keep our sites maintainable and flexible.

In the near future we will be doing more posts covering some custom item examples as well as ways that the Custom Item Generator can be extended.  Hopefully this post combined with the shared source wiki page will be enough information to get you started using the tool. We are very interested in feedback from the Sitecore community, so please send any comments/questions/suggestions to [email protected].