Getting to Know Sitecore

This Blog Has Moved

2010-06-25T09:30:00.002-04:00

Just wanted to let everyone know that as of this week, new posts to this blog can be located on the Sitecore Community, under Technical Blogs. Here's a direct link to this blog at its new home.

I've already posted a couple of articles:

Hope to see you there!

Keeping Media Metadata In Sync

2010-05-27T08:00:00.004-04:00

When media files are uploaded to Sitecore, a Sitecore item is created. This item represents the media file in Sitecore. When you want to display information about the media file, you are displaying information about the item. When the file is updated, Sitecore ensures that the fields on the item stay in sync with the file.

Well, Sitecore does this for fields it is aware of. This is handled by the Sitecore.Resources.Media.Media class (and the classes that inherit from it). Thanks to the ImageMedia class, when you upload an image file, the height and width are read. Sitecore does not include a class to handle Microsoft Word documents, so metadata from those files is NOT read.

Creating a class to read metadata from Word documents, or any other file, is not hard to do. Sitecore is already set up to allow it. You just need to write the code that can read the metadata from the media file. The Sitecore Experience blog has a post that explains how to do this.

But what if you want a change to go the other direction? What if you want to update the document title in a Word document using Sitecore? This is also possible, but requires a little more work. In this post I'm going to explain how to do this for a docx file.

Triggering code when the Sitecore item is saved
When the Sitecore item is changed, code needs to run that updates the corresponding media file. This is accomplished by hooking into the "item:saved" event in web.config (or other config file).

<events>
  <event name="item:saved">
      <handler type="Sitecore.Marketing.MediaLibrary.MediaItemSavedHandler, Sitecore.Marketing.MediaLibrary" method="OnItemSaved"/>
  </event>
</events>

And the MediaItemSavedHandler class must be defined. The rest of the code in this post goes inside this class.

public class MediaItemSavedHandler
{
   protected void OnItemSaved(object sender, EventArgs args)
   {
   }
}

Determining if the item represents a media file
Since this event handler applies to all items, it is important to determine if the item that was saved represents a media file. This can be accomplished by checking the item's template ID.

Item item = Event.ExtractParameter(args, 0) as Item;
bool isDocx = item.TemplateID.ToString().Equals("{7BB0411F-50CD-4C21-AD8F-1FCDE7C3AFFE}");
if (!isDocx)
{
    return;
}

Determining if the title has actually changed
Just because the item saved event is triggered doesn't mean it was triggered by a change to the title. The EventArgs parameter will indicate if the title has changed:

ItemChanges changes = Event.ExtractParameter(args, 1) as ItemChanges;
Field titleField = item.Fields["Title"];
bool hasTitleChanged = (changes.HasFieldsChanged && titleField != null && changes.IsFieldModified(titleField));
if (!hasTitleChanged)
{
    return;
}
MediaItem media = new MediaItem(item);

Updating the media file
Next you need to update the media file in Sitecore. Access to Sitecore media files is available through the WebDAV interface, but communicating with the WebDAV server is a topic for a separate post. I'm going to take the easy way out here: I'm going to read the current file to a temp file, update the temp file, then replace the file in Sitecore.

Additionally, I'm not going to include all of the code needed update the docx file. I'll show you how to read a file from the media library and how to write a file to the media library.

If you're familiar with how .NET handled I/O, there's not much to accessing the media file. Here is an example of how to read and write Sitecore media files.

protected string CreateTempFile(MediaItem media)
{
    string fileName = Path.GetTempFileName();
    using (FileStream file = new FileStream(fileName, FileMode.Open))
    {
        Stream stream = media.GetMediaStream();
        byte[] buffer = new byte[1024];
        int count = stream.Read(buffer, 0, 1024);
        while (count > 0)
        {
            file.Write(buffer, 0, count);
            count = stream.Read(buffer, 0, count);
        }
    }
    return fileName;
}

protected void ReplaceFileInSitecore(string fileName, MediaItem mediaItem)
{
    Media media = MediaManager.GetMedia(mediaItem);
    using (FileStream stream = new FileStream(fileName, FileMode.Open))
    {
        media.SetStream(stream, "docx");
    }
}

Want to learn more?

Content API Cookbook
Microsoft's Open XML SDK - classes that provide access to Open Office XML file format specifications, include docx files.

Browser Settings for Sitecore

2010-05-24T08:00:00.007-04:00

I am a big fan of using a virtualized development environment (I use VirtualBox). By running everything in a virtual machine, it's much easier to test systems, upgrade software, and keep my laptop from getting cluttered. For me, the greatest advantage of working in a virtual machine is that I can easily roll-back changes I've made.

But working in a virtual machine has resulted in me installing a lot more software than I would have otherwise. Today, most installers are pretty streamlined and don't require much more than a little patience.

Sometimes steps are required that cannot be handled by an installer and must be performed manually. One of my least favorite of these is Internet Explorer configurations.

Sitecore recommends Internet Explorer be configured in a certain way. The Internet Explorer Configuration Reference available on SDN explains how and why.

The following code can be copied into a reg file and run in order to set the browser settings recommended in the SDN reference. I'm including this information for demonstration purposes only. Use at your own risk.

UPDATED: 09/17/2010 - Certain revisions of Sitecore 6.2 and 6.3 may be easier to navigate if the option "allow script-initiated windows without size or position constraints" is disabled. The settings below set that value to enabled.

======

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings\Zones\2]
"2001"=dword:00000000
"2004"=dword:00000000
@=""
"DisplayName"="Trusted sites"
"PMDisplayName"="Trusted sites [Protected Mode]"
"Description"="This zone contains websites that you trust not to damage your computer or data."
"Icon"="inetcpl.cpl#00004480"
"LowIcon"="inetcpl.cpl#005424"
"CurrentLevel"=dword:00000000
"Flags"=dword:00000043
"1200"=dword:00000000
"1400"=dword:00000000
"2007"=dword:00010000
"MinLevel"=dword:00010000
"1A10"=dword:00000001
"1001"=dword:00000001
"1004"=dword:00000003
"1201"=dword:00000003
"1206"=dword:00000003
"1207"=dword:00000000
"1208"=dword:00000000
"1209"=dword:00000003
"120A"=dword:00000003
"120B"=dword:00000000
"1402"=dword:00000000
"1405"=dword:00000000
"1406"=dword:00000003
"1407"=dword:00000000
"1408"=dword:00000000
"1409"=dword:00000000
"1601"=dword:00000000
"1604"=dword:00000000
"1605"=dword:00000000
"1606"=dword:00000000
"1607"=dword:00000003
"1608"=dword:00000000
"1609"=dword:00000000
"160A"=dword:00000000
"1800"=dword:00000001
"1802"=dword:00000000
"1803"=dword:00000000
"1804"=dword:00000000
"1809"=dword:00000003
"1A00"=dword:00020000
"1A02"=dword:00000000
"1A03"=dword:00000000
"1A04"=dword:00000003
"1A05"=dword:00000001
"1A06"=dword:00000000
"1C00"=dword:00010000
"2000"=dword:00000000
"2005"=dword:00000000
"2100"=dword:00000000
"2101"=dword:00000000
"2102"=dword:00000000
"2103"=dword:00000000
"2104"=dword:00000000
"2105"=dword:00000000
"2106"=dword:00000000
"2200"=dword:00000003
"2201"=dword:00000000
"2300"=dword:00000001
"2301"=dword:00000003
"2400"=dword:00000000
"2401"=dword:00000000
"2402"=dword:00000000
"2600"=dword:00000000
"2700"=dword:00000000
"TemplateIndex"=dword:00011000
"1806"=dword:00000001
"2500"=dword:00000003

======

Authentication Using the TC Integration Module 1.1

2010-04-01T07:00:00.005-04:00

Happy April Fools Day. All things are subject to extra suspicion today, but I assure you this blog post is legit. Now then...

In my last post I walked through the installation process for the Telligent Community integration module for Sitecore. In this post I will cover the topic of how authentication works in a little more detail.

The majority of this post is just explanatory information. The instructions on how to get the integration to work (meaning how to get the 2 cookies created) are at the end. I put a "+" in front of those items in case you just want to get the integration to work and will worry about understanding it later :-)

Separate user accounts
Sitecore and TC maintain their own, separate user accounts. These accounts can stay in sync because they share the same user name. After the integration is configured, Sitecore should be used to manage accounts. This includes creating new accounts, setting passwords and assigning roles.

If you are using the integration module with an existing TC instance, the TC users need to be "migrated" to Sitecore. It's not a true migration because the user accounts will still exist in TC. What it does is creates corresponding accounts in Sitecore, so TC users can be authenticated by Sitecore.

Migrating existing TC users
Before you migrate existing TC users, be aware of a couple of things:

New accounts will be created in Sitecore.
All existing TC users will be migrated. The migration script does not currently support any kind of filtering to control which users are migrated.
Existing TC content is not modified in any way.
Existing TC users will be renamed in TC. The new user name will be the fully-qualified Sitecore user name. This is the combination of a domain with the user name, such as extranet\rickfielder.
Do not run the migration script more than one time.
Do not run the migration script if the integration is already in use (meaning Sitecore users have already logged into TC).

TC user migration script

To migrate existing TC users:

Log into Sitecore as an administrator.
Navigate to http://your-server/sitecore modules/Shell/CSSCIntegration/Security/csinstall.aspx.
Select the Sitecore domain the TC users should be created in.
Click the "move users" link.

TC user migration script output

The migration script generates 2 XML files. These files are written to "[sitecore web root]\sitecore modules\Shell\CSSCIntegration\Security":

MovedUsers.xml describes the new accounts created in Sitecore. This file contains the username and password for each migrated user. Be aware that passwords are XML-encoded and may not necessarily work if copied directly from this file.
FailedUsers.xml describes the TC users who could not be created in Sitecore.

Post-migration considerations
Unfortunately, the migration script doesn't provide any way for an administrator to specify any properties on the Sitecore users that get created. Aside from the Sitecore domain the users are added to. So if you want TC users to be assigned a certain Sitecore role, this is something that you must do manually after the migration.

Another thing to to consider after migrating users is that login, logout, password maintenance and new account creation are all handled by Sitecore. Since TC provides users the ability to do these things, you should hide those link in TC user interface.

Authentication in Sitecore
When using this integration, all authentication is handled by Sitecore. When a user navigates to TC, TC looks for some cookies that Sitecore has created in order to know

When a user logs into Sitecore, 2 cookies are created. These cookies identify that a user has been authenticated and extra information from Sitecore about the user. Since Sitecore and TC must be a part of the same domain, both cookies will be available to TC when the browser navigates to TC. So the user is not automatically logged into TC. Rather, the cookies are set so that when the user navigates to TC, TC can automatically log him in at that point.

The process by which these cookies are created is the same whether the user logs into a published Sitecore website or the Sitecore client - provided Sitecore is configured to create these cookies.

