Sheer UI: 2 - Hello World

With the previous article explaining a bit about what Sheer UI is, setting up a hello world will make much more sense. For this, I'm going to setup the XML control and supporting class file and then give examples of calling them from Applications and Item Editor Tabs

Code Behind

Let's start by creating the class file that is referenced by the XML control. I'll provide an example for both the "control" and "xamlControls" types below.

"control" example

I created a class named HelloWorld and it will inherit from the Sitecore.Web.UI.Sheer.BaseForm in the Sitecore.Kernel assembly. There are also a few other base classes you can inherit from that live in the Sitecore.Web.UI.Pages namespace depending on what you are trying to do. Here's the class code I'm going to be using for this example:

using System;
using System.Web;
using Sitecore;
using Sitecore.Diagnostics;
using Sitecore.Web.UI.HtmlControls;
using Sitecore.Web.UI.Sheer;

namespace MyLibrary {
     public class HelloWorld : BaseForm {

          protected Literal ltlOut;

          protected override void OnLoad(EventArgs e) {
               Assert.ArgumentNotNull((object)e, "e");
               base.OnLoad(e);
              
               ltlOut.Text = string.Format("Querystring: {0}", HttpContext.Current.Request.Url.Query);
           }
     }
}

"xamlControls" example

I created a class named XamlHelloWorld and it will inherit from the Sitecore.Web.UI.XamlSharp.Xaml.XamlMainControl in the Sitecore.Kernel assembly.

using System;
using System.Web;
using Sitecore.Diagnostics;
using Sitecore.Web.UI.HtmlControls;
using Sitecore.Web.UI.XamlSharp.Xaml;

namespace MyLibrary {
     public class XamlHelloWorld : XamlMainControl {
         
          protected Literal ltlOut;

          protected override void OnLoad(EventArgs e) {
               Assert.ArgumentNotNull((object)e, "e");
               base.OnLoad(e);

               ltlOut.Text = string.Format("Querystring: {0}", HttpContext.Current.Request.Url.Query);
           }
     }
}

To be able to reference the controls on the front end, you'll need to add a reference to them here with the ID name matching the ID attribute value on the front end. Sitecore handles populating the control when the class is constructed. In the event a control reference is null, it can be difficult to determine why. Try adding a runat="server" attribute on the XML control or make sure to check the control name id name and casing as well as properly closing the control. Also make sure to set the security on the class reference to at least protected. Setting it to private would not work. In this example, I'm displaying the querystring parameters, which can provide context for you depending on where you launch the control from. For example: Applications only provide the XML control name whereas Item Editor Tabs provide the item ID, language, version, database and other useful context information.

XML File

The next step is to create an xml file. For this example and for yourself, I recommend creating a folder under /sitecore modules/shell.

"control" example

I'm going to name this control "HelloWorld" and create the following file here: /sitecore modules/shell/helloworld/HelloWorld.xml. The contents of that file will look like this:

<control xmlns:def="Definition" xmlns="http://schemas.sitecore.net/Visual-Studio-Intellisense">
     <HelloWorld>
          <FormPage>
               <CodeBeside Type="MyLibrary.HelloWorld,MyAssembly"/>
               <Literal ID="ltlOut" runat="server"/>
          </FormPage>
     </HelloWorld>
</control>

"xamlControls" example:

I'm going to name this control "XamlHelloWorld" and create the following file: /sitecore modules/shell/helloworld/XamlHelloWorld.xaml.xml. The contents of that file will look like this:

<xamlControls
  xmlns:x="http://www.sitecore.net/xaml"
  xmlns:ajax="http://www.sitecore.net/ajax"
  xmlns:rest="http://www.sitecore.net/rest"
  xmlns:r="http://www.sitecore.net/renderings"
  xmlns:xmlcontrol="http://www.sitecore.net/xmlcontrols"
  xmlns:p="http://schemas.sitecore.net/Visual-Studio-Intellisense"
  xmlns:asp="http://www.sitecore.net/microsoft/webcontrols"
  xmlns:html="http://www.sitecore.net/microsoft/htmlcontrols"
  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    
     <XamlHelloWorld x:inherits="MyNamespace.XamlHelloWorld,MyAssembly">
          <Sitecore.Controls.HtmlPage runat="server">
               <Literal ID="ltlOut" runat="server" />
          </Sitecore.Controls.HtmlPage>
     </XamlHelloWorld>
</xamlControls>

Applications

When you want to setup a Sheer UI Application, you need five basic parts: the code behind file (with the functionality), the xml file (with xml markup referencing the code behind), the layout (referencing the xml file), the application (referencing the layout) and the shortcut (referencing the application). Since we already defined the first two, we'll just need the last three.

Layout Item

Now that we have a control file, we need create a layout reference in Sitecore to it. To do this log into Sitecore's Desktop application and change to the Core database. Open up the content editor and browse to core:/sitecore/layout/Layouts and, to help with organization, insert a plain old folder named "Modules". From that modules folder, right-click and "insert from template" and select the core:/sitecore/templates/System/Layout/Xml layout and name it "HelloWorld".

"control" example

On the "HelloWorld" layout item fill out the "Control" field with "HelloWorld". The "Control" field value is what is used by Sitecore to identify the name of the control from the xml file, not the file name or class it references.

"xamlControls" example

