I’ve been using Sitecore for nearly a year now. During this time, I’ve worked mostly with the content management side of Sitecore, dabbling here and there in developing custom templates and the occasional XSLT rendering. As I’ve worked with these, I’ve been quite impressed with how easy Sitecore makes the management and integration of all the pieces that go into making a web site. This has compelled me to spend a lot of time trying to expand my knowledge of the platform.
During a recent and unusually slow weekend, I happened to come across the SDN documentation about Sitecore’s Sheer UI which, I came to find out, is a quite robust set of features that developers can leverage to create custom applications within Sitecore based on a combination of C#, XAML, and the Sitecore API.
Not having a great deal of knowledge about any of these, I was, at first, somewhat hesitant to try it out. However, curiosity got the best of me and, to my great delight, I quickly found that developing custom functionality within Sitecore is a snap, and requires only a basic knowledge of the technologies involved.
On with the Walkthrough!
In this article, I’ll walk through the process of creating a very basic application within Sitecore. While the Sitecore article about the same subject does a pretty good job, it does presuppose knowledge about several aspects of the process that, to someone like me, might not be readily apparent. What I will NOT cover is the code for the application itself. I think there’s benefit in working through that piece on your own, and you can install the application yourself and rip the source code apart.
Before we begin, you’ll need a way to compile C# code. While there are a lot of ways to do this, I’ll use Microsoft’s free Visual Web Developer—it’s basically a stripped down version of Visual Studio. Once you have this installed, go ahead and open it up and keep it open—we’ll come back to it later.
Next, log in to whatever development environment of Sitecore that you’ll be using—be sure you’re on the Sitecore desktop.
Now, for the most important part of this whole tutorial:
SWITCH OVER TO THE CORE DATABASE!
We’ll be spending a lot of time here. :)
Ok! We’re ready to begin!
Step 1: Defining our Application
So what are we building? For this walk through, we’ll start creating a small app that we’ll call “Lock Manager.” This app will let us view all the “locks” (not just our own) that exist on items in the content database, and will provide the option to unlock selected locks. Additionally, we’ll add an option to open a selected item to view its contents, as well as a “nuclear” option to unlock all items.
For this particular example, we will be using a combination of XAML (Extensible Application Markup Language), C#, and the Sitecore API (although the tutorial will not cover any of the latter).
Step 2: Create an XML Layout
Now that we’ve defined what we want our application to do, let’s jump right in and start building it! The very first thing we’ll need to do is to create a new XML layout—this will be the file, full of XAML syntax, that handles the presentation of our application.
Remember when I said you should switch over to the core database? Double-check that you have! Once you’re sure you’re in the core database, open up the Developer Center. From the File menu, choose New. In the dialogue window that appears, browse to the Layouts folder and choose XML Layout.
When you’ve selected the correct file type, click Create.
Next, the New File Wizard will ask you to name your XML Layout file. Let’s call it “Lock Manager”.
After you’ve named the file, Sitecore will create a content item that represents (and points to) the file that it will also create on the file system. You’ll be asked where to put the new content item. You can change the location if you’d like, but for this example we’ll simply click Next and retain the default Layouts location.
Next, you’ll be asked to select the location on the file system where the new XML Layout file will be created. Again, you can specify a custom location, but we’ll go ahead and click Create and use the default layouts folder.
After a few seconds of processing, you should receive a confirmation message that Sitecore has successfully created the new XML Layout. Click “Finish” to close out the wizard.
You should now see the default XML that Sitecore has created for the XML Layout file in the Developer Center. The important thing to pay attention to here is the <CodeBeside> tag. While we won’t go into right now, go ahead and make note of the value of the Type attribute—we’ll need it for later.
Ok, so let’s take a step back. What did we just do? Let’s take a look.
Minimize (or close) the Developer Center and open up the Content Editor (remember, still on the core database). Under the root sitecore node, expand the Layouts item. You should see a content item with the name of the new XML Layout that we just created—in this example, “Lock Manager.”
If you select the Lock Manager item and view the Quick Info, you’ll see that we created a new content item with the “Xml Layout” template, which has only 2 data fields: Control and Path. While more explanation could be probably be given, the Control value references the namespace of the C# code that we will create later on, while the Path points to the file that Sitecore created for us on the file system (the one with the <CodeBeside> tag that we saw earlier). Pretty straightforward, right?
Step 3: Create a New Application
Now that we’ve successfully created an XML Layout, we need to create a new “application” in Sitecore. A Sitecore “application,” like the XML Layout we just created, is pretty simple. So let’s create one.
First, open up the Content Editor (remember, we’re still on the core database!) and expand out the Applications node under sitecore/content. You should see a list of applications that you’re probably quite familiar using, like the Carousel, Content Editor, Control Panel, etc. With the Applications node selected, right-click and choose to insert a new “Application.”
When prompted, give the new application a name (“Lock Manger” for our example), and choose OK.
In the new application item that’s created, you should see the Display name field filled out with the name you gave the application, as well as a default icon path. Let’s go ahead and change the icon value to “Network/32x32/lock.png”, just so we have something besides the boring, default application icon :).
Ok, our new application item is almost done. The last thing we need to do is to apply the XML Layout we created earlier to our application so that it looks like something when we load it up. We’ll do this by adjusting our application’s Presentation Details.
With the Lock Manager application selected, go to the Presentation tab in the Sitecore ribbon and choose Details from the Layout chunk.
In the Layout Details dialogue window that appears, click Edit to modify the presentation details for the Internet Explorer device.
In the Device Editor dialogue window that appears, choose the Layout tab on the left. From the drop-down menu to the right, browse to the XML Layout that we created earlier (it’s called “Lock Manager” in this example).
Once you’ve selected the correct layout, choose OK to close the Device Editor window, and OK again to close the Layout Details window.
That’s it! We have a fancy new application!
So what did we just do?
Well, as you remember we created an XML Layout that will eventually hold all of XAML code to define the “look” and “contents” of our application, as well as point to the C# code that will access the API, define logic for our app, etc.
Having this file is great, but we had nothing to really hook it to. This is what the “application” we just made does. By applying the XML Layout to the presentation details of the application, we have specified that our application should use the XAML and C# which are bundled up in the XML Layout to manage what our app will look like and how it will function.
Step 4: Create a Shortcut to Our Application
This next step is a little out of order. You’ll see why in a few minutes—however, it does make sense to do it now. After all, we’re working in Sitecore, so why not finish up all the steps while we’re here?
In this step, we’re going to create a link item in the Sitecore Start menu so that we have a handy way to launch our fancy new application whenever we want to.
To do this, browse to the Documents and Settings node. Expand it out until you get to the Left folder. With this item selected right-click and choose to insert a new Application shortcut.
As before, give the new item a name (“Lock Manager”) and hit OK.
In the Data section of the new application shortcut item, you’ll see a few fields of interest. The first is the Icon field. For the sake of consistency, let’s go ahead and use the icon from before: “Network/32x32/lock.png”
Next, fill out the Tool tip with a brief description of the app—let’s put “Manage all the locks”.
Finally, and most important, is the Application field. Here, we will define the Sitecore application that we want to run when we click on this shortcut. Right above the field, choose Insert Link. In the Internal Link dialogue window that appears, browse to the application we just got done making – Lock Manager. Click OK to select it and close the window.
At this point, it’s EXTREMELY important to recognize something quirky that Sitecore does. When inserting the link to our XML Layout, Sitecore has assumed that our application is based on an .aspx file—you’ll see the .aspx extension on the end of the name of our application. We need to remove this. Otherwise, our application will simply not work.
All said and done, our new link should look something like this:
Creating the shortcut is pretty straightforward, so to recap let’s look at what we’ve accomplished.
Since we’re done in the core database, let’s jump back over to the master database. Now, if we open the Start menu, we should see a shortcut to our application with the proper name, tooltip, and icon.
To set the stage for what comes next, go ahead and run the application. You should see a nasty error message that looks something like this:
While it looks scary, it’s actually expected. Because we haven’t yet created any code for the site (remember back to the mention of the <CodeBeside>…), our application is looking for specific resources, not finding them, and telling us about it. It actually means we’re on the right track!
From this point on, we’ll be leaving Sitecore for a while and living in Visual Studio (or whatever we are using to edit our code and compile it). Go ahead and leave Sitecore open, but just be aware that we’re now shifting into a completely different environment :)
Up to this point, we’ve done quite a bit. We’ve created an XML Layout, as well as a new “application” within Sitecore. We’ve also created a handy shortcut to launch our app, but quickly found that doing so created an error. As pointed out before, this error stems from the fact that our application is looking for resources that just aren’t there.
But what “isn’t there?” In the error message, the piece that is conspicuously missing s “Sitecore.LockManager.dll,” the compiled version of the code that we’ll be creating. If you remember back to our very first step, we had a reference to this file in our <CodeBeside> tag on our XML Layout. When our application loads the XML layout, it processes this path, looking to find the requested DLL. Since it’s not there, our app chokes, fails, and complains angrily about it.
So what we need to do to fix this is to fill in the missing piece—we need to create our DLL. But before we can do this, we need to create our first C# file.
Before we dive in, let me be completely forthcoming--I not going to even attempt to explain a C# file. For the purposes of our app, we can think of it as the “brains” of our application. With it we’ll create functionality and tap into the Sitecore API to retrieve data, manipulate it, and tell the XAML in our XML Layout how to display it.
So instead of trying to explain it, let’s just create it :)
Step 5: Create a Visual Studio Project
The first step to creating the C# file is to create a new project in Visual Studio. You can do this by going to File -> New -> Project in Visual Studio.
In the New Project dialogue window that opens, you’ll see a TON of options for types of projects. Don’t worry about the number of choices. Simply expand out the Visual C# node, click on the Web option, and choose ASP.NET Web Application. (You can most definitely use others, but I think this one’s pretty easy to work with).
With ASP.NET Web Application selected, name the project “LockManager” (no spaces) and make sure that the Create Directory for solution option is checked. When all this looks in order, click OK to create the project. Visual Studio will do its thing, and should bring up the Default.aspx page of your new VS project. Go ahead and close this as we will not need it.
Ok, before moving forward, take note of the Solution Explorer to the right of your screen. You should see a tree view of all the assets that Visual Studio has created for your project. Become familiar with this as we’ll be moving in and out of it quite a bit through the next couple steps.
Step 6: Import Sitecore References
Before we create any code, it will be important to import a new Reference to a key Sitecore DLL. This will allow us to leverage the Sitecore API within the code that we’ll eventually create.
To import the Sitecore reference, expand the References node in the Solution Explorer. Right-click on References and choose Add Reference.
In the dialogue window labeled Add Reference that appears, click on the Browse tab and browse to the bin folder of your Sitecore installation (mine is C:\inetpub\www\Sitecore\WebSite\bin). Choose Sitecore.Kernel.dll and click OK to choose the item.
Now, in the References node, you should see the Sitecore.Kernel reference added.
FINALLY! We’re ready to add some code!
Step 7: Create a C# File
To create the C# file that will drive most of our app, right click on the root of the project (“LockManager”), hover your mouse over Add, and select Class.
In the Add New Item that appears, you’ll see a list of new items that you can create, although the Class item will be selected by default. Leave this selected, and then name the item “LockManager.cs”.
Once Visual Studio is done working its mojo, you should see something like the following:
Since our application will leverage the Sitecore API references almost exclusively, we can get rid of a bunch of the default System. references preloaded at the top of our C# file. We will, however, want to add in a Sitecore reference. We’ll drill into this with more specificity as the app gets built out, but for now let’s just add the top level reference.
Ok, now we have a brand new class that we can reference within Sitecore to pull in all of our delicious application goodness. Before moving on, let’s compile our code and test it out.
To compile, first save the LockManager.cs file. Then, under the Build tab, choose Build Solution.
Once you do this, if you’ll direct your attention to the Output panel (in the bottom right of VS), you should see the status of the build process. The important thing to pay attention to here is that you receive a “Build: 1 succeeded” message.
This means exactly what it sounds like: our code compile was successful and we can deploy.
So let’s do just that. First, open up the bin folder of your Sitecore solution.
In another window, open up the bin folder of your LockManager Visual Studio project.
EX: C:\Documents and Settings\<name>\My Documents\VS 2008\Projects\LockManager\LockManager\bin
In your VS project’s bin folder, you’ll see a bunch of DLLs. Ignore all of them except for the LockManager.dll and LockManager.pdb.
Select both and copy them to your Sitecore installation’s bin folder.
Step 8: Hooking it All Up
At this point, we should technically have all the right pieces in place to launch our application. Sure, there will be nothing to see, but we can at least launch the shell of our app. So let’s fire it up!
Go back to Sitecore and launch the application.
WTF! Still the same error! We must have done something wrong, right?
Well, yes, and my apologies for doing this intentionally. However, it is for good reason.
Look again at the error message. The specific reason that for the application failure is that Sitecore.LockManager.dll cannot be found. But didn’t we just upload that?
Not exactly. We uploaded LockManager.dll—a small, but obviously important difference. Where, then, is this reference to Sitecore.LockManager.dll coming from?
If you remember back—waaaaaayyyyyy back—to our first step, we created our XML Layout. In the code that Sitecore automatically generated, we saw the <CodeBehind> chunk (I told you to pay attention to it ). In this one line of code, Sitecore automatically created a pointer to a file with the name of Sitecore.LockManager.dll. Since ours is named differently, the applications chokes and will not work. Sure, it’s frustrating, but expected.
So what can we do to fix it?
- One approach might be to just rename the DLL. However, we will have to rename it every time we rebuild the solution in Visual Studio, as the default will be whatever our project is named. That’s going to be a pain.
- Another approach would be to go back to Visual Studio and completely rework our project to match up with the naming convention “Sitecore.LockManager”. Decent enough, but it’s going to require a bunch of changes, and if we miss something we’ll get stuck hunting down this or that bit in Visual Studio to modify, just to get the right result (which we haven’t even seen yet :)
- Honestly, the easiest thing to do is simply to change the reference on our XML Layout file! Browse to your Sitecore installation’s layouts folder and open up the Lock Manager.xml file (I’d open it in Visual Studio, just to keep all our code in the same application).
In the file, you’ll see something like this:
In the part that says Sitecore.LockManager, simply remove “Sitecore.”, so that the final result is:
Now, save this file, go back to Sitecore, and reload the application.
Whoa! Another error!?!
Yes, but if you’ll notice, it’s a different one this time. The previous fix that we implemented worked…we just have another to take care of :)
In this error, our application fails because the class LockManagerForm cannot be found. If we look back to our C# file, we’ll notice that the only class in the namespace LockManager is itself named LockManager. We could rename the class in our C# file, but that will require a rebuild. Instead, let’s just switch back over to Lock Manager.xml, and modify the <CodeBeside> like so:
We can now reload our app…and…success!
It’s a blank, generic Sitecore window! Sure, it’s boring, but it means that our application officially works—e.g., that all the pieces are successfully wired up.
And this is precisely why we walked through painful process of looking at these errors. From my limited experience, getting all the parts wired up is really about 50% of the battle—the rest is the interesting part of actually creating code and layout. However, the latter cannot happen if the wiring is bad, so we walked through the various errors so you’ll know how to debug them in the future, leaving you more time to spend on the more interesting parts of the process.
Step 9: Get Your Hands Dirty
Now that we’ve successfully created and wired up our XAML application in Sitecore, we’ve laid the ground work for building out the rest of the application. I’m not going to go into all the details for building this particular app—you can download the source code and dig through it yourself. I make no claims to it being anything great or even “best practice.” Furthermore, as I’m no C# or XAML guru (nor claim to be), I know there are quite possibly TONS of areas where the code can (or should :)) be improved. However, I think it is simple enough to follow what’s going on, and there are a bunch of comments to explain everything that’s happening. Besides, the best way to learn is to stumble across the answers through trial and error on your own.
I hope this walk through is helpful as you start building XAML applications in Sitecore.
You can download the source from Joel's Lock Manager here and se the video he made of it here