This is not done automatically. The design allows you to control if and when this happens. For example, you may want content authors to have access to TC but not website users. Later in this post I'm going to walk through the configuration needed in order to instruct Sitecore to create these cookies for both published Sitecore websites and the Sitecore client.

But what are these cookies and where do they come from?

Writing the authentication cookie
The first cookie is the authentication cookie. Sitecore creates a System.Web.Security.FormsAuthenticationTicket instance. This object identifies the user who has authenticated. It also contains some data that needs to be transmitted to TC. Specifically, it contains the TC roles that the TC user is assigned.

The name of the authentication cookie is specified in Sitecore's web.config file, in the "authentication" section. My Sitecore instance is configured to use the name ".CommunityServer".

If you're interested in seeing the code that creates the authentication cookie, look at the following:

assembly: Sitecore.CommunityServerSecurityIntegration.SitecoreSide.dll
namespace: Sitecore.CommunityServerSecurityIntegration.SitecoreSide
class: SecurityUtil
method: CreateCookies

Writing the user profile cookie
The second cookie is the user profile cookie. This cookie contains user profile values that are read from Sitecore and made available to TC, which sets those values on the corresponding TC user (or uses those values to create a new TC if one doesn't already exist).

The following is an example of the (unencrypted) user profile cookie value:

Email=Johnson@localhost.com&PublicEmail=Johnson@localhost.com&CommonName=John Johnson

The values that are set in this cookie are determined by the "mappedProfileProperties" section from the Sitecore configuration file "CommunityServerIntegration.config". The only exception is the "Email" value, which is transmitted automatically.

Reading the authentication cookie
When a user clicks a link that takes him to TC, the 2 cookies are available to TC. Just like Sitecore, TC is configured use an authentication cookie named ".CommunityServer".

The TC security extension that was configuring during installation specifies that TC should use the following class to handle forms authentication:

assembly: Sitecore.CommunityServerSecurityIntegration.CommunityServerSide.dll
namespace: Sitecore.CommunityServerSecurityIntegration.CommunityServerSide
class: SitecoreFormsAuthentication

The "ProcessRequest" method is responsible for reading the authentication cookie. After the method confirms that the cookie is valid, it reads the roles that were passed from Sitecore. This ensures the proper roles are assigned to the TC user.

TC handles adding and removing roles from users who already exist in TC, but what about users who don't? Remember, all user management is handled in Sitecore, so it's possible - and even likely - that a user will exist in Sitecore but not in TC. TC will automatically create a new user in this case and will set the roles on the user. The "PostCreateUser" method does this.

Reading the user profile cookie
The "ProcessRequest" method also reads the user profile cookie. It just checks to make sure a value has been set. The underlying TC security extension infrastructure takes the information in that cookie and uses it to create a TC user if necessary and to populate the TC user.

How does Sitecore know when - and if - to write the cookies?
You may not want every Sitecore user to have an account created in TC. Therefore, it is important that you retain some control over when the cookies are written. If no cookies are written, then no single sign-on to TC will occur. The cookies are only written if you want them to be. The next sections explain how to configure this.

+Configuring a Sitecore website to support single sign-on
Website can handle authentication in a variety of ways. This integration supports all of those. However your site's login logic works, add a call to the following method after it runs. This will cause Sitecore to create the 2 cookies that are required for single sign-on to TC:

assembly: Sitecore.CommunityServerSecurityIntegration.SitecoreSide.dll
namespace: Sitecore.CommunityServerSecurityIntegration.SitecoreSide
class: SecurityUtil
method: AfterLogin

You also need to ensure the cookies are deleted when the user logs out. Add the following method call before your code ends the user's session:

assembly: Sitecore.CommunityServerSecurityIntegration.SitecoreSide.dll
namespace: Sitecore.CommunityServerSecurityIntegration.SitecoreSide
class: SecurityUtil
method: Logout

+Configuring the Sitecore client to support single sign-on
Just like when supporting single sign-on from a published Sitecore website, when configuring single sign-on from the Sitecore client you need to instruct Sitecore to create (and delete) the 2 required cookies.

Hooking into Sitecore's authentication functionality is done by modifying the "loggedIn" and "logout" pipelines. These pipelines are defined in Sitecore's web.config file.

Add the following processor as the first step in the "loggedIn" pipeline:

<processor mode="on" type="Security.CreateCSCookieProcessor, Sitecore.CommunityServerSecurityIntegration.SitecoreSide" />

Add the following processor as the last step in the "logout" pipeline:

<processor mode="on" type="Security.RemoveCSCookieProcessor, Sitecore.CommunityServerSecurityIntegration.SitecoreSide" />

Next steps
After the integration module is installed and configured, it's pretty much smooth sailing. Accessing TC content can be handled in a number of way. I described the options in my introduction to the integration post.

Want to learn more?

Telligent Community integration module

Installing the TC Integration Module 1.1

2010-03-31T08:00:00.010-04:00

In my last post I provided an overview of the Telligent Community integration module for Sitecore. While the module comes with a lot of documentation - including instructions on how to install the module - sometimes it's helpful to have someone guide you through the process. That's what I'm going to do.

TC integration module architecture
Before I get into the actual installation instructions, it's important to understand what you're going to install. I will explain each section when I get to it, but here's a quick overview:

Authentication is handled by Sitecore using ASP.NET forms authentication.
Sitecore is responsible for creating an authentication cookie that TC uses to provide single sign-on.
Sitecore passes user information to TC so TC knows which roles the user has been assigned to.
TC content is exposed to Sitecore through a REST API.
Additions to the Sitecore client are installed using a Sitecore package.

Pre-requisites
Before you attempt to install the TC integration module version 1.1, be aware of the following:

You must be running Sitecore 6.1 or 6.2.
You must be running Telligent Community 5.0 SP1. Version 5.5 might work, but I haven't tested it to know for sure.
Sitecore and Telligent Community must be running in the website or TC must be running in a domain of the Sitecore server. For example, if TC is using the domain "tc.test-server.com", then Sitecore must be using the domain "test-server.com".
You must have read/write permissions on the folders in which Sitecore and TC are installed.
You must have the ability to upload files to the folder in which Sitecore and TC are installed.
You must have an administrator account on Sitecore and TC

If you have all of these things ready, you are safe to proceed. Don't be overwhelmed by the number of steps. It's not as bad as it may look :-)

Step 1 - Download the integration module.
The integration module can be downloaded from the Sitecore's SVN server. The easiest way to get the module is to use an SVN client for Visual Studio like AnkhSVN. You want to download the trunk code since this contains the latest bug fixes.

Step 2 (optional) - Compile the .NET assemblies.
You don't have to recompile the .NET assemblies, but I think it's a good idea because it will ensure that you are using the latest available code. Here's a description of each of the C# projects that make up the integration module so you understand what you are compiling:

Sitecore.CommunityServerSecurityIntegration.CommunityServerSide - This assembly is deployed to the TC server. It contains code to support single sign-on as well as extensions to TC's REST API.
Sitecore.CommunityServerSecurityIntegration.SitecoreSide - This assembly is deployed to the Sitecore server. It contains code that allows Sitecore to create the cookies that are used by TC and to migrate existing TC users into Sitecore.
Sitecore.CommunityServersIntegration.Controls - This assembly is deployed to the Sitecore server. It is where the components that are used to access TC content are defined.
CSComponentWizard - This assembly is deployed to the Sitecore server. It is where Sitecore client user interface additions are implemented.

Step 3 - Deploy assemblies to TC.
Copy the assembly "Sitecore.CommunityServerSecurityIntegration.CommunityServerSide.dll" to the TC server. The assembly should go in the bin folder.

Step 4 - Add a security extension in TC.
New functionality can be added to TC using extensions. A security extension allows TC to use cookies that are created by Sitecore for single sign-on.

In order to use an extension, TC must be configured to allow extensions to run. In the "communityserver.config" file in TC, set the following attribute:

node path:/CommunityServer/Core/extensionModules
attribute name: enabled
attribute value: true

Next you need to specify that TC should use a custom class to handle forms authentication. In the extensionModules node you just modified, find the FormsAuthentication security extension. Hint: look for <add name="FormsAuthentication"... Replace the node with the following:

<name="formsauthentication" name="FormsAuthentication" extensiontype="Security" type="Sitecore.CommunityServerSecurityIntegration.CommunityServerSide.SitecoreFormsAuthentication, Sitecore.CommunityServerSecurityIntegration.CommunityServerSide" allowautouserregistration="true" userprofilecookie="CSUserProfile" useencryptedcookie="false" profilerefreshinterval="1" />

Here's a breakdown of what the attributes mean:

name - The name of the extension you are configuring.
extensionType - TC supports a variety of extensions. This specifies that this extension deals with security.
type - The name of the class (and assembly) that implements the extension.
allowAutoUserRegistration - When a user logs in from Sitecore, an authentication cookie is created. TC uses that cookie to authenticate the user. If the user doesn't already exist in TC, this setting instructs TC to create the user.
userProfileCookie - The name of the cookie that contains user profile information about the user who has been authenticated by Sitecore. TC uses the cookie's value to set values on the TC user. Later you will configure the setting in Sitecore that sets this value.
useEncryptedCookie -Specifies if the value saved in the userProfileCookie is encrypted. Later you will configure the setting in Sitecore that sets this value.
profileRefreshInterval - This value specifies the frequency with which TC will refresh user information. The unit is in days, with 1 being the minimal value.

Step 5 - Enable REST API in TC.
TC provides access to its content through a REST API. This API must be enabled before Sitecore can use it.

Log into TC using an administrator account.
Navigate to the TC control panel and click the "Site Administration" link.
Click the "Manage REST API" tab.
Make sure the "Yes" option is selected and click the "Save" button.

Step 6 - Generate an application key in TC.
Sitecore uses a TC admin account in order to retrieve content. For this to work, Sitecore needs the TC admin user name and an application key.

Log into TC using the admin account you intend to have Sitecore use.
Edit the user's settings.
Navigate to the "Site Options" tab.
Scroll to the bottom of the screen and click the "Create and Edit Application Keys" link.
In the "name" field enter "Sitecore" and click the "Generate" button.
Write down the API key that is generated. You will need this value when you configure the connection from Sitecore to TC.

Step 7 - Modify web handlers in TC.
This integration module allows Sitecore users to filter and repurpose TC content. In order to provide Sitecore users with a variety of ways to do this, TC's REST API had to be extended.

This step involves changing the web handlers that process the REST calls. These web handlers can be found in the api\ folder under TC. The following files need to be modified. The class name in each file needs to be changed to the value following the file name:

groups.ashx: CommunityServer.WebServices.Services.CSIGroupsService
mediagallery.ashx: CommunityServer.WebServices.Services.CSIMediaGalleriesService
membership.ashx: CommunityServer.WebServices.Services.CSIMembershipService
search.ashx: CommunityServer.WebServices.Services.CSISearchService