On the "HelloWorld" layout item fill out the "Path" field with "/sitecore/shell/~/xaml/XamlHelloWorld.aspx". The "Path" field value is what is used by Sitecore to identify the url by referencing the name of the control from the xml file, not the file name or class it references.

Application Item

Applications live in the Core database under core:/sitecore/content/Applications. I'm going to add a common folder named "Modules", again for organization, for my application to live in. Then right-click and "insert from template" on this folder and select the template core:/sitecore/templates/Sitecore Client/Applications/Application.

This item will now need to have the "HelloWorld" layout item applied through the presentation details, so select the item, jump to the presentation tab and click on the details button and set the layout to the one just created. In my case the layout file is located at core:/sitecore/layout/Layouts/Modules/HelloWorld.

Now it's worthwhile to select an item icon so that it's more readily identifiable. When you do, copy the path to the icon you chose and paste it into the "Icon" field on the item. Then fill out the "Display Name" and "Tool tip" fields.

On the item there's an appearance field section. This will allow you select the dimensions and look and feel of the application. There's a few checkbox fields that will change the display and a few drop down fields. The only one worth mentioning is the "Chrome" field. There's several types of "Chrome" or window treatments. Leaving the field empty will default the application to "WindowChrome". For this example I'm going to leave this value blank but here's how each value affected the display of my application

BorderWindowChrome has no top toolbar which means it's non-draggable.

ToolWindowChrome has a partial top toolbar with the window control buttons (minimize, maximize and close) which allows it to be draggable

ContentEditorChrome has a partial top toolbar with the window control buttons and the application name which allows it to be draggable.

WindowChrome has a full toolbar across the top with the window control buttons, the application name and icon. It is also draggable.

WindowFrame pops open a bare window with no link in the desktop tool bar. It's more like an alert or confirm window.

BorderlessChrome displays nothing. possibly a daemon/service app.

Shortcut Button

Now that you've got your application setup, the last part is to create a shortcut button in the start menu to launch the application. Shortcuts live in core:/sitecore/content/Documents and settings/All users/Start menu. Before you create this item, you'll want to consider the audience when you choose where to put the button. If you check the security on the Left, Right and Programs folders you'll see that the read is disabled for Client Users. This is to allow each button or group to be allowed only by specific client roles. I don't want to go into modifying any permissions for this example so I'm just going to create the shortcut in the Development Tools folder and inherit the permissions there. To create this shortcut right-click on core:/sitecore/content/Documents and settings/All users/Start menu/Right/Development Tools and insert "Application shortcut" and name it "Hello World". For reference the template is core:/sitecore/templates/Sitecore Client/Applications/Application shortcut.

Once you've created the item, you'll want to set the icon to match the application. Then select the application item with the Insert Link button on the "Application" field but once you've clicked ok, click into the field and remove the ".aspx" from the path otherwise the application won't display in the navigation. It's annoying. And a bug. This results in the "Application" field value looking like this: /Applications/Modules/HelloWorld. If you're on Sitecore 7, the fields are not storing the path value, only the ID so you'll have to go to view and edit the raw value of the field. Add the attribute url="/Applications/Modules/HelloWorld". Then finish it off the shortcut by populating the "Display name", "Icon" and "Tool tip" fields.

Now refresh your browser and open the start menu and click into Development Tools and there's the Hello World or Xaml Hello World button.

Now you're ready to run the application. So click away to start the application.

If you're using the "control" example, you'll see the querystring value each time you open the application like this: ?xmlcontrol=HelloWorld but if you're using the "xamlControls" example it will be blank.

Item Editor Tabs

The editor tab is altogether different from an application. As far as I can tell it only supports the newer "xamlControls". An editor has four basic parts: the code behind file, the xml file, the editor item (referencing the xml file) and a template's Standard Values' editor list. The first two we already created, so we just need the last two. If you're not sure what an editor tab is, I'm referring to the tabs used on a folder item which shows a list of its subitems.

Editor Item

To show a XAML control in an items editor tab, you'll need to create an editor tab item in the core database at core:/sitecore/content/Applications/Content Editor/Editors. Right-click and insert a common folder. I'm naming mine "Modules" and then right-click, "insert from template" and select the core:/sitecore/templates/Sitecore Client/Content editor/Editor template and name the new item "EditorHelloWorld". 

Then set the "Header" and "Icon" fields. The "Url" field will not be a file path but instead an odd mix of file path and custom nomenclature: /sitecore modules/shell/~/xaml/HelloWorld.aspx.

Template's Standard Values

The template is where the control will be viewed so switch to the master database and go into master:/sitecore/templates/Sample/Sample Item/__Standard Values (or any standard values item). Editors should be applied to the Standard Values item like Presentation Details etc. Then, in the ribbon, click on the "Configure" tab and click the "Editors" button. 

Inside the dialog window, select the /Modules/EditorHelloWorld item and click ok.

Now you can view the tab by re-clicking on the standard values item or selecting an instance from the content tree. When you view the editor tab, you'll see the querystring value like this:

?id=%7b9DFBB778-512F-4BA7-8293-C01503572D30%7d&la=en&language=en&vs=1&version=1&database=master&readonly=0&db=master. 

These are all available context parameters you can use to display information or provide custom editor functionality for the item.

You can also read the article I wrote about setting up a Rich Text Editor Button if you're curious about how to do that as well. The next article will delve deeper into the syntax of the XML controls.