Exercise 15-1. Creating a Bare-Bones Site Definition

In this exercise, you will create a site definition containing only what is absolutely required to get the site running.

1. In your Solution Explorer, under the 12TEMPLATE folder, add a new folder corresponding to the four-digit LCID of your language.

   The LCID defines for which language the site definition will be created. These LCIDs correspond to the language packs you have installed, so check the [12]TEMPLATE folder to see which language pack LCIDs are installed. For English, the LCID is 1033. I will be using 1033.

2. In the 1033 folder, create a new folder called XML.
3. In the XML folder, add a new XML file, and call it something like webtempEmpireTimes.xml.

   The important thing about the file name is that it must start with the string webtemp and must end in .xml. In the previous step, you can change EmpireTimes to whatever you like as long as you adhere to the other two naming rules.

   Note I will refer to this file as the webtemp file later.

4. Back in your 12TEMPLATE folder in the Solution Explorer, add a new folder called SiteTemplates.
5. Under SiteTemplates, add a new folder called EmpireTimes.

   Unlike with the webtemp file, the naming of this folder is important and should match the configuration we will add to the webtemp file later. You may change this, but you also need to update the webtemp file. I'll talk more about that a bit later in this chapter.

6. In the 12SiteTemplateEmpireTimes folder, add a new folder called XML.
7. In the new XML folder, add an XML file called onet.xml.

   Note I will refer to this file as the onet file later.

   Look at Figure 15-1 for how the final structure should appear.

   

   Figure 15-1. Final site definition structure

   It's time to add some content to these files.

8. In the webtemp file, add the following XML code:
   <?xml version="1.0" encoding="utf-8"?>
<Templates xmlns="Microsoft SharePoint">
  <Template Name="EmpireTimes" ID="20000">
    <Configuration
      ID="1"
      Title="Empire times web site"
      Hidden="FALSE"
      Description="Empire times web site, including all our creative effort."
      ImageUrl="/_layouts/images/[image].png"
      DisplayCategory="Empire Times" >
    </Configuration>
  </Template>
</Templates>

   The Template element is discussed in Chapter 4, so I will only outline the important bits here.

   The ID of the single Template element must be unique in your farm and should be greater than 10,000. Microsoft has reserved site template IDs below 10,000 for future expansion. Of course, Microsoft is not very consistent in this. If you have access to MOSS, check out the template ID of the Records Center. It is 14483, so stay away from that number as well if you have MOSS installed.

   The template Name attribute is what maps to the folder we created to hold the onet.xml file earlier. If you change the folder name, you also need to update the Name attribute of the Template element.

   Finally, the ID of the Configuration element must be unique within a Template element, but not much else. The number is used when you create new site using code where you would address this particular site configuration as EmpireTimes#1.

   At this point, you can deploy your solution and see your new site definition appear when you go to one of the site creation pages, either from Central Administration or from the root site itself. You may want to do this just to test that the webtemp file is working as expected. Or take a look at Figure 15-2, which shows my result. Don't create a site yet, though, because the lack of content in the onet file will cause the creation to crash.

   

   Figure 15-2. Site definition added to the Create site collection page

   On to the onet file.

9. In your onet .xml file, add the following code. We will expand this code later, so for now it is extremely crude:
   <?xml version="1.0" encoding="utf-8" ?>
<Project xmlns="http://schemas.microsoft.com/sharepoint/">
  <Configurations>
    <Configuration ID="1"
                   Name="EmpireTimesWebSite"
                   Title="Empire times web site"
                   >
    </Configuration>
  </Configurations>
  <DocumentTemplates></DocumentTemplates>
  <NavBars></NavBars>
</Project>

   By adding this XML code, we now have a creatable site definition. Of course, it is still empty, so going to the front page will yield a 404 error. We'll add more cool stuff later, but first we should take a look at what we have done up to this point.

Exercise 15-2. Improving the Site: Step 1

In this exercise, you will add to your site definition and make it easier to implement the EmpireTimes solution.

1. Open the onet file. Inside the Configuration Id="1" element, add a new child element:
   <ExecuteUrl Url="_layouts/settings.aspx"/>

   This addition makes sure that when we create a new site, we automatically end up on the Site Settings page of the new site. However, this works only for sites created from an existing site, in other words, from the Create page. If you create a new site collection from the Central Administration web site, you still get sent to the root URL of the new site collection.

   We can make this a bit better, however. In Chapter 6, we looked at the UseRootFolderForNavigation property of the list template element. This property relied on the WelcomePage property of the folder for a list. If that property is set, links to the root of the list—in other words, http://lab-s02:10000/lists/News—will go to the address stored in WelcomePage instead of the default view for the list.

   It turns out that we can use this property on the root folder as well. You can test this by setting the WelcomePage property using SharePoint Manager. Look at Figure 15-3. The effect is that going to the root of the site, as in http://lab-s02:10000/, will send the user to the welcome page instead of the normal default.aspx.

   

   Figure 15-3. WelcomePage property of root folder

   Let's set this property to a custom page as part of our setup.

2. In the FeatureAdded method in your TimesSetup.cs class, add the following piece of code:
   // Set custom home page
SPFolder root = web.RootFolder;
root.WelcomePage = "categories.aspx";
root.Update();

   It's not perfect, but it's better than nothing. We still need a better way of activating features so we do not have to remember the correct order or risk problems related to missing features.

3. In your EmpireTimes solution, add a new Feature with Receiver item. Make it web scoped, and name it something like TimesSetup. As usual, remove all the throw new Exception lines from the methods in TimesSetup.cs.
4. In the FeatureActivated method of the TimesSetup.cs file, add the following code:
   SPWeb web = (SPWeb)properties.Feature.Parent;