Step 8 - Install the integration module deployment package in Sitecore.
The deployment package is available in the file named "TCSC Integration - Sitecore side-1.1.x.zip". Install this package using the Sitecore Installation Wizard.

The package includes a number of Sitecore items and files that are copied to the filesystem. Some of those files are .NET assemblies. If you recompiled the assemblies earlier, you will want to copy those assemblies into the bin\ folder in Sitecore.

Step 9 - Add a connection string in Sitecore.
Since TC is an external system that Sitecore is connecting to, an entry for TC must be added to Sitecore's connectionstring.config file. Add the following to the configuration file:

<add name="tc" connectionstring="siteUrl=http://your-server.com/tc;username=admin;apiKey=c00y45fd" />

Of course, the specific values you enter here will be different than the ones above. Here's an explanation of the values in the connectionString attribute:

siteUrl - The base URL to your TC server. If you enter the URL in a browser you should be taken to the TC homepage.
username - The name of the TC administrator account that Sitecore uses to communicate with TC. This must be the same account you used earlier to generate the API key.
apiKey - The API key value you generated earlier.

Step 10 - Modify the integration module configuration file in Sitecore.
One of the files that is created by the deployment package is the integration module configuration file. This file is located in the folder "app_config/include/". The name of the file is "CommunityServerIntegration.config".

Locate the node "/configuration/sitecore/settings". This node defines the basic settings used by the integration module. Here's a description of the settings:

CS.ProfileCookie - Remember the "userProfileCookie" attribute in TC's "communityserver.config" file? This value must match that.
CS.EncryptProfile - This value must match the "useEncryptedCookie" attribute value from TC's "communityserver.config" file.
CS.ConnectionStringName - This value must match the name of the connection string you configured in Sitecore's "connectionstring.config" file.

Using the values I've already configured, this is what my settings node looks like:

<settings>
<setting name="CS.ProfileCookie" value="CSUserProfile" />
<setting name="CS.EncryptProfile" value="false" />
<setting name="CS.ConnectionStringName" value="tc" />
</settings>

Step 11 - Configure forms authentication settings in Sitecore.
In order for single sign-on to work, both Sitecore and TC must use forms authentication. Additionally, the forms authentication settings for both must match. Make sure the "authentication" node in Sitecore's "web.config" file matches the node in TC's "web.config" file.

The important part here is the the authentication form's name and domain match. Here's the authentication node from my installation:

<authentication mode="Forms">
<forms name=".CommunityServer" protection="All" timeout="60000" loginurl="login.aspx" slidingexpiration="true" domain=".nicam.com" />
</authentication>

The domain attribute is required if TC is running in a subdomain. The dot before the domain name is needed in order for the browser to use the same cookie when sending requests to either the domain or the subdomain.

Also - and this may be common knowledge among developers but it can't hurt to be repeated - be sure your domain has at least one dot in it already. The cookie will not be written if your domain is simply "nicam". It needs to be "nicam.com".

Step 12 - Ensure the machineKey values in Sitecore and TC match.
The "machineKey" settings is important when using forms authentication in ASP.NET. Both Sitecore and TC must have the same "machineKey" configuration.

This configuration can be found in web.config. If no "machineKey" configuration exists, it must be added. Online tools are available - like this one - to generate the required settings. After you generate the configuration, add it to web.config as the last tag before the closing "system.web" tag (</system.web>).

Step 13 (optional) - Configure role and property mappings from Sitecore to TC.
Sitecore's "CommunityServerIntegration.config" file contains 2 sections that allow Sitecore user settings to be mapped to TC user settings.

The first mapping section is "rolesCorrespondence". This section allows you to specify user roles in Sitecore but still take advantage of security in TC. Sitecore roles are mapped to TC roles.

When the authentication cookie is created, the Sitecore user's roles are checked against this setting. The names of the appropriate TC roles are set in the authentication cookie. When single sign-on happens in TC, the custom forms authentication class that TC uses reads the roles from the authentication cookie and adds those roles to the TC user.

The following is an example of role mapping:

<rolesCorrespondence>
<role communityserverrole="Employees" sitecorerole="sitecore\Author" />
<role communityserverrole="Visitors" sitecorerole="extranet\Nicam" />
</rolesCorrespondence>

The second mapping section is "mappedProfileProperties". This is where Sitecore user profile properties are mapped to TC user profile properties. These values are passed to TC through the user profile cookie.

<mappedProfileProperties>
<property communityserverproperty="PublicEmail" sitecoreproperty="Email">
<property communityserverproperty="CommonName" sitecoreproperty="FullName">
</mappedProfileProperties>

Step 14 - Enable the HTML editor for display templates
Display templates determine how content retrieved from TC by the community component is formatted. Sitecore users are able control this presentation by using a rich text editor to edit display templates.

A couple of changes to the Sitecore file "/sitecore/shell/Controls/Rich Text Editor/Default.aspx" are required:

Change the "Inherits" attribute to "Sitecore.CommunityServerIntegration.Editors.CSRADEditor". This class extends the standard Sitecore rich text editor to support the dropdown list that allows an editor to select the specific TC content fields to display.
At the bottom of the file, add a link to the Javascript file "/sitecore modules/Shell/CSSCIntegration/RichText Commands.js". It is important that this be the last Javascript file that the browser loads. Otherwise the code in the file may be overriden by another script.

Next steps
The integration module is installed, but there's more work to do. Since Sitecore is handling authentication and is responsible for role management, existing TC users must be migrated into Sitecore. Also, Sitecore needs to be configured to create the cookies (authentication and user profile) that TC needs in order to sign a user in. I will cover these topics in my next post.

Want to learn more?

Introduction to Telligent Community Integration Module for Sitecore

2010-03-29T21:00:00.004-04:00

The Sitecore Shared Source Library has a lot of interesting and useful projects that are available for free. In this post I want to introduce the Telligent Community integration module. I will explain what the module does and show that it looks like in action.

Sitecore website that incorporates Telligent Community content.

For those of you who don't know, Telligent Community is a .NET-based system for building and maintaining communities. Inside Telligent Community, applications provide blog, wiki, forum and media gallery functionality.

So what does this integration do? Two things. The first is integrated security. Single sign-on between Sitecore and TC is supported. Sitecore can be used to manage TC users and roles.

The second is the ability to repurpose TC content in Sitecore. The integration provides a variety of ways to incorporate TC content into a Sitecore website, including a wizard that allows Page Editor users to select the TC content they want to use. It also provides a variety of ways to control how that content is presented, including a rich-text editor for building display templates.

I will save the technical details on how all this works for later posts. For now I want to focus on what the integration does rather than how it does it. The easiest way to do this is through some videos. And if you're only going to watch one video, I suggest video #2.

Video 1: Security integration features
This video covers the module's security integration features. It demonstrates how single sign-on works and how Sitecore is used for role management.

Security integration using the TC integration module 1.1.

Video 2: Content repurposing
The integration module provides a number of ways to repurpose content. This video explains these options. It also covers the "community component", which is a Sitecore control that allows Sitecore content authors to repurpose Telligent Community content through a wizard interface.

Content repurposing using the TC integration module 1.1.

Video 3: Controlling presentation logic
This video demonstrates how the integration module allows custom presentation logic to be defined in Sitecore and applied to Telligent Community content.

Controlling presentation logic using the TC integration module 1.1.

Want to learn more?

Sitecore Shared Source Library
Telligent Community Integration Module - You can download the source code, installation files and documentation here.
Sitecore Shared Source Weblog - This blog is written by Sitecore's Shared Source Coordinator. It's a great source of information on what's going on in the Shared Source world.

Custom Fields, Part 3

2010-03-25T08:00:00.009-04:00

In my last post I explained how to create a custom user interface for editing a name in Page Editor. I left off suggesting that there's a problem with the current implementation. And there is: it is possible to circumvent the user interface by using the inline editing feature provided by the default field renderer.

Inline editing circumvents my new user interface.

Why is that happening? Well, as far inline editing is concerned, Sitecore doesn't have any special instructions on how to handle a name field. Therefore, Sitecore treats the field like a single-line text field.

Since I created this special user interface to handle the name field, I want Sitecore to use that interface. And while in some cases being able to use inline editing to modify a field value may be advantageous, in this case I want it disabled.

In this post I'm going to cover 3 items:

Creating a custom field type to make it easier to work with the components of a name (currently only first and last names, but could later be expanded to more).
Controlling how the standard Field Renderer web control behaves when it is used to render a custom field.
Configuring a custom field renderer control to make it easier to configure the display formatting for a name field

Step 1 - Create new field type
My first step it to create a new field type. This will make it much easier for people working with the Sitecore API to work with name fields. Since I will need to work with field names in a later step, I will be the first person to benefit from this addition.

Also, this code will serve as a replacement for the NameFieldUtils class. Same logic, different location.

public class NameFieldType : CustomField
{
 public static string GetFullName(string firstName, string lastName)
 {
     var name = new string[2];
     name[0] = firstName;
     name[1] = lastName;
     return String.Join(" ", name);
 }
 public static string GetFirstName(string fullName)
 {
     string[] parts = fullName.Split(' ');
     if (parts.Length >= 1)
     {
         return parts[0];
     }
     return string.Empty;
 }
 public static string GetLastName(string fullName)
 {
     string[] parts = fullName.Split(' ');
     if (parts.Length >= 2)
         return parts[1];
     return string.Empty;
 }
 public NameFieldType(Field innerField) : base(innerField) { }

 public static implicit operator NameFieldType(Field field)
 {
     if (field != null)
         return new NameFieldType(field);
     return null;
 }

 public string FirstName
 {
     get { return NameFieldType.GetFirstName(InnerField.Value); }
 }

 public string LastName
 {
     get { return NameFieldType.GetLastName(InnerField.Value); }
 }
 public string FullName
 {
     get { return InnerField.Value; }
 }
}

Step 2 - Register new field type
When working with content using the Sitecore API, a class is used. Different classes support different types of field. Sitecore needs to know which class should be used for which field type. This mapping is specified in the FieldTypes.config file.

In order for Sitecore to be able to resolve the "Name Field" type to the NameFieldType class I just created, I need to add the following to the FieldTypes.config file:

<fieldType name="Name Field" type="sctest.NameFieldType,sctest" />

Step 3 - Write code that controls the inline editing interface
Next I need to tell Sitecore how a name field value should be displayed in Page Editor. There are a couple of things I want to configure. First, I don't want users to be able to enter a value inline. I want all name values to be entered through my custom interface. I need to disable inline editing. Second, I want my custom interface to appear when a user clicks a name value in Page Editor.

public class GetNameFieldValue
{
public void Process(RenderFieldArgs args)
{
  switch (args.FieldTypeKey)
  {
    case "name field":
    {
      args.DisableWebEditContentEditing = true;
      args.WebEditClick = "return Sitecore.WebEdit.editControl($JavascriptParameters,'sctest:EditNameButton');";
      break;
    }
  }
}
}

