This article describes how Sitecore handles internal and external links, how you can resolve the correct URL to an item, and what you should know about links when building multisite and multilanguage websites.

To render a corrent URL you use the LinkManager:

public string GetUrl(Sitecore.Data.Items.Item item)
{
  return Sitecore.Links.LinkManager.GetItemUrl(item);
}

If the Sitecore Item you are linking to is a Media Item, you cannot use the LinkManager as this will return the Url to the Sitecore item, not the actual media. Instead use the MediaManager:

public string GetUrl(Sitecore.Data.Items.Item item)
{
  return Sitecore.Resources.Media.MediaManager.GetMediaUrl(item);
}

If you have a Linkfield (which can link to Internal items, Media Items, external pages, anchors, email and javascript) you can use a function like this to automatically get the correct URL:

Sitecore.Data.Fields.LinkField lf = Sitecore.Context.Item.Fields["Link"];
switch (lf.LinkType.ToLower())
{
  case "internal":
    // Use LinkMananger for internal links, if link is not empty
    return lf.TargetItem != null ? Sitecore.Links.LinkManager.GetItemUrl(lf.TargetItem) : string.Empty;
  case "media":
    // Use MediaManager for media links, if link is not empty
    return lf.TargetItem != null ? Sitecore.Resources.Media.MediaManager.GetMediaUrl(lf.TargetItem) : string.Empty;
  case "external":
    // Just return external links
    return lf.Url;
  case "anchor":
    // Prefix anchor link with # if link if not empty
    return !string.IsNullOrEmpty(lf.Anchor) ? "#" + lf.Anchor : string.Empty;
  case "mailto":
    // Just return mailto link
    return lf.Url;
  case "javascript":
    // Just return javascript
    return lf.Url;
  default:
    // Just please the compiler, this
    // condition will never be met
    return lf.Url;
}

WHAT ELSE IS THERE TO KNOW?

Well, all internal links in Sitecore starts as a GUID. The GUID represents the internal item you link to. By using GUIDs internally, Sitecore allows you to move pages without worrying about links being invalid.

It is first when you render the page that the GUID is converted into a valid URL. Links in Rich Text Fields does it automatically (actually they use the ExpandLinks processor in the renderField pipeline), Link fields and lookup fields need help from you.

CAN I CONTROL HOW THE URL LOOKS?

Yes you can. You control the URLs with the linkManager settings in web.config:

<linkManager defaultProvider="sitecore">
  <providers>
    <clear />
    <add name="sitecore" type="Sitecore.Links.LinkProvider, Sitecore.Kernel" addAspxExtension="true" alwaysIncludeServerUrl="false" encodeNames="true" languageEmbedding="asNeeded" languageLocation="filePath" shortenUrls="true" useDisplayName="false" />
  </providers>
</linkManager>

Read the comments in the web.config on how to use the attributes. You can also replace the LinkProvider completely.

HOW ABOUT LINKS IN MULTISITE SOLUTIONS?

Multisite solutions are solutions where the same Sitecore installation contains more than one website, each site with its own unique domain name.

When creating multisite websites, you must remember to:

• Set the Rendering.SiteResolving setting in web.config to true.
• Set the targetHostName property to a unique domain for each website in the sites section in web.config.

This allows Sitecore to identify each site and add the correct domain name to links between sites.

BUT FOR NO APPARENT REASON Sitecore has chosen to render links made in the Rich Text Editor and links rendered by the LinkManager differently. Links in the Rich Text Editor use the Rendering.SiteResolving setting, while the LinkManager does not.

So you have to set it when using the LinkManager, using UrlOptions():

Sitecore.Links.UrlOptions urlOptions = new Sitecore.Links.UrlOptions();
urlOptions.SiteResolving = true;
Sitecore.Links.LinkManager.GetItemUrl(someSitecoreItem, urlOptions)

A clever developer will might do as Paul is doing in this blog post and modify the LinkProvider so the option is always set.

Sitecore have also made a free LinkProvider that does the same and more. You can get it here:

http://trac.sitecore.net/LinkProvider#

HOW ABOUT NESTED MULTISITES?

When nesting sites (a new site begins below the URL of an existing site) it becomes more tricky. Forunately Sitecore allows us to replace their LinkProvider, as my colleague Uli has done here: http://reasoncodeexample.com/2012/08/09/sitecore-cross-site-links/

HOW ABOUT MULTILANGUAGE SOLUTIONS?

Multilanguage solutions are solutions where the same site exist in several language versions, each language having a unique URL.

From Sitecore 6.4, Update 6, Sitecore introcuced to more settings called Rendering.SiteResolvingMatchCurrentSite and Rendering.SiteResolvingMatchCurrentLanguage. These settings allow URL’s to guestimate the correct domain and langauge and create the correct URL accordingly.

Read more about it here: http://briancaos.wordpress.com/2012/03/29/sitecore-cross-site-and-cross-language-links-resolved-in-6-4-1-release-120113/

Unfortunately, these settings are also only supported by the Rich Text Editor, not by the LinkManager.

MORE TO READ:

• Sitecore Cross Site Links by Uli Weltersbach
• Manipulating Sitecore Links by John West
• Custom LinkProvider by Sitecore Trac
• Using cross site links by Paul Martin

The Sitecore security framework is based on the .NET security. Managing Authentication, Authorization, User Accounts and Roles can be done using the standard System.Web.Security namespace.

But Sitecore also provides its own Security framework that you can use for easy manipulation of users and roles seen from a Sitecore perspective.

BASICS OF SITECORE SECURITY

There is 2 things you need to know about Security in Sitecore:

• Sitecore prefixes user names with a domain name. This is used to differentiate users between those with access to the Sitecore editor (domain: sitecore) and those with access to the Sitecore extranet (domain: extranet).
  So when accessing Sitecore users from System.Web.Security, make sure you remember to ask for sitecore\admin, and not admin.
  (Advanced Sitecore users know that you can create as many domains as you like).
• In Sitecore there is no such thing as “not been logged in”. If you are not logged in, you will have a user called “extranet\Anonymous“.
  This means that you will always have a user, no matter the context you are running in.

ENOUGH TALK, LETS CODE

Get a user from the domain name, user name and password:

using System.Linq;
using Sitecore.Common;
using Sitecore.Security;
using Sitecore.Security.Accounts;

