September 16, 2010

Custom Error Pages

whoops

One of the important steps of any website is setting it up to fail Nicely. Sitecore has done a lot of this for us with their error pages, but that may not be the look you want your visitors to see! And what if Sitecore isn’t able to help at all? Not so pretty with ASP.NET error pages…

But do not fear! With the configuration files Sitecore makes available, this is a snap to set up and fix.***

***You Will need to change the web.config file, so please back it up before making any changes suggested here!

The first and hardest step – make your error/not found pages that you want your visitors to see – these can be html pages, aspx pages, or even an existing page within Sitecore.

Quick Edit!-- As a commenter pointed out: using Sitecore pages for your 404/page not found type errors can allow you to make use of the Sitecore features for multilingual sites as well as analytics. Not to mention, it makes it very easy for business users to make the changes.

Usually Sitecore will handle your errors nicely, but if .NET explodes you will need to display something to the user that will Not fail, so I’d VERY STRONGLY recommend an html page for errors and not aspx pages: if there’s an error in the error page, you’re back to square one.

Upload these files to your Website directory or a subfolder within it – for our example we have saved the files in Website/ErrorPages/.

If you’re using Sitecore Items, set those up within your content tree and publish them (somewhere other than where your html error page resides to keep things simple).

Now for the magic: In the website folder is a folder called App_Config and inside that is the Include folder. This folder automagically updates the web.config with new settings – it doesn’t require anything to be restarted and immediately takes effect. Also – using these files instead of modifying the web.config directly means you can make web.config type changes in packages without completely destroying the site.

There should be a file in that directory called: SitecoreSettings.config.example

This is what we will be changing into SitecoreSettings.config and adding our custom ‘not found’ page details.

Currently the file looks like this, along with some comments describing the use of the file at the top:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<
sitecore>
<
settings>
<!--
REQUIRE LOCK BEFORE EDITING
If true, the user must have a lock on a document before
he can edit it, otherwise it is always ready for editing
-->
<
setting name="RequireLockBeforeEditing" value="false"/>

</
settings>
</
sitecore>
</
configuration>

We are going to erase this, and put in the following:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
<
sitecore>
<
settings>
<
setting name="ItemNotFoundUrl">
<
patch:attribute name="value">/ErrorPages/404.html</patch:attribute>
</
setting>
<
setting name="LinkItemNotFoundUrl">
<
patch:attribute name="value">/ErrorPages/404.html</patch:attribute>
</
setting>
<
setting name="LayoutNotFoundUrl">
<
patch:attribute name="value">/ErrorPages/404.html</patch:attribute>
</
setting>
<
setting name="ErrorPage">
<
patch:attribute name="value">/ErrorPages/Error.html</patch:attribute>
</
setting>
</
settings>
</
sitecore>
</
configuration>

The above basically tells the web.config file to update the specified settings with our new and improved values.

You can choose other files to use or have different files for each – and these special pages do not stop any logging from happening on the server – they simply give a better experience for your users when your site is having some trouble. 

ItemNotFoundUrl and LinkItemNotFoundUrl will come up when a visitor tries to access an item that doesn’t exist or hasn’t been published (it doesn’t exist yet on the web database). This replaces the default value of: /sitecore/service/notfound.aspx with our own /ErrorPages/404.html

You’ll notice that the default is pulling from /sitecore/service ß if you have blocked this directory or don’t have it available, you will need to make the changes above so that users see Some kind of page instead of a browser default.

LayoutNotFoundUrl will come up when the user tries to visit an item that does exist, but no layouts have been assigned to the item so Sitecore doesn’t know what to display for the user. This replaces /sitecore/service/nolayout.aspx in the default web.config file.

ErrorPage should come up whenever there is a generic error within Sitecore – the default setting we are overwriting is: /sitecore/service/error.aspx

Save your new file without the .example extension and you should now see your custom error pages whenever you try to access missing items!

The next step is the change to the web.config for handling errors when sitecore can’t handle them for us – save a backup of your web.config and then open it up in an editor.

Here is what we are looking for:

<!--  CUSTOM ERROR MESSAGES
Set customError mode values to control the display of user-friendly
error messages to users instead of error details (including a stack trace):

"On" Always display custom (friendly) messages
"Off" Always display detailed ASP.NET error information.
"RemoteOnly" Display custom (friendly) messages only to users not running
on the local Web server. This setting is recommended for security purposes, so
that you do not display application detail information to remote clients.
-->
<
customErrors mode="On" />

Search for customErrors to find it quickly. It may also have one of the above settings, RemoteOnly or Off. I would recommend On or RemoteOnly if you won’t have visitors accessing the site locally.

We want to change the setting to also include a redirect to our new Error page:

<customErrors mode="RemoteOnly" defaultRedirect="/ErrorPages/Error.html"/>

Now, if anything serious should happen, your users will not end up seeing an ASP.NET error page telling them it is broken and will instead get to see a page of your choice! This should Not point to a page you have in Sitecore since it will not work in the case of ASP.NET failing.

Anyone have any tips on making the user experience better in the case of errors?

September 1, 2010

Sitecore Training: Sitecore 6.2 .net Developer Series Experiences

128739161_5a5c4eaf3d_z

At the beginning of August, I was able to go out to Mill Valley, CA for the .net developer series training at Sitecore USA Headquarters. The course was 4 days of Sitecore goodness, with a certification and a day of hands-on building with Sitecore. Once I found out I would be heading to training, I spent a fair bit of time trying to find out what it would be like and searched for details of the certification without much luck. So for those out there who want to know a little bit more before you’re in the thick of things, here is what happened for me!

The quick and dirty description, for those who want to avoid the wall of text: I’d say this training is a must for any developer switching over to Sitecore – without it, it can be really hard to get the whole picture of the product and really see what it is capable of. Even for those of us who had been using Sitecore for a bit before training (there were a number of us in the class), it was very useful to see how to do things the ‘Sitecore way’ and to learn a few things that are just not available through searching alone. The Fundamentals day will introduce you to what Sitecore is all about and why you should be so excited to use it – it will also show you how to begin using it as a developer or user. The two developer days will give you a good background for doing most tasks that will be requested from clients, and the day of prototyping will give some hands-on practice in doing just that. Also, certification will grant you access to other areas of SDN and the ability to request support through them for the product. It’s also part of your company becoming a Sitecore Partner.

So... here are my experiences, from beginning to end... after the cut!