Step 4 - Configure Sitecore to use the code
The Sitecore's renderField pipeline is responsible for rendering fields in Page Editor. The pipeline is defined in web.config. One of the steps in the pipeline is to determine what value should be rendered for a specific field. An addition to this pipeline is needed since I want to change the field renderer's default behavior.

I need to add a processor to the renderField pipeline. The processor will use the class I just created. The path to this pipeline in web.config is /configuration/sitecore/pipelines/renderField. The line should be added before the processor that uses the type Sitecore.Pipelines.RenderField.AddBeforeAndAfterValues. After I make my addition the renderField pipeline looks like the following:

<renderField>
<processor type="Sitecore.Pipelines.RenderField.SetParameters, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.GetFieldValue, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.ExpandLinks, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.GetImageFieldValue, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.GetLinkFieldValue, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.GetInternalLinkFieldValue, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.GetMemoFieldValue, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.GetDateFieldValue, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.GetDocxFieldValue, Sitecore.Kernel"/>
<processor type="sctest.GetNameFieldValue, sctest"/>
<processor type="Sitecore.Pipelines.RenderField.AddBeforeAndAfterValues, Sitecore.Kernel"/>
<processor type="Sitecore.Pipelines.RenderField.RenderWebEditing, Sitecore.Kernel"/>
</renderField>

After I compile my code I can test my changes. I can no longer directly edit a name field value. In addition, when I click the value in Page Editor, my custom user interface appears.

The next thing I want to do is create a custom field renderer in order to provide some extra functionality for my custom field type.

Step 5 - Create a new field renderer
My new field renderer is going to allow a developer to specify a formatting for a name. By default the first name followed by last name will be displayed. This is the value the default field renderer uses. But my custom field renderer is going to support options that will display only the first name, only the last name, and the last name followed by the first name, in addition to the default display format.

In order to accomodate this I need a custom field renderer that supports a format option. Since a developer is able to set the format option value, I need to make sure this value is made available to Sitecore in the way Sitecore expects. The following class does these things:

Assembly name: sctest.dll
Namespace: sctest
Class name: NameFieldControl
Base class: Sitecore.Web.UI.WebControls.FieldControl

public class NameFieldControl : Sitecore.Web.UI.WebControls.FieldControl
{
  public string Format { get; set; }

  protected override void PopulateParameters(Sitecore.Collections.SafeDictionary<string> parameters)
  {
      parameters.Add("format", this.Format);
      base.PopulateParameters(parameters);
  }
}

Step 6 - Implement support for formatting options
Now that I have the ability to support a format value, I need to implement the logic to use that value to determine the text that is displayed when a name field is displayed. That is going to require a modification to the GetNameFieldValue class (the class that I added to the renderField pipeline).

The format value that was set in the previous step is available in the pipeline through the RenderFieldArgs parameter. I use that value to determine how to format the name field's value.

public void Process(RenderFieldArgs args)
{
    switch (args.FieldTypeKey)
    {
        case "name field":
        {
            //
            //
            NameFieldType field = args.Item.Fields[args.FieldName];
            string displayValue = null;
            //
            //
            var format = args.Parameters["format"];
            switch (format)
            {
                case "FirstNameOnly":
                    displayValue = field.FirstName;
                    break;
                case "LastNameOnly":
                    displayValue = field.LastName;
                    break;
                case "LastCommaFirst":
                    displayValue = string.Format("{0}, {1}", field.LastName, field.FirstName);
                    break;
                case "Complete":
                default:
                    displayValue = field.FullName;
                    break;
            }
            args.Result.FirstPart = displayValue;
            args.DisableWebEditContentEditing = true;
            args.WebEditClick = "return Sitecore.WebEdit.editControl($JavascriptParameters,'sctest:EditNameButton');";
            break;
        }
    }
}

Step 7 - Use the custom field renderer
Now I'm ready to use my custom field renderer. I need to add the following code to the top of my sublayout:

<%@ Register TagPrefix="sctest" Namespace="sctest" Assembly="sctest" %>

And then I need to use my new field renderer:

<sctest:NameFieldControl ID="NameFieldControl1" runat="server" Field="Name" Format="LastCommaFirst" />

When I view my site, I see that the name field is formatted as specified.

Custom field renderer in action.

Next steps
This is the end of my 3-part series on custom fields. You can download the finished source code here.

Want to learn more?
See my previous post for good links.

Custom Fields, Part 2

2010-03-22T08:00:00.008-04:00

In my Custom Fields, Part 1 post I demonstrated how to create a customized user interface for editing field content in Content Editor. This post is going to cover how to do the same sort of thing for Page Editor.

Demonstration of the component described in this post.

I know that I promised a custom field render in my previous post, but that's going to have to wait until my next post. This post has more ground to cover than I expected! But that's OK because a custom field renderer isn't needed to create the custom user interface. The generic field renderer is able to handle the user interface we're going to build.

A word of warning
But before I go any further I feel it is important to provide a warning. When I started looking into custom field types I was very excited by the idea of them. Then I talked to some colleagues and learned that custom field types are not all that common in the real world. There are some good reasons for this:

They are not very flexible - If new content needs to be added to a custom field type, it can result in a lot of work. The amount of work is hard to justify when you consider how easy it is to add a new field on a data template. In other words, using data templates to define the content is easier than creating and maintaining custom fields.
The parts of Sitecore that are needed to create custom field types are not entirely documented.
Creating this type of customization is risky because of changes that might be made to the API or to the Sitecore user interface in the future.

Having said that, I still believe there is value is knowing how to do this. The exercise has taught me a lot about how Sitecore handles content, as well as how the Sitecore client works. Now, on to the code...

Step 1 - Refactor name-parsing logic
In my previous post I included name-parsing logic directly in the name field control. If you remember, the purpose of this control was to display a custom interface for editing a name field using Content Editor.

This time I am creating a custom interface for editing a name field using Page Editor, so I'm going to need name-parsing logic again. Rather than duplicate the code, I'm going to create a utility class to hold that logic:

Assembly name: sctest.dll
Namespace: Sctest
Class name: NameFieldUtils
Base class: System.Object

public class NameFieldUtils
{
 public static string GetFullName(string firstName, string lastName)
 {
   var name = new string[2];
   name[0] = firstName;
   name[1] = lastName;
   return String.Join(" ", name);
 }
 public static string GetFirstName(string fullName)
 {
   string[] parts = fullName.Split(' ');
   if (parts.Length >= 1)
   {
       return parts[0];
   }
   return string.Empty;
 }
 public static string GetLastName(string fullName)
 {
   string[] parts = fullName.Split(' ');
   if (parts.Length >= 2)
     return parts[1];
   return string.Empty;
 }
}

Step 2 - Rename the NameField class to NameControl
In order to avoid any possible confusion regarding the purpose of the various classes being created, rename the control created in the last post to NameControl. Recompile your code. Don't forget to change the control name in the core database, too (/sitecore/system/Field types/Custom Field Types/Name Field).

Step 3 - Modify the OnLoad method from NameControl
The name-parsing logic was moved into NameFieldUtils, so the OnLoad method should use NameFieldUtils. OnLoad should look like the following:

protected override void OnLoad(EventArgs e)
{
   if (!Sitecore.Context.ClientPage.IsEvent)
   {
       //
       //create the controls
       var textFirstName = new Sitecore.Shell.Applications.ContentEditor.Text();
       this.Controls.Add(textFirstName);
       textFirstName.ID = GetID("textFirstName");
       var textLastName = new Sitecore.Shell.Applications.ContentEditor.Text();
       this.Controls.Add(textLastName);
       textLastName.ID = GetID("textLastName");
       //
       //set the values on the textbox controls
       textFirstName.Value = NameFieldType.GetFirstName(this.Value);
       textLastName.Value = NameFieldType.GetLastName(this.Value); ;
   }
   else
   {
       //
       //read the values from the textbox controls
       var textFirstName = FindControl(GetID("textFirstName")) as Sitecore.Shell.Applications.ContentEditor.Text;
       var textLastName = FindControl(GetID("textLastName")) as Sitecore.Shell.Applications.ContentEditor.Text;
       //
       //set the value on the NameControl control
       var firstName = (textFirstName != null ? textFirstName.Value : string.Empty);
       var lastName = (textLastName != null ? textLastName.Value : string.Empty);
       this.Value = NameFieldType.GetFullName(firstName, lastName);
   }
   base.OnLoad(e);
}

This is a good point to test your changes. Recompile your code and make sure everything works as it did before you started reading this post. No new functionality has been added to Sitecore yes, so your code should work the same as it did before.

Step 4 - Create a layout
The Sitecore client user interface is built using XAML. This technology allows user interface components to be defined using XML. An XML Layout can be used to define the user interface.

Switch to the core database.
Open Developer Center.
In the top menu, select File --New.
The New File window appears. Select XML Layout from the Layouts category.
Click the Create button.
The new file wizard appears. For the name enter "Name Field Editor Layout". Then click the Next button.
For the location select the \Layouts\Dialogs node. Click the Next button.
For the file location select the \Website\layouts node. Click the Create button.
Click the Finish button.
The newly created XAML file appears in Developer Center. This file can be edited using Developer Center, or by editing the file Test Field Editor Layout.xml directly from the file system.

Step 5 - Specify the user interface components
The XML file created in the previous step must have controls in order to display a meaningful user interface.

<control xmlns:def="Definition" xmlns="http://schemas.sitecore.net/Visual-Studio-Intellisense">
 <NameFieldEditorLayout>
   <FormDialog Icon="Applications/32x32/text_marked.png" Header="Enter Name" Text="Enter the name." OKButton="OK">
     <GridPanel Columns="2">
       <Literal Text="First name:"/>
       <Edit ID="FirstName" Width="300" />
       <Literal Text="Last name:"/>
       <Edit ID="LastName" Width="300" />
     </GridPanel>
     <CodeBeside Type="sctest.NameFieldEditor,sctest.dll"/>
   </FormDialog> 
 </NameFieldEditorLayout>
</control>

Some of the code above is self-explanatory, I think. Here's a description of the parts that aren't obvious:

NameFieldEditorLayout - If you look in the core database you can find the item that was generated when you used Developer Center to create a new XML layout: /sitecore/layout/Layouts/Dialogs/Name Field Editor Layout. One of the properties of this item is its control name: NameFieldEditorLayout. This value was automatically generated by Developer Center. When Sitecore uses the XML layout, it is going to look for the XAML file that has the definition of NameFieldEditorLayout. By containing the tag NameFieldEditorLayout, this file becomes the file Sitecore will use.
FormDialog - Creates a modal window.
GridPanel - Creates a 2-column table. Each control inside the GridPanel tag gets its own cell. The 1st control gets the 1st cell in the 1st column. The 2nd control gets the 2nd cell in the 1st column. The 3rd control gets the 1st cell in the 2nd column. The 4th control gets the 2nd cell in the 2nd column.
CodeBeside - Defines the file that will contain code like event handlers.