namespace PT.Framework.NemLogin
{
  public class UserRepository
  {
    /// <summary>
    /// Gets the <see cref="Sitecore.Security.Accounts.User"/>.
    /// </summary>
    /// <param name="domainName">Name of the domain.</param>
    /// <param name="userName">Name of the user.</param>
    /// <param name="password">The password.</param>
    /// <returns><see cref="Sitecore.Security.Accounts.User"/> if found or null if not found</returns>
    public static User GetUser(string domainName, string userName, string password)
    {
      if (!System.Web.Security.Membership.ValidateUser(domainName + @"\" + userName, password))
        return null;
      if (User.Exists(domainName + @"\" + userName))
        return User.FromName(domainName + @"\" + userName, true);
      return null;
    }
  }
}

The above function demonstrates how you can use the System.Web.Security and the Sitecore.Security namespace simultaneously. The function first validates the user using standard .NET security, then uses the Sitecore namespace to get the user.

Login:

The following function will do a login of a specified user:

using Sitecore.Security.Accounts;

using Sitecore.Security.Authentication;
using Sitecore.Web.Authentication;

public static bool Login(string domainName, string userName, string password)
{
 return AuthenticationManager.Login(domainName + @"\" + userName, password, false);
}

And this function will also do a login, but it utilizes the Sitecore TicketManager. The TicketManager manages persistent logins and is used to remember you when you log into the Sitecore backend:

public static bool Login(User user)
{
  string ticketID = TicketManager.GetCurrentTicketId();
  if (!string.IsNullOrEmpty(ticketID))
    TicketManager.RemoveTicket(ticketID);
  return AuthenticationManager.Login(user);
}

Managing Custom Properties on User Profiles:

This is an example on how to store custom data on a user profile, and later search for the user based on the value in the custom field:

#region

using System.Linq;
using Sitecore.Common;
using Sitecore.Security;
using Sitecore.Security.Accounts;

#endregion

namespace MyCode
{
  public class UserRepository
  {
    public static User GetUserFromCustomField(string fieldName, string fieldValue)
    {
      IFilterable<User> allUsers = UserManager.GetUsers();
      return allUsers.Where(user => user.Profile.GetCustomProperty(fieldName) == fieldValue).FirstOrDefault();
    }

    public static void SetCustomField(User user, string fieldName, string fieldValue)
    {
      UserProfile profile = user.Profile;
      profile.SetCustomProperty(fieldName, fieldValue);
      profile.Save();
    }
  }
}

Read more here:

• Sitecore Security API Cookbook – The essential reading
• Sitecore Membership Providers – The next book you will read
• Working with custom user profiles by Learn Sitecore
• Setting up a Sitecore Extranet by Mark Stiles
• Virtual Users in Sitecore 6 by iStern
• Setting up Security on Languages by briancaos
• Assigning Security to items by briancaos

Have you ever experienced that Sitecore keeps popping the “Do you want to save the changes to the item?” dialog box, even when you have made no changes to the item? And the box keeps appearing, even when you have chosen “yes”?

Save Dialog

This scenario can occur if the contents of any multiline field or textbox field contains new lines \n or carriage returns \r.

Memo Box with \r or \n

In rare situations, the browser will interprete \n and \r differently from Sitecore, thus telling Sitecore that the contents in the box differs from the contents in the Sitecore database.

The situation rarely occurs with manually entered text, but if you have programatically added the text to the box, the \n and \r might misalign.

So if you add text to the multiline field (or textbox field) you should ensure that any \n and \r are removed before adding the text.

I made this string extension method to remove all new lines, carriage returns, tabs and strange \xA0′s (which looks like a space but isn’t):

public static string CleanNewLinesTabsAndOtherStuff(this string s)
{
  return s.Replace("\r\n", " ").Replace("\r", " ").Replace("\n", " ").Replace("\t", " ").Replace('\xA0', '\x20');
}

I replace all of them with spaces, but in other situations you could replace them with string.Empty.

When uploading PDF (or Word/Excel/…) documents to the Sitecore media library, the PDF icon is not shown:

PDF icon Missing

In this case it is only my test server that is not showing the icons. My local development machine (my own laptop) displays the icons perfectly:

PDF icon Shown on my laptop

The reason is that Siteore use the associated icon from the OS. Acrobat Reader is installed on my laptop, not on my test server. So the test server displays a default icon instead.

WHAT’S THE SOLUTION THEN?

You can specify which static file to use for which extension in the web.config. To add the PDF icon, do the following:

Download a .pdf icon from the Adobe Website (due to licensing restrictions, Sitecore is not shipped with an Acrobat Reader icon). Place the icon wherever you wish.

Go to the web.config and find the <mediaType name=”PDF file” extensions=”pdf”> section.

Add the following:

<mediaType name="PDF file" extensions="pdf">
  <mimeType>application/pdf</mimeType>
  <forceDownload>false</forceDownload>
  <sharedTemplate>system/media/unversioned/pdf</sharedTemplate>
  <versionedTemplate>system/media/versioned/pdf</versionedTemplate>
  <!-- New section -->
  <thumbnails>
    <generator type="Sitecore.Resources.Media.MediaThumbnailGenerator, Sitecore.Kernel">
      <extension>png</extension>
    </generator>
    <staticFile>File location. For example /sitecore/shell/Themes/pdficon_large.png</staticFile>
  </thumbnails>
  <!-- end:New section -->
</mediaType>

Clear the following folders:

• /temp/ folder (at least all files named “fileIcon”)
• The Sitecore media cache (default located at /app_data/mediacache/)

Clear your browser cache.

Restart the website.

That’s it. You now have PDF icons in Sitecore.

MORE READING:

• Adding custom icons for the media library
• Sitecore forum post on missing PDF icons

This quick tutorial will guide you trough your first Sitecore Page Editable Component.

The Sitecore Page Editor is build around the concept of components. A component is a reusable piece of data that is parred with a sublayout and placed in a placeholder.

Sitecore Page Editor’

This tutorial will create a very simple component: Adding an Image.

To create components you must go through a series of steps.

STEP 1: CREATE THE TEMPLATE

First you need a Sitecore Template where you store the data. My component must show an image, so all my template contains is an image field called “DocumentImage”:

Document Image Template

STEP 2: FIND A HOME FOR TEMPLATES OF THIS TYPE

Next step is to define a place in your web site structure where you will store templates of this type. Templates of different types can share a folder, or you can create a folder specifically for this type.

You will need the folder in a few steps.

STEP 3: CREATE A SUBLAYOUT

Now you need a sublayout that will present the data from the template.

Document Image Sublayout

When creating the sublayout you must determine the contents of these fields:

• Editable: Check this box. If unchecked, the sublayout is not editable and cannot be used in the Page Edittor as a component.
• Datasource location: Select the folder you chose in STEP 2. When the component is added to a page, this is where the data will be stored.
• Datasource template: Select the template you created in STEP 1. When the component is added to a page, this is the template that is created.

STEP 4: ASSIGN THE SUBLAYOUT TO A PACEHOLDER SETTING

Each placeholder that is capable of having controls added must be defined in the folder /sitecore/layout/Placeholder Settings.

Select the placeholder setting where you would like to allow your control to be added and add it to the “Allowed controls” field:

Placeholder setting

Read more about placeholder settings here.

STEP 5: CODE THE CONTENTS OF THE SUBLAYOUT

When a component is added to a page it is parred to a item through the “datasource” parameter on the layout. This means that you cannot get the data for your component with Sitecore.Context.Item. Sitecore.Content.Item will point to the actual page where the component is added, not the item assigned to the component.

The following method will get the item from the “datasource”, with a fallback to the current item. The fallback is a safety mechanism that ensures that the item returned is never null, as this will crash the entire web page.

protected Item CurrentContextItem
{
  get
  {
    Sublayout thisSublayout = (Parent as Sublayout);
    if (thisSublayout == null)
      return Sitecore.Context.Item;
    if (string.IsNullOrEmpty(thisSublayout.DataSource))
      return Sitecore.Context.Item;
    string dataSource = thisSublayout.DataSource;
    Item dataSourceItem = Sitecore.Context.Database.GetItem(dataSource) ??
                          Sitecore.Context.ContentDatabase.GetItem(dataSource);
    if (dataSourceItem == null)
      return Sitecore.Context.Item;
    return dataSourceItem;
  }
}

(This method of getting the datasource has not changed the last 5 years).

You now assign the Item parameter of the sc:Image webcontrol to CurrentContextItem, and the control will take its data from that item:

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="DocumentImage.ascx.cs" Inherits="PT.Document.DocumentImage" %>
<%@ Register TagPrefix="sc" Namespace="Sitecore.Web.UI.WebControls" Assembly="Sitecore.Kernel" %>

<div class="Image">
  <sc:Image field="DocumentImage" id="Image" runat="server" Item="<%# CurrentContextItem %>" MaxHeight="200" />
</div>

If your component uses an EditFrame you need to get the actual value from the datasource, not the item it points to. In this case you need another method:

protected string DataSourceValue()
{
  Sublayout sublayout = (Parent as Sublayout);
  return (((sublayout == null) || string.IsNullOrEmpty(sublayout.DataSource)) ? string.Empty : sublayout.DataSource);
}

You can now use this method to ensure your EditFrame uses the correct item:

<sc:EditFrame runat="server" ID="editFrame" Buttons="???" DataSource="<%# DataSourceValue %>">
  ...
  ...
</sc:EditFrame>

That’s all there is to it. Happy coding.

More reading:

• Sitecore Recommended Practices – part 6 (Presentation,Page Editor, and Solution Code) by Dan Brown.
• Presentation component reference (PDF Document by Sitecore)

It’s a well known issue that when Sitecore displays a 404 page, it’s done by doing a 302 redirect to the 404 page, hence the 302 status code is thrown before the 404.

The behavior is partially because of the way .net handles redirects internally. But fortunately you can overcome it pretty easily.

My colleague Anders Laub came up with this extension to the Sitecore httpRequestBegin pipeline.

By adding a processor to the pipeline you can switch the missing item with a 404 item inside Sitecore. The item in Sitecore will then have a sublayout that will throw the 404. In effect, Sitecore (or .net) will not know that there is a page missing and will continue the business as usual. It’s up to us developers to handle the 404. Just like we like it.

First the httpRequestBegin processor:

<httpRequestBegin>
  <processor type="Sitecore.Pipelines.PreprocessRequest.CheckIgnoreFlag, Sitecore.Kernel" />
  ...
  ...
  <processor type="Sitecore.Pipelines.HttpRequest.ItemResolver, Sitecore.Kernel" />
  <processor type="MyCode.Custom404ResolverPipeline, MyDll" />
  ...
  ...
</httpRequestBegin>

The processor is added just after the ItemResolver. The ItemResolver returns null if the item is not found.

We then switch the missing item with our 404 item:

public class Custom404ResolverPipeline : HttpRequestProcessor
{
  public override void Process(HttpRequestArgs args)
  {
    Assert.ArgumentNotNull(args, "args");

    // Do nothing if the item is actually found
    if (Sitecore.Context.Item != null || Sitecore.Context.Database == null)
      return;

    // all the icons and media library items 
    // for the sitecore client need to be ignored
    if (args.Url.FilePath.StartsWith("/-/"))
      return;

    // Get the 404 not found item in Sitecore.
    // You can add more complex code to get the 404 item 
    // from multisite solutions. In a production 
    // environment you would probably get the item from
    // your website configuration.
    Item notFoundPage = Sitecore.Context.Database.GetItem("{DFE03D7A-00B9-4C15-8AB7-482D82B3484E}");
    if (notFoundPage == null)
      return;

    // Switch to the 404 item
    Sitecore.Context.Item = notFoundPage;
  }
}

The page we switched to needs to have a sublayout that will do the actual 404 return code:

public partial class _404 : System.Web.UI.UserControl
{
  protected void Page_Load(object sender, EventArgs e)
  {
    HttpContext.Current.Response.StatusCode = (int)HttpStatusCode.NotFound;
    HttpContext.Current.Response.TrySkipIisCustomErrors = true;
    HttpContext.Current.Response.StatusDescription = "Page not found";
  }
}

Remember to set the TrySkipIisCustomErrors or your 404 page will be ignored by IIS 7.5.

MORE READING:

• Kern Herskind has another solution here.
• A Stackoverflow article on the same issue.
• Partech handles the issue as well.

In ASP.NET 3.5 you may encounter one of the following error messages:

“Operation is not valid due to the current state of the object”

or:

“The URL-encoded form data is not valid”

WHY?

Microsoft released a Security update at dec 29 2012. The update contained (amongst other features) an upper bound to the number of simultaneous HTTP form elements that can be posted. The new limit is 1000.

In the Sitecore Page Editor you may experience that for large pages you have more than 1000 form elements.

WHAT TO DO?

To fix this you should add the following to the web.config:

In the <appSettings> of the web.config add the following:

<add key=”aspnet:MaxHttpCollectionKeys” value=”value greater than 1000” />

Thanks to Alin Parjolea for the tip.

The next big release of Sitecore 7 is on it’s way. This time Sitecore have listened to many MVP’s and have adressed some technical issues.

Most of this release revolves around scalability and indexing. The Lucene index have been updated to allow even more impressive performance and even higher scalability. The old Sitecore 6 would easily swallow 1.000.000 items. Sitecore 7 have almost no limitations. Even on folder level, where the old Sitecore 6 stalled at around 200 items at the same level; Sitecore 7 implements a revamped version of Sitecore Item Buckets, allowing you to have an infinite amount of items at the same level.

So what’s next on my wish list? Could I ask for more? Of course. More wants more. Here is the areas where I would like Sitecore to focus on for the first update of Sitecore 7:

SITECORE PAGE EDITOR

AN EXTENSIBLE PAGE EDITOR

We need the Sitecore Page Editor to be extensible, like the rest of Sitecore.

If you wish to add a new field to the Sitecore shell, you write some code, put it in a DLL and points to the field. No modifications to Sitecore itself.

In the Page editor, you need to modify one of Sitecore’s own Javascript files (FieldChromeType.js). This file changes with every version of Sitecore, and you cannot just append your modifications, as you need to modify namespaces and switch statements.

This is bad and very Sitecore-unlike behavior. Sitecore is a platform. You never modify the platform. You extend it. Except for the page editor. Sigh.

PAGE EDITOR LINK FIELD TYPE NEEDS TO ALLOW LOOKUP FIELDS

If you would like to have a link popup box in the page editor, you must have a general link field. The page editor should have a popup for all lookup fields, so you can have fields where only internal links are allowed.

PAGE EDITOR SHOULD HAVE A BUTTON FOR THE MEDIA LIBRARY

A button that opened the media library would be nice please. It’s 10 lines of code. I can give you the code.

PAGE EDITOR SHOULD BE ABLE TO EDIT NON-VISUAL FIELDS

Not all fields are visible. But you should be able to edit them anyway. Thomas Stern made a solution. This should be standard.

PAGE EDITOR SHOULD BE ABLE TO PUBLISH EVERYTHING THAT’S INCLUDED ON THE PAGE

The publish button on the page editor will only publish the current item (and it’s subitems). But most pages have included components. These components are not stored on the item, and often not as children to the current item. When publishing from the page editor, these components should be published as well. Otherwise you cannot publish them from the Page Editor at all.

PAGE EDITOR SHOULD BE CHEAPER TO DEVELOP FOR

This is not a no-brainer. The Page Editor is the coolest thing since sliced bread. Customers are requesting page editable websites more and more often.

Unfortunately, if you are aiming at building a page-editor only website (a website that is edited completely using the page editor) costs explode. The number of lines explode, as you have to consider many more states and exceptions.

You have to add code to allow fields that is hidden if empty to be shown, only in page edit mode. And how do you make a carrousel page editable? And what about the metadata fields?

How do you allow the customer to version pages, if the page consists of components?

All of these simple, little decisions complicate your code, making it more expensive to develop, and more expensive to test.

SITECORE SHELL

ADDING COMPONENTS USING THE SHELL

If you wish to use the Sitecore DMS in it’s full extent you are bound to make a Page Editable website. Why? Because the Page Editor is the only place where you can add components to a page. Components are necessary if you would like to use A/B Testing and Real Time Personalisation.

We need the dialogs for adding components to a page available in the Sitecore Shell.

I would expect the Sitecore Shell to contain the full set of functions, and the Page Editor to be a subset of functionality.

Yes I know that I can use the Presentation->Details button to open the Layout Details and from there I can add my components. But my customer cannot. It’s a developer tool and way too complicated to use.

Please make a user friendly way of adding components to a page from the Sitecore Shell.

CODING

SC:FIELDRENDERER

The sc:FieldRenderer should be able to get a NULL item without crashing. This would remove half of my code lines in my components.

SC:LINK

The sc:Link should be able to use lookup fields and not only the general link field.

SC:EDITFRAME

The sc:EditFrame should accept a Sitecore item instead of a Item path in the DataSource property.

If you try to create a new user in Sitecore with an email address as account name you will be met with a validation error:

“user name is not valid in the selected domain.”

But do not worry, it’s not the underlying security framework that disallows email as username, it’s just a default validation of user names in the user manager dialog box.

The default validation is based on this regular expression: ^\w[\w\s]*$

You can change the regular expression using the AccountNameValidation setting. Add the following to your web.config:

<setting name="AccountNameValidation" value=".+" />

When using the users email address as username, you should consider changing the membership provider in Sitecore to require a unique email. Otherwise you risk having users that share email addresses.

The change is simple. Go to web.config and change the attribute “requiresUniqueEmail” to “true“:

<add name="sql"
type="System.Web.Security.SqlMembershipProvider"
connectionStringName="core"
applicationName="sitecore"
minRequiredPasswordLength="1"
minRequiredNonalphanumericCharacters="0"
requiresQuestionAndAnswer="false"
requiresUniqueEmail="true"
maxInvalidPasswordAttempts="256" />

In the latest version of Sitecore 6.6 (release 13.04.04) I sometimes get this error:

Exception: Sitecore.Security.AntiCsrf.Exceptions.PotentialCsrfException
Message: CSRF form field is missing.
Source: Sitecore.Security.AntiCsrf
at Sitecore.Security.AntiCsrf.SitecoreAntiCsrfModule.RaiseError(Exception ex, HttpContext context)
at Sitecore.Security.AntiCsrf.SitecoreAntiCsrfModule.PreRequestHandlerExecute(Object sender, EventArgs e)
at System.Web.HttpApplication.SyncEventExecutionStep.System.Web.HttpApplication.IExecutionStep.Execute()
at System.Web.HttpApplication.ExecuteStep(IExecutionStep step, Boolean& completedSynchronously)

The issue seemes to be related to an implementation of AntiCSRF, a Microsoft Public License library that prevents Cross Site Request Forgery.

HOW TO FIX IT:

The fix is easy. Clear your cookies, clear the browser cache, close the browser and try again.

UPDATE:

The clever guys at Sitecore Support have come up with this (untested) quick fix that you can try:

Please add these lines to the Sitecore.AntiCsrf.config file (website/app_config/include/Sitecore.AntiCsrf.config):

<ignore wildcard="/sitecore/shell/*Applications/Security/User*Manager*?*Cart_Users_Callback=yes"/>
<ignore wildcard="/sitecore/shell/*Applications/Security/Role*Manager*?*Cart_Roles_Callback=yes"/>
<ignore wildcard="/sitecore/shell/*Applications/Security/Domain*Manager*?*Cart_Domains_Callback=yes"/>
<ignore wildcard="/sitecore/shell/~/xaml/Sitecore.Shell.Applications.Security.SelectAccount*Cart_*_Roles_Callback=yes"/>
<ignore wildcard="/sitecore/shell/~/xaml/Sitecore.Shell.Applications.Security.SelectAccount*Cart_*_Users_Callback=yes"/>

UPDATE 2:

The tough guy could choose to disable AntiCSRF completely. Add the following line in the /App_Config/Include/Sitecore.AntiCSRF.config file:

<?xml version="1.0"?>
<configuration>
  <sitecore>
    <AntiCsrf>
      <rules>
        <rule name="shell">
          <!-- Ingore AntiCSRF completely -->
          <ignore wildcard="/sitecore/*"/>
        </rule>
      </rules>
    </AntiCsrf>
  </sitecore>
</configuration>

Sitecore DMS Engagement plans allow you to control some of the specific ways in which your website interacts and communicates with the visitors to your website. Think of engagement plans as a configurable flow state engine. It allows you to push the responsibility of automation to your customer.

Engagement plans are especially usefull when you have named visitors, ie users with a username and an email.

Engagement plans are controlled through the Sitecore.Analytics.Automation.VisitorManager class and the Sitecore.Analytics.Tracker class.

The Tracker class can be used for connecting a named user to the DMS visitor:

using Sitecore.Analytics;
using Sitecore.Analytics.Automation;

private void CheckAndSetTracker(string userName)
{
  if (Tracker.IsActive)
  {
    Tracker.Visitor.ExternalUser = userName;
  }
}

The userName is a fully qualified name, ie extranet\user.

To assign a user to an engagement plan, simply call VisitorManager.AddVisitor with the ID of the engagement plan state:

public bool AssignToEngagementPlan(User user, ID engagementPlanIdStartState)
{
  bool addVisitor = VisitorManager.AddVisitor(user.Name, engagementPlanIdStartState);
  return addVisitor;
}

The User is the Sitecore.User.

usually you would assign the user to the first step of your engagement plan, but you can in fact assign the user to any state you wish.

You can also move a visitor from one state to another:

VisitorManager.MoveVisitor(userName, source, destination);

You can also search for a specific user in an engagement plan to see is the user is alreay assigned to any state in that engagement plan:

private bool UserIsInAnyEngagementPlanState(string userName, ID engagementPlan, out ID stateId)
{
  var result = false;
  stateId = null;
  foreach (Item state in GetEngagementPlanItem(engagementPlan).Children)
  {
    result = VisitorManager.GetStateVisitors(state.ID).Any(visitor => visitor.Equals(userName));
     if (result)
    {
      stateId = state.ID;
      break;
    }
  }
  return result;
}

That’s basically it. It’s very easy to work with once you get the hang of it.

READ MORE:

• Sitecore Engagement Plan Cookbook.
• Sitecore Engagement Plans as an Audience Segmentation Tool by Mike Casey.
• Applying Advanced Sitecore DMS Capabilities: Engagement Automation by Aaron Branson, Roundedcube.

In Sitecore it is possible to change the sublayouts or data sources on a page depending on conditions. This means that users can see the same page differently, depending on a set of rules. Sitecore comes standard with a set of standard rules (The user’s geographic place, has the user met any goals, has the user been referred etc.).

As always with Sitecore (well, except for the page editor) you can extend Sitecore’s functionality by creating your own rules.

THE EXAMPLE: QUERY STRING CONDITION

This is an example of a rule that checks for a certain QueryString (in this case a ZipCode). If the querystring contains a certain value, the condition is met.

First you need to set up the condition. Conditions are defined in folders below /sitecore/system/Settings/Rules/Segment Builder/Conditions:

My Custom Condition

The cryptic text attribute is used to explain and configure the condition at the same time:

Where the querystring parameter zipcode [operatorid,Operator,,compares to] [value,,,value]

The string is case sensitive. [operatorid,Operator,,compares to] gives you the options “equal to, not equal to, less than, greater than, …”, and [value,,,value] gives you the possibility to enter a value.

Then you need to write the code. This condition compares integers, so I inherit from the IntegerComparisonCondition. There are other conditions to inherit from as well, like the OrCondition, NotCondition, AndCondition, OperatorCondition, BinaryCondition etc.

namespace MyCode.Infrastructure
{
  public class CheckQuerystringCondition<T> : IntegerComparisonCondition<T> where T : RuleContext
  {
    protected override bool Execute(T ruleContext)
    {
      Assert.ArgumentNotNull(ruleContext, "ruleContext");
      var zipCodeQuerystringValue = HttpContext.Current.Request.QueryString["zipcode"];
      int zipCode;
      if (string.IsNullOrEmpty(zipCodeQuerystringValue))
      {
        return false;
      }

      if (!int.TryParse(zipCodeQuerystringValue out zipCode))
      {
        return false;
      }

      return Compare(zipCode);
    }
  }
}

The condition is now ready to be used.  To use it you need to find the layout of the page you wish to personalize. You can see if there is conditions on a layout by the little number mark:

Layout Details

Select the control to personalize and start personalizing. In this example I choose between 2 diferent sublayous depending on the condition. You can also choose to switch the data context (i.e. where the component gets its data from).

Personalize The Component

The personalization is pretty straight forward, and reminds of the way you would set up rules in Microsoft Outlook:

Rule Set Editor

Thanks to Emil Klein for the code.

READ MORE:

• Sitecore Digital Marketing System (DMS) Part 2: Creating Conditions to compare custom values by Oshyn
• Custom Conditions by Karbyn Interactive
• Ruling the DMS Rule Engine, a presentation from the Sitecore Symposium 2012

Or: How Sitecore DMS and Personalization killed the Sitecore.Context.Item. This post is about how to properly ensure that you get data from the correct item when you develop websites that can be personalized.

The Sitecore.Context.Item returns the current item, i.e. the item that corresponds with the URL that the user has entered. Old Sitecore developers like me has been used to adding the fields of a page to the current item, and then accessing these fields directly using the sc:FieldRenderer:

<%@ Register TagPrefix="sc" 
    Namespace="Sitecore.Web.UI.WebControls" 
    Assembly="Sitecore.Kernel" %>

<sc:FieldRenderer ID="MyField" runat="server" 
FieldName="NameOfMyField"  />

This approach is no longer a good approach, as the the customer have been given access to DMS and personalization. Now you no longer know if the content that the usercontrol need, is part of the current item, or another item.

Personalize the Component

The customer can now acces any component he likes, and use personalization to alter the data source (or even the component itself). This breaks the pattern of assuming that content is part of the current item.

So what can we do?

Before we grab any field, we need to go through these steps:

• Check the datasource of the current sublayout
• If the datasource is set, use the item from the datasource
• If not, use the current item

These 2 extension methods ease the process:

namespace SitecoreExtensions
{
  public static class SublayoutExtensions
  {
    public static Item GetDataSourceItem(this Sublayout sublayout)
    {
      string dataSource = sublayout.DataSource;
      if (string.IsNullOrEmpty(dataSource))
        return (Item) null;
      return Context.Database.GetItem(dataSource);
    }
  }

  public static class UserControlExtensions
  {
    public static Item GetDataSourceItem(this UserControl control)
    {
      Sublayout sublayout = control.Parent as Sublayout;
      return sublayout == null ? (Item) null : SublayoutExtensions.GetDataSourceItem(sublayout);
    }

    public static Item GetDataSourceOrContextItem(this UserControl control)
    {
      return UserControlExtensions.GetDataSourceItem(control) ?? Context.Item;
    }
  }
}

The SublayoutExtensions extend the Sitecore Sublayout. The GetDataSourceItem returns the item that the datasource points at, or null if the datasource is not set.

The UserControlExtensions extend the .NET UserControl (that really is the base of a Sitecore Sublayout). The GetDataSourceOrContextItem returns the datasource item, with a fallback to Sitecore.Context.Item.

To use the method, you must add the function to the item property of the sc:FieldRenderer:

<sc:FieldRenderer ID="MyField" runat="server" 
FieldName="NameOfMyField" 
Item="<%# this.GetDataSourceOrContextItem() %>" />

And you must remember to call DataBind().

This pattern is good because you never end up with a NULL item, as sc:FieldRenderer will crash if you feed it with a NULL value in the item property. There is no reason to crash the entire page just because one component is not configured correct.

From code-behind you simply replace Sitecore.Context.Item with this.GetDataSourceOrContextItem:

var text = Sitecore.Context.Item["NameOfMyField"]; // old way
var text = this.GetDataSourceOrContextItem()["NameOfMyField"]; // new way

I would not be surprised if Sitecore in the future would build these functions into sc:FieldRenderer, but untill then we have to do it ourselves.

One of the features that Sitecore introduced somewhere in the Sitecore 6.x range is “Layout Deltas“,  the possibility to merge an item’s layout details with the layout details on the item’s __Standard Values template.

It means that you can add sublayouts to the __Standard Values, and still modify the sublayouts on the actual item, without overwriting __Standard Values.

Because instead of copying all the layout details from the __Standard Values, Sitecore will only keep a difference list on the item, not the entire layout details. Sitecore then uses the XmlDeltas field type to merge the two.

If you look at the raw values in Sitecore, you will see that in the “Layout” field of your __Standard values, the contents look like this:

<r xmlns:xsd="http://www.w3.org/2001/XMLSchema" >
  <d id="{FE5D7FDF-89C0-4D99-9AA3-B5FBD009C9F3}" l="{45D794F6-9DBB-4DBE-9826-606456562FB4}">
    <r id="{153F8C66-033E-456A-9C5F-A98D587C7A7E}" ph="" uid="{DE3402CB-9E79-4539-8C54-1DA8FB8D3733}" />
    <r ds="" id="{69EB7A6D-ACEF-4D06-A923-804918AA245E}" par="" ph="NewsletterHeadSection" uid="{CECCDC8D-3AF8-448D-A527-F8471C139FE9}" />
    <r id="{424A40CD-CAF3-45D9-87BA-CBE88C895A64}" ph="" uid="{48640574-E4FB-433B-97B4-0B202D609CB2}" />
    <r ds="" id="{A5975387-6B3A-4A43-BDF5-2A422057E518}" par="" ph="NewsletterBody" uid="{56CA9222-D31E-400A-B697-B620CF431DFF}" />
    <r id="{E429A2F3-DCFC-416E-ACB1-6BB7DE70C846}" ph="" uid="{7DBE3A38-12AD-42B7-8115-F50121D38B84}" />
    <r ds="" id="{175839E3-AEF4-4830-B679-0F51B90B438E}" par="" ph="NewsletterFooter" uid="{DA53887E-B21F-4C8B-A7D7-C3770B79DDF3}" />
  </d>
</r>

But the “Layout” field of the actual item look like this:

<r xmlns:p="p" xmlns:s="s" p:p="1">
  <d id="{FE5D7FDF-89C0-4D99-9AA3-B5FBD009C9F3}">
    <r uid="{7B831873-DE0D-46AA-AA38-9B5A72A3A1B7}" p:before="r[@uid='{7DBE3A38-12AD-42B7-8115-F50121D38B84}']" s:ds="{C57FBE62-5181-49B8-BF6A-E7CEE7BED209}" s:id="{7CCB9656-AE33-4609-92F0-1FDC5632BB8B}" s:ph="newsletterbody" />
  </d>
</r>

Notice the p:before attribue in the last XML? These are the attributes telling Sitecore how to apply the changes to the finished layout details.

You can do the merge yourself using the XmlDeltas field. This example merges the __Standard values onto the item itself:

using Sitecore.Data;
using Sitecore.Data.Fields;
using Sitecore.Data.Items;

/// <summary>
/// Merge layouts
/// </summary>
/// <param name="destinationItem">Item that receives the merged layouts</param>
/// <param name="standardItem">Item to merge from (the Standard Values usually)</param>
private string MergeLayouts(Item destinationItem, Item standardItem)
{
  LayoutField layoutDestinationItem = destinationItem.Fields[Sitecore.FieldIDs.LayoutField];
  LayoutField layoutStandardItem = standardItem.Fields[Sitecore.FieldIDs.LayoutField];
  string deltaLayout = XmlDeltas.ApplyDelta(layoutDestinationItem.Value, layoutStandardItem.Value);
  destinationItem.Editing.BeginEdit();
  try
  {
    destinationItem.Fields[Sitecore.FieldIDs.LayoutField].Value = deltaLayout;
    destinationItem.Editing.EndEdit();
    return deltaLayout;
  }
  catch (Exception ex)
  {
    destinationItem.Editing.CancelEdit();
    throw new Exception("Updating '" + destinationItem.Paths.FullPath + "' failed: " + ex.ToString());
  }
}

It is the XmlDeltas.ApplyDelta that executes the merging.

Please notice that if you merge from __Standard Values, and later modify the item that was merges, Sitecore will identify the merge, and “unmerge” your merged item. It does so using the XmlDeltas.GetDelta() method:

string deltaLayout = XmlDeltas.GetDelta(layoutDestinationItem.Value, layoutStandardItem.Value);

MORE INFORMATION:

• Complex layouts in Sitecore using standard values hierarchy by Cognifide.
• Unsharing the Layout field in Sitecore – a multi-language strategy by Jan Hebnes
• What is Layout Deltas by Adam Conn

When using Sitecore Email Campaign Manager, you might encounter the following error:

The target device layout does not include ‘Process Personalization Tokens’ sublayout and ‘Target Item’ rendering, you may encounter this error for every variant in this message, if you have admin right to fix variant ‘A’, please click here to start the Layout dialog.

ECM Error

The error does not only occur if the rendering and the sublayout is missing, but also if they are placed imporperly:

• The “Target Item” render needs to be the first rendering.
• The “Process Personalization Tokens” needs to be the last rendering.

Peoper placement of the 2 renderings

To do this you must place the Process Persinalization Tokens sublayout in a non-editable placeholder. This placeholder must be placed at the bottom of the control stack, as described in the image above.

Furthermore, do not use __Standard Values. ECM cannot find the Target Item and Process Personalization Tokens controls if they are located in the __Standard Values of the message root item.

You must copy all the controls to the actual item and delete the controls from the layout field of the __Standard Values. If you have added controls to the item with the page editor you will need to merge the layouts from __Standard Values to the item. See this arcticle on how to merge layout details.

When installing Sitecore and DMS, Sitecore comes pre-installed with an Executive Insight Dashboard Report that will generate a report containing which search words users have executed in your local search page.

All you need to do is to register a Page Event called “Search” on your search result page:

using Sitecore.Analytics;
using Sitecore.Analytics.Data;

protected void RegisterSearchPageEvent(string searchQuery)
{
  if (!Tracker.IsActive || Tracker.Visitor == null || Tracker.Visitor.CurrentVisit == null)
    return;

  var page = Tracker.Visitor.CurrentVisit.CurrentPage;
  if (Tracker.Visitor.CurrentVisit.PreviousPage != null)
    page = Tracker.Visitor.CurrentVisit.PreviousPage;

  page.Register(new PageEventData("Search")
  {
    Data = searchQuery,
    DataKey = searchQuery.ToLowerInvariant(),
    Text = searchQuery
  });
}

What happens behind the scenes is that the search terms (the parameter “searchQuery” is registered as a page event on the current page. The page event “Search” is defined in Sitecore:

Page Event “Search”

And a SQL Query Report is defined to get the visits per data query.

SQL Query

And the Executive Dashboard is configured to display the search terms from this SQL Query (you will find the report under “Site Search“):

Dashboard displaying the search terms

Please note that the report will not display any data below 50 hits, unless you configure this in the .config file located here:

\sitecore\shell\Applications\Reports\Dashboard\Configuration.config

Look for the setting called “MinimumVisitsFilter“. This filter determines how many (or how few) visits are required before they are considered a significance.

In the demo above, I have set the value to “5″:

<ConfigurationParams>
  ...
  <MinimumVisitsFilter value="5" />
  ...
</ConfigurationParams>

Also note that this setting influences every report in the Executive Dashboard, so be careful not to set it too low or it will slow down other reports significantly.

READ MORE:

• Tracking Local Search with DMS by Coffee=>Coder=>Code
• Sitecore 6.6 Executive Insight Dashboard not get loaded from StackOverflow

This article explains how you can get the hierarchy of placeholders and render them to your screen for debugging or documentation purposes.

The Sitecore rendering engine allows you to place sublayouts inside placeholders. These sublayouts can contain more placeholders, thus creating a hierarchy of placeholders inside a page.
This hierarchy can get pretty complex. So the following code demonstrates how you can read the layout from an item, the placeholders from a layout or sublayout, which renderings will be rendered where and how to write it all to an XML document that will show you which sublayout contains which placeholders and which renderings is rendered where.

STEP 1: THE BASIC METHODS:

First i give you the basic methods for getting layout, placeholder and rendering information. These methods can be copied into your own project directly:

  /// <summary>
  /// Return all placeholder keys defined on one item
  /// </summary>
  private IEnumerable<string> GetPlaceholderKeys(Sitecore.Data.Items.Item item)
  {
    List<string> uniquePlaceholderKeys = new List<string>();
    Sitecore.Layouts.RenderingReference[] renderings = GetRenderingReferences(item, "default");
    foreach (var rendering in renderings)
    {
      if (!uniquePlaceholderKeys.Contains(rendering.Placeholder))
        uniquePlaceholderKeys.Add(rendering.Placeholder);
    }
    return uniquePlaceholderKeys;
  }

  /// <summary>
  /// Search for all placeholder controls in a specific file and return all the placeholder keys
  /// </summary>
  /// <param name="relativePath"></param>
  /// <returns></returns>
  private IEnumerable<string> GetPlaceholderKeysFromFile(string relativePath)
  {
    string text = System.IO.File.ReadAllText(HttpContext.Current.Server.MapPath(relativePath));
    string pattern = "<sc:Placeholder (.*?) />";
    MatchCollection matches = Regex.Matches(text, pattern, RegexOptions.IgnoreCase);
    foreach (Match match in matches)
    {
      string keyPattern = @"Key=""(.*?)""";
      Match keyMatch = Regex.Match(match.Value, keyPattern, RegexOptions.IgnoreCase);
      yield return keyMatch.Value.Replace("Key=", "").Replace("key=", "").Replace("\"", "");
    }
  }

  /// <summary>
  /// Return all renderings to be rendered in a specific placeholder on the "default" device
  /// </summary>
  private IEnumerable<Sitecore.Data.Items.RenderingItem> GetRenderings(string placeholderKey, Sitecore.Data.Items.Item item)
  {
    Sitecore.Layouts.RenderingReference[] renderings = GetRenderingReferences(item, "default");
    foreach (var rendering in renderings)
    {
      if (rendering.Placeholder == placeholderKey)
      {
        yield return rendering.RenderingItem;
      }
    }
  }

  /// <summary>
  /// Return all renderings from an item defined on a device
  /// </summary>
  private Sitecore.Layouts.RenderingReference[] GetRenderingReferences(Sitecore.Data.Items.Item item, string deviceName)
  {
    Sitecore.Data.Fields.LayoutField layoutField = item.Fields["__renderings"];
    Sitecore.Layouts.RenderingReference[] renderings = layoutField.GetReferences(GetDeviceItem(item.Database, deviceName));
    return renderings;
  }

  /// <summary>
  /// Get the layout from an item defined on a device
  /// </summary>
  private Sitecore.Data.Items.LayoutItem GetLayout(Sitecore.Data.Items.Item item, string deviceName)
  {
    Sitecore.Data.Fields.LayoutField layoutField = item.Fields["__renderings"];
    return new Sitecore.Data.Items.LayoutItem(item.Database.GetItem(layoutField.GetLayoutID(GetDeviceItem(item.Database, deviceName))));
  }

  /// <summary>
  /// Convert a Sitecore item to a Sublayout item
  /// </summary>
  private Sitecore.Data.Items.SublayoutItem GetSublayout(Sitecore.Data.Items.Item item)
  {
    return new Sitecore.Data.Items.SublayoutItem(item);
  }

  /// <summary>
  /// Get the device item from a device name
  /// </summary>
  private Sitecore.Data.Items.DeviceItem GetDeviceItem(Sitecore.Data.Database db, string deviceName)
  {
    return db.Resources.Devices.GetAll().Where(d => d.Name.ToLower() == deviceName.ToLower()).First();
  }

  /// <summary>
  /// Get all placeholder settings that defines the specified placeholderKey
  /// </summary>
  private IEnumerable<Sitecore.Data.Items.Item> GetPlaceholderSettings(Sitecore.Data.Database db, string placeholderKey)
  {
    Sitecore.Data.Items.Item root = db.GetItem("/sitecore/layout/Placeholder Settings");
    foreach (Sitecore.Data.Items.Item descendant in root.Axes.GetDescendants())
    {
      if (descendant.Template.Key != "placeholder")
        continue;
      if (descendant["Placeholder Key"].ToLowerInvariant() == placeholderKey.ToLowerInvariant())
        yield return descendant;
    }
  }

Each of these methods can be used individually, but will reference each other some times.

To get all placeholders (i.e. the placeholder “keys” which is the unique definition of a placeholder) that contain renderings, call GetPlaceHolderKeys().

To get all placeholders that is defined in a file, call GetPlaceholderKeysFromFile(). This method uses a Regular Expression to extract all the <sc:Placeholder /> definitions found inside a source file.

To get all renderings that is rendered to a specific placeholder, call GetRenderings().

STEP 2: GET THE HIERACHY OF RENDERINGS:

Here is how to use the methods. These 2 functions will render an XML structure of the hierarchy of layouts, sublayouts, placeholder etc. You should replace /sitecore/templates/somepage/__Standard Values with the page you wish to get the hierarchy from:

  void Page_Load(object sender, System.EventArgs e)
  {
    Sitecore.Data.Database db = Sitecore.Configuration.Factory.GetDatabase("master");
    Sitecore.Data.Items.Item item = db.GetItem("/sitecore/templates/somepage/__Standard Values");

    Response.Write(string.Format(@"<template name=""{0}"">", GetLayout(item, "default").Name));
    foreach (string s in GetPlaceholderKeysFromFile(GetLayout(item, "default").FilePath))
    {
      RenderPlaceholders(s, item);
    }
    Response.Write("</template>");
  }

  private void RenderPlaceholders(string placeholderKey, Sitecore.Data.Items.Item item)
  {
    IEnumerable<Sitecore.Data.Items.Item> placeholderSettings = GetPlaceholderSettings(item.Database, placeholderKey);
    int settingsCount = placeholderSettings.Count();
    bool editable = placeholderSettings.Any(i => i["Editable"] == "1");
    Response.Write(string.Format(@"<placeholder key=""{0}"" editable=""{1}"">", placeholderKey, settingsCount, editable));

    foreach (var rendering in GetRenderings(placeholderKey, item))
    {
      Response.Write(string.Format(@"<sublayout name=""{0}"">", rendering.Name));
      foreach (string s in GetPlaceholderKeysFromFile(GetSublayout(rendering.InnerItem).FilePath))
      {
        RenderPlaceholders(s, item);
      }
      Response.Write(@"</sublayout>");
    }
    Response.Write(@"</placeholder>");
  }

The method will output something like this:

<template name="Default">
  <placeholder key="SeoRegion" editable="0">
    <sublayout name="MetaTags"></sublayout>
    <sublayout name="DocumentDescription"></sublayout>
    <sublayout name="OpenGraph"></sublayout>
  </placeholder>
  <placeholder key="phPageHolder" editable="1">
    <sublayout name="DefaultPage">
      <placeholder key="DefaultColumn1" editable="0">
        <sublayout name="DefaultPage">
        </sublayout>
      </placeholder>
    </sublayout>
  </placeholder>
  <placeholder key="ScriptsRegion" editable="0">
    <sublayout name="GoogleAnalytics"></sublayout>
  </placeholder>
</template>

That’s it. Happy coding.

In Sitecore you cannot compare an ID with NULL; it will produce the following error:

The call is ambiguous between the following methods or properties: ‘Sitecore.Data.ID.operator ==(Sitecore.Data.ID, Sitecore.Data.ID)’ and ‘Sitecore.Data.ID.operator ==(Sitecore.Data.ID, Sitecore.Data.ShortID)’

I.e. the following code is invalid:

Sitecore.Data.ID someID = GetSomeID();
if (someID == null)
{
  // do code
}

Instead, you need to call Sitecore.Data.ID.IsNullOrEmpty():

ID someID = GetSomeID();
if (Sitecore.Data.ID.IsNullOrEmpty(someID))
{
  // do code
}

A quick tip for you.

You probably have never used a code generator for the same reason I never used a code generator:

• It was not developed by yourself
• It’s not generating the code you need
• You cannot extend it with the stuff you need
• They create the same code for all of your Sitecore templates
• It’s difficult to install
• It was not developed by yourself.

A code generator that creates an O/R relationship between your Sitecore templates and your code can save you a ton of work though:

• Automatically update your code when new templates are created
• There is never any mismatch between your code and Sitecore templates
• Code class names matches Sitecore template names
• All field names are mapped correctly

That is why I introduce the open-source, freeware, use-as-you-please:

SITECOREORM, The object/relational code generator for Sitecore.

You can download it here for free, including the source code:

SitecoreORM

http://marketplace.sitecore.net/en/Modules/SitecoreORM_Object-relational_Code_Generator.aspx

The SitecoreORM is a code generator framework that allows you to create code templates based on well-known user controls (.aspx) pages, and generate code from all of your Sitecore templates.

There is no Sitecore package; all you do is to place the code in your solution and call \sitecore modules\Shell\SitecoreORM\Execute.aspx to execute the code generation.

Out of the box, SitecoreORM generates simple classes that maps all fields on a Sitecore template, references to inherited templates, and a static struct of field names to be used by Sitecore’s sc:FieldRenderer.

But the idea behind SitecoreORM is that you define yourself how your classes should look like.

Changing the output is done by simply changing some .aspx pages. For example, the code template is an .aspx page. This is an example of how it looks (simplified, download the code for the complete example):

namespace <%# Namespace %>
{
  public class <%# ClassName %> : BaseItem
  {
    public <%# ClassName %>(Item innerItem)
    {
      InnerItem = innerItem;
    }

    public Item InnerItem { get; private set; }

    public override FieldCollection Fields
    {
      get { return InnerItem.Fields; }
    }

    #region Inherited Templates
<%# ExecuteCodeProvider("SomeClass, SomeDll", "SomeParameter") %>
    #endregion
  }
}

Generating fields, inherited templates or other thing you need, is done using code providers, that you plug in. SitecoreORM uses reflection to find the code, and your class only needs to implement an ICodeProvider interface that has 1 method: Get().

Here is an example of an .aspx file that generates a Sitecore field (a CheckBox field):

<%@ Page Language="C#" AutoEventWireup="true" %>
<%@ Import Namespace="Sitecore.Data.Items" %>
<%@ Import Namespace="SitecoreORM.CodeProviders" %>
<%@ Import Namespace="SitecoreORM.Services" %>
<script runat="server">

  void Page_Load(object sender, System.EventArgs e)
  {
    DataBind();
  }

  private TemplateFieldItem Field
  {
    get { return GenerateFieldProperties.Field; }
  }

  private string PropertyName
  {
    get { return NameNormalizerService.GetValidName(Field.Name); }
  }

</script>

    /// <summary>
    /// <%# TemplateFieldItemCommentService.GetComment(Field) %>
    /// </summary>
    public Sitecore.Data.Fields.CheckboxField <%# PropertyName %>
    {
      get { return InnerItem.Fields["<%# Field.Name %>"]; }
    }

The SitecoreORM framework is written with the fewest lines of code that will do the job. The code is as simple as possible, making it easier to extend, and for you to understand.

Features of SitecoreORM includes:

• O/R mapping Sitecore templates to C# code.
• Every aspect of the code generation can be customized:
  • .aspx page based code generation allows you to choose the class format yourself.
  • Each field type from Sitecore can be mapped by .aspx pages, making it easy to determine how each field type from Sitecore should be mapped.
  • Inherited templates can be mapped as well.
  • Field names can be mapped to be used by sc:FieldRenderer
  • Plug in your own code; SitecoreORM uses reflection to find the code generators.
• Customizable output using an include file (/app_config/include/sitecoreorm.config)
  • Determine class name suffixes
  • Determine name space prefixes
  • Determine removing of parts of template path from namespace
  • Determine file destination for generated classes
  • Specify which template folders to ignore (for example /system/ and /common/)
  • Specify which template folders to include
  • Specify file destination for each template folder to include, hence supporting component based development
• Simple code. Less than 20 classes makes up the framework. 5 services and one repository does most of the job.

Check out SitecoreORM here:

http://marketplace.sitecore.net/en/Modules/SitecoreORM_Object-relational_Code_Generator.aspx

Here is a small tip for you who is doing API’s based on Sitecore. How to get an item from the Sitecore Media Library and stream it to the HttpResponse of a page.

This is an example of an .ashx HttpHandler class that gets the ID of an Sitecore Media Library item and streams the item. Add your own exception handling as you wish.

using System;
using System.Net;
using System.Web;
using Sitecore.Data.Items;
using Sitecore.Diagnostics;
using Sitecore.Configuration;

namespace MyProject
{
  public class GetImage : IHttpHandler
  {
    public void ProcessRequest(HttpContext context)
    {
      // ID of media item
      string id = context.Request.QueryString["id"];

      // Get media item
      MediaItem item = (MediaItem)Factory.GetDatabase("web").GetItem(id);

      // Get name to be shown when image is saved
      string imageName = item.Name + "." + item.Extension;

      context.Response.Clear();
      context.Response.ContentType = mediaItem.MimeType;
      context.Response.AppendHeader("Content-Disposition", string.Format("inline;filename=\"{0}\"", imageName));
      context.Response.StatusCode = (int)HttpStatusCode.OK;
      context.Response.BufferOutput = true;
      // Copy the media stream to the response output stream
      mediaItem.GetMediaStream().CopyTo(context.Response.OutputStream);
      // As momma always said: Always remember to flush
      context.Response.Flush();
      context.Response.End();
    }

    public bool IsReusable
    {
      get
      {
        return false;
      }
    }
}

The trick lies within the type casting of an Item to a MediaItem. The MediaItem contains a media stream that can be copied to the OutputStream of the HttpResponse.

Another trick is to construct a file name from the item name + the file extension found on the MediaItem. Adding this to the output stream will make the name appear as the default file name when users saves your file.