Guid g;
g = new Guid("[FEATURE GUID OF TimesArticleCategoriesList]");
web.Features.Add(g);
g = new Guid("[FEATURE GUID OF TimesSiteColumns]");
web.Site.Features.Add(g);
g = new Guid("[FEATURE GUID OF TimesContentTypes]");
web.Site.Features.Add(g);
g = new Guid("[FEATURE GUID OF TimesLists]");
web.Features.Add(g);
g = new Guid("[FEATURE GUID OF TimesCategoryPage]");
web.Features.Add(g);

   Replace the string in the GUID constructors with the feature ID of the respective features.

   OK, this at least ensures that we get our features activated in order. Now all we need to do is activate the single TimesSetup feature, and all should be well.

Exercise 15-3. Improving the Site: Step 2

In this exercise, you will manipulate the built-in QuickLaunch menu and the top navigation bar. You will do this using .NET code because it gives you nice insights into how the navigation works. Plus, it is more flexible to do this through code.

1. In the FeatureActivated method of the TimesSetup.cs file, add the following code after any existing code:
   // Quicklaunch navigation
SPNavigationNodeCollection quickLaunch = web.Navigation.QuickLaunch;
for (int i = 0; i < quickLaunch.Count; i++)
{
    quickLaunch[0].Delete();
}

   This code removes any existing QuickLaunch menu items.

2. Continue by adding a root menu item as such:
   SPNavigationNode aboutUs = new SPNavigationNode("About us", "/");
quickLaunch.AddAsFirst(aboutUs);

   The SPNavigationNode constructor in this case takes two parameters. The first is the text to be linked, and the second is the URL to which the link will go. The constructor may also take a third parameter, a Boolean that is set to True to signify that the link is an absolute URL rather than a relative URL.

   Note If you use a relative URL like we are doing here, SharePoint will check whether the URL goes to an existing page and will throw an exception if the page does not exist.

   Next we simply add the SPNavigationNode to the QuickLaunch menu. But we want more, right? Let's add some child elements.

3. Add the following code after the previous lines:
   SPNavigationNode contact = new SPNavigationNode("Contact form", "/");
aboutUs.Children.AddAsFirst(contact);
SPNavigationNode map = new SPNavigationNode("Map", "/");
aboutUs.Children.Add(map, contact);

   Note the use of two different methods for adding the first and second nodes. In the Add method of SPNavigationNodeCollection, like the Children property is here, you need to specify both the node to add and the preceding node. Here we add the contact node first, but since it is the first node, we can use the AddAsFirst method.

   The same applies to the quicklaunch object we got in step 1. The first item is added with quicklaunch.AddAsFirst, and any subsequent items are added using the Add method. Go ahead and explore this if you like.

   For now you can build, deploy or upgrade, and then recycle IIS. Yes, you need to recycle IIS to avoid assembly caching. Then deactivate and reactivate the setup feature.

Exercise 15-4. Improving the Site: Step 3

Yeah, that's right campers; it is time to put the final piece of our puzzle in place, the top navigation bar. I can hear you all crying that we are almost finished and there is no more book left. Well, dry your eyes, matey; this ship is coming to port.

1. In the TimesSetup.cs file, in the same place as the previous two exercises, add the following code:
   SPNavigationNodeCollection topNavigationBar = web.Navigation.TopNavigationBar;
for (int i = 0; i < topNavigationBar.Count; i++)
{
    topNavigationBar[0].Delete();
}

   As for the QuickLaunch example, this simply makes sure we empty any existing items in the menu.

2. Continue with this code, which is again rather similar to the previous example:
   SPNavigationNode newsNode = new SPNavigationNode("News", "categories.aspx");
topNavigationBar.AddAsFirst(newsNode);

   Note that I have linked the News item to the categories.aspx page. I'll show you why in a moment.

3. You'll want more items. Add some! Such as:
   // Horizontal items
SPNavigationNode localNews = new SPNavigationNode("Local news", "/");
newsNode.Children.AddAsFirst(localNews);
SPNavigationNode weather = new SPNavigationNode("Weather", "/");
newsNode.Children.Add(weather, localNews);
SPNavigationNode sports = new SPNavigationNode("Sports", "/");
newsNode.Children.Add(sports, weather);

   The comment is optional; the rest is not.

   Note Yes I realize hard-coding links like this is bad practice. I am doing this to show you how to modify the navigation, not to be a saint. That train left the station a long time ago, and the ticket was too expensive for me.

4. (Optional) Did you know that the menus also support child elements? Try this:
   // Child items
SPNavigationNode soccer = new SPNavigationNode("Soccer", "/");
SPNavigationNode golf = new SPNavigationNode("Golf", "/");
SPNavigationNode football = new SPNavigationNode("Football", "/");
sports.Children.AddAsFirst(soccer);
sports.Children.Add(golf, soccer);
sports.Children.Add(football, golf);

   Now, for the last time, build, deploy or upgrade, recycle IIS, and then. . .poof! The object reference is not set to an instance of an object. No menu. So close but no cigar. Let's see what went wrong.

Exercise 15-5. Marveling at Your Creation

This one is the simplest exercise. This is where you brand yourself with the proverbial crown of glory, raise your hands toward the sky, and feel the rush of success.

1. Delete your current site collection. Create a new site collection based on the EmpireTimes site definition. And now, to make the crowd go wild...

2. Go to the root of your new site. Yeah, just click the link from the site collection creation receipt.

I will let the applause from the audience, along with Figure 15-6, speak for itself.

Figure 15-6. Something to make you proud