Step 6 - Create the CodeBeside file
This file contains the code to handle events generated by the user interface. There are 2 methods in this file:

OnLoad - This code runs when the dialog window is loaded. Specifically, the code sets the values of the FirstName and LastName input fields to be the current field value. This is done by reading a query string value. The query string value is set by code I will write in a later step.
OnOK - This code runs when the OK button is clicked. Specifically, the code passes the values in the FirstName and LastName input fields back to the code that opened the dialog window in the first place. That, also, is code that I will write in a later step.

public class NameFieldEditor : DialogForm
{
   protected Sitecore.Web.UI.HtmlControls.Edit FirstName;
   protected Sitecore.Web.UI.HtmlControls.Edit LastName;
   protected override void OnLoad(EventArgs e)
   {
       if (! Sitecore.Context.ClientPage.IsEvent)
       {
           //
           //The values are not actually stored on the item itself
           //until the save button is clicked, so we can't read
           //the values from the item.  Instead, read the values
           //from the webedit interface.  These values should have
           //been included in the QueryString by the WebEditCommand
           //instance that opened the dialog.
           var name = Sitecore.Context.Request.QueryString["name"];
           if ((name != null) && (! string.IsNullOrEmpty(name)))
           {
               FirstName.Value = NameFieldType.GetFirstName(name); ;
               LastName.Value = NameFieldType.GetLastName(name); ;
           }
       }
       base.OnLoad(e);   
   }
   protected override void OnOK(object sender, EventArgs args)
   {
       //
       //Write the response value that will be available to the
       //WebEditCommand class that caused this dialog to appear.
       var xml = string.Format("<name><first>{0}</first><last>{1}</last></name>", FirstName.Value, LastName.Value);
       SheerResponse.SetDialogValue(xml);
       base.OnOK(sender, args);
   }
}

Step 7 - Create an item for the user interface
Sitecore needs to know that my user interface is available. This is done by creating an item in the core database:

Item to create the item on: /sitecore/content/Applications/Dialogs
Template: /sitecore/templates/Common/Folder
Item Name: Name Field Editor

Step 8 - Identify the layout that applies to the user interface item
Open the Presentation Details for the item created in the previous step. Set the layout to be Layouts/Dialogs/Name Field Editor Layout.

Step 9 - Define buttons for the custom field type
When a content author wants to set a value for a name field, I want the author to be able to click a button that will cause the name field editor dialog to appear. I need to define the button. But first I need to create a folder to hold the button. Create the following item:

Item to create the item on: /sitecore/system/Field types/Custom Field Types/Name Field
Template: /sitecore/templates/Common/Folder
Item Name: WebEdit Buttons

Next I create the button itself. Create the following item:

Item to create the item on: /sitecore/system/Field types/Custom Field Types/Name Field/WebEdit Buttons
Template: /System/WebEdit/WebEdit Button
Item Name: Edit Name

A couple of field values must be specified for this item. Set the following values:

Header: Edit Name
Click: javascript:return Sitecore.WebEdit.editControl($JavascriptParameters, "sctest:EditNameButton")
Tooltip: Edit Name

Step 10 - Register the command
In the previous step I configured a button. One of the settings was the Javascript code to run when the button is clicked. The code tells Sitecore to execute a command named "sctest:EditNameButton" when the button is clicked. I need to tell Sitecore what code corresponds to this command. This is done by adding a command to the commands.config file.

<command name="sctest:EditNameButton" type="sctest.EditNameButtonCommand,sctest">

Step 11 - Implement the command
The class identified in the previous step contains the logic that is run when the specified command is executed (meaning when the edit name button is clicked).

This class extends Sitecore.Shell.Applications.WebEdit.Commands.WebEditCommand. The class has 2 methods in it:

Execute - This method reads the current name field value. It sets this value as a parameter, which is important because this will make the value available inside the Run() method. Then the method calls the Run() method.
Run - If the code is running during a PostBack it means either the Cancel or the OK button was clicked. If the Cancel button was clicked (there is no result, so args.HasResult is false) there is nothing else to do so the method returns. If the OK button was clicked, the XML generated by NameFieldEditor.OnOK() is parsed and the first and last names are set for the field in Page Editor.

If the code is not running during a PostBack, that means someone has clicked the edit name button. The name field editor dialog window is displayed, and the current field value must be passed to the window.

public class EditNameButtonCommand : WebEditCommand
{
   public override void Execute(CommandContext context)
   {
       //
       //Read the value that is currently set on the field
       //in the page editor.  Since the page editor interface
       //only writes field values after the user clicks the
       //save button it is important that the value be read
       //from the page editor rather than the item itself.
       var formValue = WebUtil.GetFormValue("scPlainValue");
       context.Parameters.Add("name", formValue);
       Sitecore.Context.ClientPage.Start(this, "Run", context.Parameters);
   }

   protected void Run(ClientPipelineArgs args)
   {
       if (args.IsPostBack)
       {
           if (! args.HasResult)
           {
               return;
           }
           //
           //Read the first and last names from the returned XML.
           var dom = new XmlDocument();
           dom.LoadXml(args.Result);
           var firstName = dom.SelectSingleNode("/name/first").InnerText;
           var lastName = dom.SelectSingleNode("/name/last").InnerText;
           var fullName = NameFieldType.GetFullName(firstName, lastName);
           //
           //Set the first and last names.  These values should not be
           //saved directly on the item.  The page editor will handle
           //that when the user clicks the save button.  Instead, the
           //values should be set in a way that the page editor will
           //store the values until the user clicks the save button.
           SheerResponse.SetAttribute("scHtmlValue", "value", fullName);
           SheerResponse.SetAttribute("scPlainValue", "value", fullName);
           SheerResponse.Eval("scSetHtmlValue('" + args.Parameters["controlid"] + "')");
       }
       else
       {
           //
           //get the url for the dialog that needs to be displayed
           var db = Sitecore.Data.Database.GetDatabase("core");
           var item = db.GetItem("{6C57B044-C860-4DAF-982E-5A64E467C1CD}");
           var url = new UrlString(LinkManager.GetItemUrl(item));
           //
           //pass the current value to the dialog
           var name = args.Parameters["name"];
           if (name != null)
               url.Add("name", name);
           //
           //display the dialog
           Sitecore.Context.ClientPage.ClientResponse.ShowModalDialog(url.ToString(), true);
           args.WaitForPostBack();
       }
   }
}

Note: in order to compile this code, you may need to add a reference to the Sitecore.Client.dll assembly. If using Visual Studio because to set CopyLocal to false.

Step 12 - Test the code
After I compile my code I am ready to test it. I need to make sure I have a field in a data template that uses the Name Field type. In the sublayout (or rendering) you're using to display the field value, make sure you're using the field renderer to display the value. You should be able to go into page editor and click the Edit Name button.

And when I click the button, I see the name field editor.

Next steps
In my next post I will demonstrate how to create a custom field renderer. Also, when you use the default field renderer on a name field, you may notice there is some unwanted functionality. I'll tell you what it is in my next post - along with a solutions for it. In the meantime, here's a hint: is there any way for a Page Editor user to circumvent the name field editor interface?

Want to learn more?

Writing My First XAML Application - Great tutorial that guides you through every step in creating a XAML application.
XML/Sheer UI articles on SDN
Alexey Rusakov's blog - Alexey has written a number of outstanding posts on this subject, and has tagged them for your convenience.

Custom Fields, Part 1

2010-03-05T07:00:00.016-05:00

Like most WCM systems, Sitecore supports both structured and unstructured content. The difference between structured and unstructured content can be explained through an example. Let's say you want to allow a person from the marketing department to create a new press release for your website. With structured content the person would need to provide a title, date, description, and an image. With unstructured content the person would get a big HTML field and would provide any values he wants.

What is a field type?
When working with structured content, the concept of "content type" is important. Is the content you're modeling a string, a date or an image? If the content is a string, is formatting supported? The answers to these questions determine what the user interface looks like for the people using the system.

Sitecore has an interesting way of handling content type. Content is defined using fields, and each field has a type. Sitecore comes with a large number of different field types out of the box.

Why should you be interested in custom field types?
As powerful and flexible as Sitecore field types are, it is possible that you will encounter a requirement that would be much easier to meet if you create your own field type.

Not all WCM systems can do this. The impact of this is a significantly more complicated content model. This means more work for developers to create and more work for content authors to use. It also has a potentially devastating effect on workflow (imagine a proliferation of distinct pieces of managed content that somehow must be related).

This functionality has so many applications. It can be used to integrate with external data sources. It can be used to create easier-to-use interfaces for text values (as this article will explain). It can be used to facilitate content migration. And much more.

How are custom field types handled in Sitecore?
As you would expect, Sitecore provides many ways to handle custom field types. And as you would expect, the method you choose depends on your requirements. I'm going to cover a number of these in future posts.

To give you an idea of the scope of this topic, developing a custom field requires you consider the following:

How does a person edit field content in Content Editor mode?
How does a person edit field content in Page Editor mode?
How is field content stored in Sitecore?
How is field content accessed using the Sitecore API?
How is field content rendered in presentation logic?

Not every custom field needs to have a custom solution for each of these. This post covers only the first one. I will explain how to create a custom interface for entering a text value. I think this is a good place to start since a large part of creating custom field types is building the user interface for reading and writing field content.

The Sitecore Developer Network has an excellent article that explains how to create something called a "composite custom field". What this post covers is very similar to that, but is much simpler. This will give me something to build on in subsequent posts.

This post will explain how to create a custom field to make it a little easier to enter a person's name. For the sake of simplicity, I am going to assume that a person has a first name (given name) and a last name (family name or surname). The person's name will be stored as a single value in Sitecore, but the user interface will allow content editors to enter the values separately.

What is a composite custom field?
A composite custom field is made up of existing field types. My custom field needs to support two separate text values. Since Sitecore already has the Text field type, a composite custom field is appropriate. I can use two Text fields to create my custom field.

Step 1 - Create an HTML server control
Using Visual Studio create the following class. This control will generate the user interface Sitecore displays when someone edits the value of a field:

Assembly name: sctest.dll
Namespace: Sctest
Class name: NameField
Base class: Sitecore.Web.UI.HtmlControls.Control

Step 2 - Override the OnLoad method
In the Sctest.NameField class, override the OnLoad method. This method is inherited from System.Web.UI.WebControl, which is a base class for Sitecore.Web.UI.HtmlControls.Control. Just like with a standard ASP.NET web control, the purpose of this method is to load and set properties on child controls.


protected override void OnLoad(EventArgs e)
{
base.OnLoad(e);
}

This control needs 2 textbox controls (first name and last name). The first thing this method does is checks to see if these controls have already been loaded. This is accomplished by checking the value of the IsEvent property on the ClientPage.


protected override void OnLoad(EventArgs e)
{
if (!Sitecore.Context.ClientPage.IsEvent)
{
}
else
{
}
base.OnLoad(e);
}

ClientPage represents the current web form. Checking ClientPage.IsEvent is very similar to checking Page.IsPostback in ASP.NET. This layer of abstraction is important because it frees Sitecore from being tied to web forms. But that's a topic for a later post.

If ClientPage.IsEvent is not true it is likely that the 2 textbox controls have not already been created. The textboxes need to be created. The textbox controls also need to be added as children on the NameField control.


//
//create the textbox controls
var textFirstName = new Sitecore.Shell.Applications.ContentEditor.Text();
textFirstName.ID = GetID("textFirstName");
var textLastName = new Sitecore.Shell.Applications.ContentEditor.Text();
textLastName.ID = GetID("textLastName");
//
//add the textbox controls as children
this.Controls.Add(textFirstName);
this.Controls.Add(textLastName);

The current item may already have a value set for the name, so that value needs to be loaded into the control. Sitecore handles the work of actually reading and writing field values. It does so through the control's Value property. The Value property is a string, which should come as no surprise since, internally, Sitecore stores content as text.

The logic we will use is very simple. The first space character in the value will serve as the separator between the first and last names.


var firstName = "";
var lastName = "";
var currentValue = this.Value;
var firstSpace = currentValue.IndexOf(' ');
if (firstSpace == -1)
{
firstName = currentValue;
}
else
{
firstName = currentValue.Substring(0, firstSpace);
lastName = currentValue.Substring(firstSpace).Trim();
}
textFirstName.Value = firstName;
textLastName.Value = lastName;

Next we need to consider the code that belongs in the else-block. This code runs when ClientPage.IsEvent is true. One important example of when this code will run is when an item is saved. Specifically, this code will run when the item is saved using a ClientPage with this control on it. For this reason, this code must take the values from the 2 textbox controls and set a value on the NameField control.


var textFirstName = FindControl(GetID("textFirstName")) as Sitecore.Shell.Applications.ContentEditor.Text;
var textLastName = FindControl(GetID("textLastName")) as Sitecore.Shell.Applications.ContentEditor.Text;
var name = new string[2];
name[0] = textFirstName.Value;
name[1] = textLastName.Value;
this.Value = String.Join(" ", name);

The complete code is the following:


public class NameField : Sitecore.Web.UI.HtmlControls.Control
{
protected override void OnLoad(EventArgs e)
{
  if (!Sitecore.Context.ClientPage.IsEvent)
  {
    //
    //create the controls
    var textFirstName = new Sitecore.Shell.Applications.ContentEditor.Text();
    this.Controls.Add(textFirstName);
    textFirstName.ID = GetID("textFirstName");
    var textLastName = new Sitecore.Shell.Applications.ContentEditor.Text();
    this.Controls.Add(textLastName);
    textLastName.ID = GetID("textLastName");
    //
    //get the current value
    var firstName = "";
    var lastName = "";
    var currentValue = this.Value;
    var firstSpace = currentValue.IndexOf(' ');
    if (firstSpace == -1)
    {
      firstName = currentValue;
    }
    else
    {
      firstName = currentValue.Substring(0, firstSpace);
      lastName = currentValue.Substring(firstSpace).Trim();
    }
    //
    //set the values on the textbox controls
    textFirstName.Value = firstName;
    textLastName.Value = lastName;
  }
  else
  {
    //
    //read the values from the textbox controls
    var textFirstName = FindControl(GetID("textFirstName")) as Sitecore.Shell.Applications.ContentEditor.Text;
    var textLastName = FindControl(GetID("textLastName")) as Sitecore.Shell.Applications.ContentEditor.Text;
    var name = new string[2];
    name[0] = textFirstName.Value;
    name[1] = textLastName.Value;
    //
    //set the value on the NameField control
    this.Value = String.Join(" ", name);
  }
  base.OnLoad(e);
}
}

Step 3 - Compile your code
Compile your code and put the assembly in a directory that Sitecore will be able to find it.

Step 4 - Define a custom field type in Sitecore
This step involves adding the custom field to the Sitecore client so that developers can use it.

Step 4.1. Log into the Sitecore Content Editor and connect to the core database.

Step 4.2. Create the following item:

Item to create the item on: /sitecore/system/Field types
Template: /sitecore/templates/Common/Folder
Item Name: Custom Field Types

Step 4.3. Create the following item:

Item to create the item on: /sitecore/system/Field types/Custom Field Types
Template: /System/Templates/Template field type
Item Name: Name Field

Step 4.4. Select the Name Field item. Enter the following field values:

Control: myfields:NameField

Step 4.5. Save your changes and switch to the master database.

What you have just done is told Sitecore is that a new field type is available. This field type is named "myfields:NameField". How does Sitecore know what code to use when this field type is used? That is configured in the next step.

Step 5 - Map the field prefix to an assembly and namespace
The custom field's name (configured in the previous step) is a combination of a prefix (myfields) and a class name (NameField). This step involves telling Sitecore which assembly contains the class NameField.

This is done through the web.config file. I added the following line to the /configuration/sitecore/controlSources node. It tells Sitecore that any control identified using the prefix "myfields" can be located in the "sctest" assembly and is a part of the "sctest" namespace:

How to use a composite custom field
Now, when you configure a field in a Data Template, you should see a new option available in the list of field types. I added the following field:

Data template: /sitecore/templates/Sample/Sample Item
Field name: Name
Type: Name Field

The Home item in my installation is an instance of this data template. Using Content Editor, I see the following when I edit content:

I also modified the layout that is used for this item so that the name value appears on the website. I added the following code inside the body:

Next steps
We have created a custom interface for configuring content using Content Editor, but this interface is not available in Page Editor. The next step is to expand this functionality to Page Editor. This will require a custom field renderer web control.

Want to learn more?

Blog Update

2010-02-22T22:00:00.001-05:00

Just wanted to let everyone know about a small - but important - change I recently made on this blog. I went back through my previous posts and added links to the relevant Sitecore resources so you can get more information on the topics discussed. Look for the "Want to learn more?" section at the end of each post. I will be including this information in all future posts as well.

How Sitecore Determines Which Layout To Use

2010-02-12T09:00:00.004-05:00

Recently I've written about the core components of Sitecore's approach to presentation logic: layouts and controls (.NET and XSLT) and placeholders. I've explained how content is displayed in layouts, and how controls are positioned inside them. What I haven't covered is how Sitecore knows which layout to use and when. That is the topic of this post.

How content is viewed in Sitecore?
When someone wants to view content from Sitecore, a request is made through a URL. In Sitecore, every URL resolves to an item in the system. What Sitecore returns when a request is made is a visual representation of the item that corresponds to the URL. We know that layouts provide the basic structure of this visual representation, but how does Sitecore know which layout to apply to which item?

What is a device?
A device represents a specific way of viewing content in Sitecore. Sitecore analyzes a request in order to determine how the user wants to view content.

This determination is based on rules a developer configures. Sitecore allows the browser agent and query string values to be used to define rules. (Of course, it is also possible to extend Sitecore to support other criteria.) If you anticipate visitors will use desktop web browsers and mobile phones to access your site, you might configure 2 devices.

Device configuration options.

It's important to note that devices themselves don't do anything. A device does not specify which layout should be used. Sitecore inspects incoming requests in order to determine which device is appropriate for each request. After Sitecore figures this out, the device is just one of many pieces of information that are passed along to be used by other parts of the system. Other parts of the system may contain conditional logic that considers the device as a part of its operation.

I think the word device fails to convey the flexibility of devices. A visitor to the website can start out using one device and then can switch to another device without leaving his browser. Devices could be used to try out new HTML using live content without disrupting the live site. I'm not sure "device" is the best English word for the concept, but that is the word that Sitecore uses.

How are devices configured?
Devices are configured under the /sitecore/Layout/Devices node. After you create a device, you can specify the browser agent value and/or the query string value that Sitecore should use to uniquely identify the device. These values can be changed at any time in the future, so you don't need to be too worried about making a mistake.

BTW, when you provide a browser agent value, Sitecore checks to see if your value is found in the User-Agent request header. Sitecore performs a case-insensitive search using IndexOf().

How does a device relate to an item?
When you want to view an item, you always view the item through a device. Therefore it makes sense that device settings can be configured at the item level. However, since all items that are based on the same data template are probably displayed in the same way, a better place to configure device settings is on the data template itself (using standard fields, of course).

By configuring the device settings on the data template you are setting a default value. You're telling Sitecore that unless the device settings are overridden on a specific item, these are the settings Sitecore should use. One of the device settings indicates which layout Sitecore should use.

Presentation Details
The section of the Sitecore user interface that allows a layout to be specified for a device is called "presentation details". Like I mentioned above, presentation details can be set on data templates and on individual items (though the former is preferred).

Presentation details in the Sitecore user interface.

The presentation details section displays all of the devices that have been defined. For each device, they layout that has been assigned for the device is displayed. This is tell you that when a certain item is viewed using a certain device, a certain layout should be used. These settings can be changed at any time.

The layout details screen lists devices and the layout assigned to each.

What's next?
Now that I've gotten through the absolute basics of content modeling and presentation logic using Sitecore, I'm going to move onto different topics. Hopefully some that won't take almost 10 posts to cover.

Want to learn more?

How Presentation Controls Are Used In Sitecore

2010-02-09T10:00:00.014-05:00

My last several posts have covered controls (.NET and XSLT). The purpose of controls are to allow presentation logic and functionality to be reused. One thing I haven't explained is how controls are actually used.

Controls can be used in two ways. One way is probably pretty obvious: you can put presentation controls directly in a layout using web controls. Sitecore provides web controls for positioning sublayouts and renderings. Since Sitecore web controls are already ASP.NET web controls, they can be used as-is.

Positioning presentation controls directly in a layout is sometimes called "static binding". The words refer to the idea that the controls are positioned in the layout in a way that does not change.

Which leads us to the second way to position controls: dynamically. Using dynamic binding, a control is positioned in a layout by a content editor rather than a developer. If you're comfortable with the concept of variables, the approach Sitecore uses will make perfect sense:

Developer creates a "placeholder" in a layout. The placeholder is given a name.
Developer specifies the controls that a content editor will be allowed to put into the placeholder.
The content editor selects placeholder he wants to position a control in.
The content editor selects the control he wants to drop into the placeholder.

Step 1 involves inserting a web control into the layout. Step 2 involves configuration inside Sitecore. Steps 3 and 4 can be performed in a number of ways. The following video demonstrates how to do it using Page Editor.

Now, there is a little more to working with placeholders than the 4 simple steps I listed above. The missing piece is understanding how Sitecore knows to you the layout in the first place. That is key because the placeholder is defined in the layout.

What's next?
I just tipped my hand, but defining content and presentation only get you so far. In order for either to be useful, they must work together. My next post will cover how you tell Sitecore which presentation should be used for which content.

Want to learn more?

Renderings

2010-02-05T14:00:00.003-05:00

Presentation controls are an important part of Sitecore's strategy for displaying content. When these controls are created using .NET they are either sublayouts or web controls. When these controls are created using XSLT then are called "renderings"

Renderings serve the same purpose as any other presentation control (they provide blocks of reusable presentation logic). They are configured in the same way (they consist of a definition item as well as a physical file). They are developed and deployed similarly (changes to the files the definition items point to can be changed and deployed without having to notify Sitecore).

The idea with renderings is that Sitecore provides a view of itself in an XML structure, which can be transformed into HTML (or whatever presentation format you want) using XSLT.

...

Sample of the XML representation of a Sitecore item.

XSL extension methods are used to display field values in renderings. Placeholders cannot be defined in renderings.

One of the nice features available to you when using renderings is the Sitecore Developer Center. This is a part of the Sitecore user interface where developers are able to work on and debug their code. The Developer Center includes a preview screen that allows you to watch your XSLT execute as you write it.

Changes to XSLT files can be previewed inside Sitecore.

XSLT or not?
Using XSLT in Sitecore is something that people tend to feel passionate about. I've heard the arguments (some of them, anyway), but there are 2 things that make me feel that - as a general rule - it's probably better to stay away from XSLT.

First, .NET code runs much faster than XSLT code in Sitecore. Some people argue that the proper use of Sitecore's caching features renders this a moot point. I don't know enough about how Sitecore caching works to know how many situations this holds true for. I know from working with other system that there are times when content just can't be cached. For example, personalized navigation.

My second issue involves code maintenance. Trying to understand someone else's code is seldom a pleasant task, but trying to understand someone else's XSLT code takes unpleasant to another level. With .NET code you have Visual Studio to help you in a variety of ways. I'm not aware of any way to debug XSLT code running in Sitecore. Sure, it might take 1/2 the time for you to write XSLT code, but I wonder if that efficiency evaporates when it's time for someone else to work with the code.

Still, it is important to note that renderings are not a gratuitous or deprecated feature. There are places they are genuinely useful. In cases where you need to traverse multiple levels of the content tree (building navigation links, for example), using XSLT is a fast and powerful tool.

What's next?
Now that we've seen how controls are created, the next thing to cover is how are they used. My next post will cover this topic.

Want to learn more?

Sublayouts and Web Controls

2010-02-01T21:00:00.011-05:00

Previously I explained what Sitecore's presentation controls are and why they are important. At this point you're probably ready for some technical details. These controls can be written using .NET for XSLT. In this post I will discuss presentation controls written using .NET.

When creating presentation controls using .NET you have two choices: user controls (which are called sublayouts in Sitecore) and web controls. For both user controls and web controls, the advantages and disadvantages inside Sitecore are the same in a regular ASP.NET application. Which you use depends on what you're trying to accomplish. (Microsoft has a good article that describes the differences between user controls and web controls)

And the user controls and web controls are plain old ASP.NET controls. There is no special Sitecore class to extend or interface to implement.


<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="HelloWorldSublayout.ascx.cs" Inherits="mysite.HelloWorldSublayout" %>

[Hello, world.]

Example of an ASP.NET user control.

All of your development can be done in Visual Studio. Inside Sitecore, you simply need to register the control. After the control is registered it can be used inside placeholders.

Creating a sublayout using Sitecore.

The video above demonstrates how a sublayout is created inside Sitecore. The user creates a sublayout item, and then Sitecore generates the ascx file. But there's a little more to it than that.

When the user creates the sublayout, Sitecore creates a definition item for the sublayout. A definition item is the object inside Sitecore that maps a logical component to a physical one. Definition items are used in several places in Sitecore.

In this case, the logical component is the sublayout and the physical component is the ASP.NET user control (ascx file). The definition item merely points to a file on IIS. The location of the file was specified on one of the screens in the "create sublayout" wizard and can be changed at any time using the Content Editor.

The important thing to note is that the physical file can be edited outside of Sitecore. After this happens, Sitecore doesn't need to be notified. All Sitecore cares about is that it is able to locate a file at a certain location when a specific resource is requested.

Pretty much everything I just wrote about sublayouts is also true of web controls. In order to create a web control you use a different branch of the content editor (Layout\Renderings instead of Layout\Sublayouts). The configuration of the definition item for a web control is slightly more manual than that of a sublayout (you need to point Sitecore to a specific .NET class rather than a file). But I see these as minor differences.

What's next?
Presentation controls can be written using another technology as well: XSLT. My next post will describe how XSLT can be used to create presentation controls.

Want to learn more?

Sitecore Presentation Controls

2010-01-21T09:00:00.014-05:00

In Sitecore, there are various web controls that can be used to display the value of a field. This is critical because content it stored in fields. If you want to display the date assigned to a press release or an image of the cover of a book that you sell on your website, this is what you are interested in.

However, presentation logic should be thought of as more than a bunch of individual values. There are relationships between the fields being displayed. You're not just displaying the title of a book along with its cover. You are displaying details about a book. Today it's the title and cover. Tomorrow it might also include a summary of the book.

Before presentation controls and after.

A block of presentation logic in Sitecore is defined using a component called a "presentation control". In this post I am going to give a quick overview of presentation controls.

What is a presentation control?
A presentation control allows presentation logic to be defined in a reusable component. Some examples are:

Book detail - displays the title, author, summary and price of a book along with an image of its cover, positioned in a certain way
Breadcrumb trail
Ad block - displays an image and a hyperlink
Header block - displays an image, search box, an ad block and a home link

Sitecore supports 3 kinds of presentation controls: sublayouts, webcontrols and renderings. Sublayouts and webcontrols are written using .NET. Renderings are written using XSLT.

What are the benefits to presentation controls?
One benefit of using presentation controls is that your presentation logic is encapsulated in a reusable component.

Another benefit is that content editors are able to use the Sitecore page editor to drop presentation controls into their web pages. This is a very powerful tool that can be offered to content editors, and one that I will cover in a future post.

This is not so much a benefit of presentation controls so much as a benefit of Sitecore. There is no new, proprietary technology that you need to learn in order to create presentation controls. You can use .NET or XSLT.

I spent many years teaching people how to use a product that depended on an unwieldy, proprietary language for presentation logic. It's definitely to Sitecore's credit - and the benefit of people learning Sitecore - that they decided against reinventing the wheel.

What's next?
My next post will take a look at some of the technical details of presentation controls. How are they written? What do they look like? How are they used?

Want to learn more?

Displaying Field Values Using Server Controls

2010-01-18T09:00:00.017-05:00

This post is part 3 of a not-yet-determined number of posts discussing presentation logic and Sitecore. My previous post explained some of the options available for getting content to appear in a Sitecore website. I ended with a promise to cover some of the Sitecore server controls that are used to display content.

Sitecore has a number of server controls that are used for different purposes. For this discussion there are 2 kinds of server controls to consider: those that display a single value and those that display other controls. I will start with the former.

Controls that display content
One of the most fundamental tasks performed by presentation logic is to display values. If you are displaying content about a book, you might want to display the book's title and author and an image of its cover.

In Sitecore, the book would be an item which was created using a data template. The title, author and image are fields defined in the data template. A layout is used when the book item needs to be displayed. Server controls are used in the layout to position and render the field values.


<sc:FieldRenderer ID="FieldRenderer1" runat="server" FieldName="Description" />

The specific type of server control is Sitecore.Web.UI.WebControls.FieldRenderer. The class name reveals this server control's purpose: it renders the value of a field. The various web controls that extend Sitecore.Web.UI.WebControls.FieldControl provide similar functionality.

What's the difference FieldControl classes and FieldRenderer? FieldRenderer is generic. You give it the name of the field and it will render the value. FieldControl classes target specific field types. They recognize the unique capabilities of the different field types. The following examples demonstrate what I mean.


<sc:Image ID="Image1" runat="server" Field="Image" MaxWidth="250" />
<sc:Date ID="Date1" runat="server" Field="Date" Format="MM/dd/yyyy" />

As you can see in the following example, the specific options that are available using FieldControl classes are available using FieldRenderer. You just don't get Visual Studio showing what they are the way you do with FieldControls. One thing to note is that FieldControl classes do not exist for every possible field type, so you'll probably be using FieldRenderer at least some of the time.


<sc:Image ID="Image1" runat="server" Field="Image" MaxWidth="250" MaxHeight="100" />
<sc:FieldRenderer ID="fr1" runat="server" FieldName="Image" Parameters="MaxWidth=250&MaxHeight=100" />

What's next?
That gets us through the server controls that display field values. But most of the time individual field values aren't displayed on their own. Usually a number of fields are displayed together, forming a logical grouping of presentation logic. In my next post I will describe how blocks of presentation logic can be defined in Sitecore.

Want to learn more?

Positioning Content For Display

2010-01-14T11:00:00.021-05:00

With this post I want to continue discussing how Sitecore handles presentation logic. My last post described layouts, which are just aspx files that Sitecore uses when someone wants to view content.

Think of HTML. Without content, HTML isn't very useful. Sure, you can have a box with a blue border, but if you don't have any content to put into that box, what's the point? I think of a Sitecore layout in much the same way. Layouts don't have content, they just position content.

So a key question to answer is how do you make content available to a layout? With HTML you just type text or a URL into a tag. With Sitecore you have some more sophisticated options available.

Positioning content using code
Sitecore has an API that provides access to content, so content can be positioned for display using code. For example, the following code could be added to the Page Load event handler in order to display the value of a field named "Text":


Item item = Sitecore.Context.Item;
Response.Write(item.Fields["Text"].Value);

I am far from a Sitecore expert at this point, so I can't say for certain that there's anything wrong with this approach. After all, it works. If you're comfortable with writing code, Sitecore allows you to write code.

However, even as someone new to Sitecore, I can see at least one possible problem with using this approach. When content editors work in Sitecore, they use a WYSIWYG interface called "Page Editor". The page editor allows a user to click on a value and start changing it.

The problem is how does Sitecore know how to generate the interface that allows the editor to actually edit? Unless you tell it, Sitecore doesn't know. Again, you can write code to tell Sitecore to render the user interface so it enables the value to be edited.

Maybe that's not a big deal in this example. In some cases you might not want an editor to ever change a value (site name, for instance). But some of the time - if not most of the time - you are going to want editors to be able to control the content. This is a content management system :-)

And this is a trivial example I'm using. There are only 2 values to edit. In the real-world it's not unusual to have a dozen or more. This quickly becomes more work than expected just to set up, let alone maintain.

Positioning content using server controls
Using the server controls that come with Sitecore is a much easier way to get content into a layout. The following code is an example of how a Sitecore server control can be used to display the value of a field named "Text":


<sc:FieldRenderer ID="FieldRenderer1" runat="server" FieldName="Text" />

Aside from the generic advantages server controls offer over coding, you also get at least one significant Sitecore-specific advantage: these controls are self-aware. By this I mean that they understand the environment in which they are being executed.

For example, if the control is being executed on the published website, a text value may be rendered. If the control is being executed inside the Page Editor interface, the control is able to determine if the current user has permission to edit the value. If the user has permission, then extra code will be generated that will allow the user to edit the value.

The value of this functionality becomes clear when you start thinking about content authoring and usability. But that's a topic for another post.

What's next?
In my next post I plan to get into some of the specific Sitecore server controls that are used to access content.

Want to learn more?

Defining Presentation

2010-01-12T11:00:00.003-05:00

Last week I wrote about content modeling and inheritance, two of the first topics you encounter when learning Sitecore. Content modeling isn't the most exciting topic. You're really just defining data structures used to store content. There are only so many ways to skin that cat, and so many things that a WCM vendor can do to make this a difficult or complicated task.

Handling presentation is another matter. A vendor can choose to use an existing technology for presentation logic. Or, if the vendor is especially self-confident, it can create its own technology. Sitecore uses the former option, with .NET and XSLT being the specific technologies.

What is presentation?
Just to be sure we're on the same page, I want to explain a little about what the term presentation means when dealing with WCM. Content modeling covers how content is defined. In Sitecore, data templates and items are the main tools used to model content. Content is what gets displayed, and it is separate from how it gets displayed.

Presentation is responsible for describing how content should be displayed. It says, for instance, that the image should go in the upper left-hand corner and the main text should be positioned below it. Presentation is what makes it possible to view content on a website. Content without presentation is like having records in a database without a query to retrieve them.

How is presentation defined?
Sitecore uses "layouts" to specify the overall positioning of content and the format of the content being displayed. The purpose of Sitecore items is to store content. The purpose of Sitecore layouts is to provide a visual representation of items. A layout's format is usually HTML, but it can be pretty much anything you want: XML, PDF, etc.

Uninteresting example of a Sitecore Layout.

Layouts are aspx files. And I don't mean a special kind of aspx file. There is no special class that has to be used to create a layout. There is no special interface that must be used to create the aspx file. No new proprietary language, format, tags or syntax is needed. Sitecore websites can be designed and coded in the same manner as any ASP.NET website.

So layouts are web pages, right?
It seems important to remember that a layout is NOT a web page. Sitecore uses layouts when it needs to display items. A web page - when delivered by Sitecore - is a combination of a layout with Sitecore content. Web pages don't exist inside Sitecore. Web pages are generated by Sitecore.

When you think of a web page, you think of something specific: a web page that describes an event or a place. A Sitecore layout, on the other hand, has nothing specific in it. It can display information about specific events or places, but it doesn't have any content of its own. I'm tempted to describe a layout as a presentation template, but since the word "template" already has a use in Sitecore, I'm not going to do that ;-)

What's next?
I've given an overview of what layouts are, but I haven't explained what goes into layouts. In a way, there isn't anything to explain. Layouts are aspx files, so anything that goes into an aspx file can go into a layout.

But, actually, there is more to explain. Sitecore provides some server controls that make it easy to access content in a layout. In my next post I'm going to explain about these server controls and the advantages you'll gain by using them.

Want to learn more?

Inheritance, Content Modeling & Sitecore

2010-01-07T17:00:00.037-05:00

In my previous post I discussed the most elementary aspects of content modeling with Sitecore. When you are learning a WCM system, it's easy to stick with very simple content models. The risk in this is that content models in the real world are not always simple.

Until you encounter requirements that include overlap and interdependency it's easy to have an unrealistic opinion of how well your WCM models content. So far I have been very impressed with Sitecore's approach to modeling content - specifically its support for inheritance.

In this post I will cover inheritance and why it's such a great thing to have in a WCM.

What is inheritance and how does it work?
A data template is a collection of fields. Those fields can be defined directly in the data template, or they can be "inherited" from other data templates. When content is modeled, there is often overlap between very different content. Inheritance allows the overlapping fields to be moved into separate data templates that can be used by any data template that needs the fields.

Let's consider some content that might appear on a website: books, press releases and reviews. The following table lists the fields that are needed for each content type:

Data Template Name	Fields
Book	title, description, image, category, author, price
Press Release	title, description, image, category, date
Review	title, description, image, book, reviewer name

Using inheritance removes duplication by allowing common fields to be moved into more generic base data templates. The following content model takes advantage of inheritance:

Data Template Name	Fields	Inherits
Content Base	title, description, image	[none]
Content Meta Data	category	[none]
Book	author, price	Content Base, Content Meta Data
Press Release	date	Content Base, Content Meta Data
Review	book, reviewer name	Content Base

This explanation of inheritance may appear to contradict something I wrote about items above. I wrote that an item is based on 1 and only 1 data template. That is true of items, but it is not true of data templates. A data template can be based on as many different data templates as you want.

The Book data template's path of inheritance as seen in Sitecore. This example shows the Book data template inherits from the "Content Base" template, which inherits from the "Standard template" template, etc. The "Content Meta Data" data template is also included, but is not shown in this screenshot due to space constraints.

Then what does it mean if an item is based on a data template that is based on multiple data templates? A book item is an example of this. The book item is based on the Book data template, but the Book data template is based on both Content Base and Content Meta Data. This means that the book item is able to store content defined in 3 data templates: Content Base, Content Meta Data, and Book.

You might be tempted to think that a book item is based on 3 data templates, but I don't think that's technically accurate. When you create the book item you can only select 1 data template. The fact that you inherit from 2 other data templates is important, but it shouldn't be confused with the fact that the book item is based on only 1 data template.

Why should you care about inheritance?
There are many reasons to appreciate inheritance. Being able to reuse content definitions makes it easier to make changes later. Consistency is improved because common fields are defined once and used when needed.

But I think the best benefit of inheritance is ease of use for non-technical users. Remember, all of this inheritance is handled by the developer. The content authors never see any of it directly, but they reap the benefits. From the author's perspective, all of the fields are just there. There is no linking or connecting to a separate object in order to enter the values. This means the author can work on the content in one piece, as it exists in the real world.

What is life like without inheritance?
This may seem like an obvious way to do things, but not all WCM systems are designed this way. Consider RedDot CMS (now called Open Text Web Solutions Management Server) as an example. In RedDot, it is possible to move common fields into a shared component. This component is and always will be separate from the component that uses it.

While setting these separate components up is not any more difficult than with Sitecore, the effects are far reaching and significant. Instead of having to create one piece of content, RedDot requires multiple pieces of content be created and connected to one another. Each piece of content is independent each other, meaning that they have their own security, workflow and publishing settings. Content authors have a hard time understanding which pieces go together and which don't. When blocks of content are missing from the website, they don't understand how that can be.

So what ends up happening is the fields that should be separated out are duplicated wherever they are needed. This makes life easier for content authors, but can result in a lot of duplication of work and added complication for developers. On a large project, it is easy to forget all of the places where changes need to be made.

What's next?
Data templates and inheritance seem to be 2 of the most important concepts to understand when first working with Sitecore. Modeling content is at the core of a WCM system, and data templates and inheritance are at the core of modeling content with Sitecore.

Being able to define content is crucial, but if you don't have any way to display content, you might as well not have any content at all. My next post will cover my first impressions of the approach Sitecore uses to handle presentation logic.

Want to learn more?

Content Modeling With Sitecore

2010-01-06T19:00:00.014-05:00

One of the first technical topics you encounter when learning Sitecore is how the system separates content from presentation. In some ways this is a massive and complicated topic. There are so many options and approaches that can be used.

At the same time, its essence seems to be pretty simple. Not simple in that it should be easy for anyone to understand or that it can be learned quickly. I mean simple in the sense that there isn't much to it. Yes, Sitecore provides a large number of tools for a developer to use to model content and design presentation, but there's a distinct logic and consistency to it. Once you're able to get your head wrapped around that, the system isn't as overwhelming.

New York's original telephone system provides a good metaphor.

If one of the first things you learn is how Sitecore separates content from presentation, probably the very first thing you learn is how Sitecore models content. How does a developer configure Sitecore so content authors are able to create content on the site?

How is content described?
Data Templates are used to model content. A data template is a collection of "fields", with each field representing a specific piece of content. Data templates are used to create "items". An item provides the ability to save specific values for the fields. Each item is based on 1 and only 1 data template. To use an object-oriented programming analogy, data templates are classes and items are instances of those classes.

Fields from a data template at they appear in Sitecore.

For example, you might create a data template for a book. A book has fields to store a title, author, description, image and price. Each book item has its own title, author, description, image and price. Examples of book items are "Crime and Punishment", "Absurdistan" and "Sum" (which are 3 of the best books I read last year).

This is a simple example. In the real world, content is often much more complicated. What if you need to model all sorts of books, with each type of book having different content requirements. For example, the content for a novel might be very different from that of a journal or a reference volume or a technical manual.

The way a WCM system provides handles content like this (meaning there are similarities along with differences) impacts so many different aspects of the system that it's hard to overstate its significance. When a WCM doesn't do a good job, usability suffers, it becomes more difficult to introduce changes, duplication starts to appear, among other things. And all of these things increase the cost of building and maintaining your website.

What's next?
In my next post I will explore the concept of inheritance as it pertains to modeling content with Sitecore. I am impressed with how Sitecore allows developers to use inheritance to create a content model that is easy to develop, maintain and use.

Want to learn more?

Getting To Know "Getting to Know"

2010-01-04T18:00:00.003-05:00

Hi there, and welcome to my blog. If I'm not mistaken, this blog has earned the distinction of being the first new Sitecore blog of 2010. Dubious, perhaps, but a distinction nonetheless.

Who am I?
In late 2009 I joined Sitecore as a Technical Architect. I'm a member of the Product Marketing team. As I've been telling my friends, the only bad part of the job is that it's not very easy to explain what I do. My responsibilities include making sure that people inside the company have the technical product knowledge they need in order to get their jobs done, and to help partners develop quality integration between Sitecore and external systems.

Prior to working at Sitecore, I worked at RedDot Hummingbird Open Text. My role there ranged from training to helping partners implement RedDot Open Text Web Solutions products. And before that I worked as a trainer, developer and consultant for content management and custom application development.

What is the purpose of this blog?
Eventually this blog will likely focus on integration topics, since working on integrations is one of my main responsibilities at Sitecore. I was inspired by the spirit of openness and sharing that I see at Sitecore, and I was eager to start sharing my experience and knowledge as soon as possible. But since the part of my job that deals with integrations won't be starting up for a little while, I had to think of something else.

Since I am not only new to the company but new to the product, I decided to blog about my experience learning Sitecore. I hope these posts will help people who are looking at or are new to the product see what it's like to enter the Sitecore world.

While I am new to Sitecore, I am not new to web content management. I may be learning features for the first time, but not the underlying concepts. I haven't been working with Sitecore long, but I already see that a number of the most intractable and pervasive problems people have with other WCM systems can be solved elegantly - or avoided altogether - using Sitecore. In addition to explaining features, I also hope to be able to explain why Sitecore's approach matters.

So thanks for reading. I hope you'll return!