DevExpertise

In my last two posts here and here I began describing how to integrate a custom ASP.NET application into SharePoint.  The first post focused on the essentials, and detailed how to get your application into the SharePoint LAYOUTS folder structure, specifically where to place your files and how to inherit SharePoint’s look and feel by using its master page.  The second post focused on configuring permissions for your application and also demonstrated a few handy built-in controls that you can leverage to give your application that true SharePoint-like integrated look and feel.

This post will explain how to add custom navigation for your application.  There are a few different approaches that I like to take depending on the application, and I’ll demonstrate a couple of them for you.  These can be used in any combination in order to achieve the navigation you’re aiming for.  In fact, I recommend a combination of these to achieve a fully integrated navigation structure.

Approach #1: Quick Launch Navigation
Now, modifying the Quick Launch navigation menu is a trivial task.  Simply go to Site Actions > Site Settings and find the settings to modify the navigation (Quick Launch on team sites, and Navigation on publishing sites), and add and remove nodes to your heart’s content.  While this manual method works just fine, it’s just that: manual.  I always have the mindset of if I’m already deploying an application somewhere, I might as well automate as much of the setup steps as I can.  Luckily through the use of features we are able to accomplish this easily.

For the sake of brevity, I am going to assume you know what a SharePoint feature is, what a solution package is, and how to create and deploy them.  If not, there are plenty of great resources out there that will help you out.  Anyways, the first step is to create the feature and associated feature receiver that will execute when the feature is activated on the site.  The feature receiver is going to utilized the SharePoint Object Model to create navigation items.

The first step is to create the feature receiver, which must inherit from the SPFeatureReceiver class and must implement the standard 4 feature operations: FeatureActivated, FeatureDeactivated, FeatureInstalled, and FeatureUninstalled.  For this post I’m only adding the items in the FeatureActivated event, but it’s probably a good idea to clean these up in the FeatureDeactivated event in case the feature is ever deactivated.  My feature receiver looks like this:

namespace DevExpertise.LayoutsApp {
    public class FeatureReceiver: SPFeatureReceiver {
        public override void FeatureActivated(SPFeatureReceiverProperties properties) {
            using (SPWeb site = (properties.Feature.Parent as SPWeb)) {
                // create the nodes
                SPNavigationNode widgetManagementNode = new SPNavigationNode("Widget Management",
                    SPUrlUtility.CombineUrl(site.Url, "DevExpertise.LayoutsApp/WidgetMgmt.aspx"), true);
                SPNavigationNode viewWidgetsNode = new SPNavigationNode("View Widgets",
                    SPUrlUtility.CombineUrl(site.Url, "DevExpertise.LayoutsApp/WidgetList.aspx"), true);
                SPNavigationNode addWidgetNode = new SPNavigationNode("Add Widget",
                    SPUrlUtility.CombineUrl(site.Url, "DevExpertise.LayoutsApp/AddWidget.aspx"), true);
                SPNavigationNode widgetSettingsNode = new SPNavigationNode("Modify Widget Settings",
                    SPUrlUtility.CombineUrl(site.Url, "DevExpertise.LayoutsApp/WidgetSettings.aspx"), true);

                // add the Widget management node to the menu (must be done first)
                site.Navigation.QuickLaunch.AddAsLast(widgetManagementNode);

                // add the sub-items to the Widget Management node
                widgetManagementNode.Children.AddAsLast(viewWidgetsNode);
                widgetManagementNode.Children.AddAsLast(addWidgetNode);
                widgetManagementNode.Children.AddAsLast(widgetSettingsNode);

                // update the site
                site.Update();
            }
        }

        public override void FeatureDeactivating(SPFeatureReceiverProperties properties) {
            // do nothing
        }

        public override void FeatureInstalled(SPFeatureReceiverProperties properties) {
            // do nothing
        }

        public override void FeatureUninstalling(SPFeatureReceiverProperties properties) {
            // do nothing
        }
    }
}

As you can see, it’s not complicated at all.  Simply add as many SPNavigationNodes as you like!  The next step is to tell the feature to execute the custom feature receiver.  For that just add the ReceiverAssembly and ReceiverClass elements to your feature definition file:

<?xml version="1.0" encoding="utf-8"?>
<Feature
  Id="5856617E-BED2-4705-B030-735F7483225E"
  Title="DevExpertise Layouts Application"
  Description="Contains the necessary components for the DevExpertise custom LAYOUTS application."
  Version="1.0.0.0"
  Scope="Web"
  Hidden="false"
  ImageUrl="DevExpertise\devexpertiseLogo.png"
  ReceiverAssembly="DevExpertise.LayoutsApp, Version=1.0.0.0, culture=neutral, PublicKeyToken=d39eedb6cff9b1c8"
  ReceiverClass="DevExpertise.LayoutsApp.FeatureReceiver"
  xmlns="http://schemas.microsoft.com/sharepoint/">
</Feature>

Once the feature is properly installed, it will show up under Site Features (note that this is scoped at the site level, and will need to be activated on each site):

Cross your fingers, activate it, and you should the new navigation items:

Not too shabby for a few lines of code, huh?  You’re just as able to add items to the top navigation if you so desire too. 

Approach #2: Custom Actions

One of my favorite things about SharePoint is the ability to extend just about anything, making it a true application development.  Menu items are no exception, and they’re painfully simple to implement.  You are able to add a custom link to the Site Actions menu, Site Settings menus, list menus, individual item menus, Central Administration menus, etc.  If SharePoint has a menu somewhere, chances are you’re able to add your own item to it.  There are 2 ways to do this and I’ll only be demonstrating it one way.  In a future blog post I’ll show how to do all this stuff programmatically for an even more robust navigation structure.

For this sample Widgets application, I would like to take the navigation a bit further and add an item to the Site Actions menu and also create a group in Site Settings that will allow me to manage my application.  To accomplish this, I added a new element manifest to my feature called CustomActions.xml, which will define our custom actions.  Per MSDN, custom action files are included as part of a feature and deployed as XML element descriptions, and structured with a CustomAction element, which serves as the core definition for a single action of a link or toolbar item. The following is my CustomActions.xml file, which defines a single action for the Site Actions menu:

<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction
    Id="ManageWidgetAction"
    GroupId="SiteActions"
    Location="Microsoft.SharePoint.StandardMenu"
    Sequence="1"
    Title="Manage Widgets"
    Description="Manage your company's widget catalog."
    ImageUrl ="/_layouts/images/actionssettings.gif"
    Rights="ManageWeb,ManageLists">
    <UrlAction Url="~site/_layouts/DevExpertise.LayoutsApp/ManageWidgets.aspx" />
  </CustomAction>
</Elements>

Let’s break this down a little bit:

• Id.  The ID of your custom action.
• GroupId. A pre-defined or custom that determines what group it will be placed into.  A comprehensive list of built-in values can be found here.
• Location.  The location at which your custom action will be applied.  A comprehensive list of built-in values can be found here.
• Sequence.  The order in which your custom action will appear in relation to other custom actions.
• Title.  The display title of the action.
• Description.  The description of the action, if applicable.
• ImageUrl. The image that is displayed next to the action, if applicable.
• Rights.  A comma delimited list of SPBasePermission enumeration items.  A comprehensive list of values can be found here.
• RequireSiteAdministrator.  A true/false value indicating if this option is only visible to the site collection administrator.
• UrlAction: This element defines where the link will take you.  Be sure to specify either the ~site or ~sitecollection token which tells SharePoint to build the URL relative to either the site or site collection, respectively.

Simply modify the feature to include this element manifest, redeploy it, reactivate it, and you should see the following in your Site Actions menu:

Easy, huh?  Let’s take this a step further and add a few items to the Site Setting page.  You can either add items to existing groups on that page, or create your own.  I created my own by specifying CustomActionGroup in my CustomActions.xml file, as well as a few CustomAction elements that will be a part of my custom group.  The XML is fairly straightforward:

<CustomActionGroup
  Id="LayoutsAppCustomActionGroup"
  Title="Widget Application Settings"
  Sequence="1"
  Location="Microsoft.SharePoint.SiteSettings">
</CustomActionGroup>

<CustomAction
  Id="UserGroupAdminLinkForSettings"
  GroupId="LayoutsAppCustomActionGroup"
  Location="Microsoft.SharePoint.SiteSettings"
  Rights="ManageWeb,ManageLists"
  Sequence="1"
  Title="Manage Widget Categories">
  <UrlAction Url="~site/_layouts/DevExpertise.LayoutsApp/Categories.aspx" />
</CustomAction>

<CustomAction
  Id="UserGroupAdminLinkForSettings"
  GroupId="LayoutsAppCustomActionGroup"
  Location="Microsoft.SharePoint.SiteSettings"
  RequireSiteAdministrator="TRUE"
  Sequence="2"
  Title="Modify Widget Permissions">
  <UrlAction Url="~site/_layouts/DevExpertise.LayoutsApp/Permissions.aspx" />
</CustomAction>

The only notable thing to point out here is for the CustomAction elements, the GroupId is that of the CustomActionGroup I specified first.  This tells SharePoint to put these actions in the custom group.  Redeploy and reactivate your feature, and you will now have this in your Site Settings page:

Hopefully you can see from this post that it’s pretty easy to build navigation for your custom application and have that created when your application is deployed via a custom feature.  In the next and final post in this series, I will show my approach to packaging everything up into features and solution packages, and how to deploy that to SharePoint in a simple and streamlined fashion.  Stay tuned!

I briefly went over my approach to creating a custom SharePoint theme in my previous post, and I even included a downloadable solution package that you can install on your farm (provided you have the .NET 3.5 Framework installed).  How did I accomplish this?  Pretty easily actually.  Unfortunately there isn’t much documentation or examples of this out there, so allow me to put an end to that!

SharePoint features and solutions are absolutely essential if you want to provide an easy and maintainable method of deploying custom artifacts to your SharePoint servers.  A theme is a perfect candidate for this, as everything is file-system based and located with the 12 directory.  The only odd thing that throws a monkey wrench in this seemingly simple process is the SPTHEMES.XML file, which must be updated to include an entry for your custom theme.  Here’s a portion of that file, with the custom theme I developed in my previous post highlighted:

Now, you could by all means include the SPTHEMES.XML file in your solution and have it overwrite the existing file, but what if you have other themes defined in your file?  That approach will overwrite it, and you’ll have to reenter everything.  The recommended approach to this is to create a feature receiver that fires when the feature is installed and modifies the SPTHEMES.XML.  When the feature is installed, a custom <Templates> section is added for the custom theme, and when it’s uninstalled it’s removed.

NOTE: A feature is “installed” when you run the STSADM –o installfeature command, or when a feature is contained in a solution package and that solution package is deployed.

One important thing to mention is that this feature is scoped for the farm, not an individual site-collection or site, as the files deployed to the file system are used by the entire farm.  Let’s first take a look at the feature.xml file:

<?xml version="1.0" encoding="utf-8" ?>
<Feature xmlns="http://schemas.microsoft.com/sharepoint/"
         Id="2D965A22-73A9-4e00-A530-06F2AF6EC89F"
         Title="DevExpertise Vista Theme"
         Description="Adds the DevExpertise Vista Theme"
         Scope="Farm"
         Version="1.0.0.0"
         ImageUrl="DevExpertise\devexpertiseLogo.png"
         ReceiverAssembly="DevExpertise.SharePoint.Themes, Version=1.0.0.0,
                           Culture=neutral, PublicKeyToken=d39eedb6cff9b1c8"
         ReceiverClass ="DevExpertise.SharePoint.Themes.FeatureReceiver">
</Feature>

As you can see, it is executing a custom FeatureReceiver class.  At a high-level, the receiver looks like this:

[UPDATED 5/27/2009]

I received a couple comments that let me know that if this feature is activated on a farm with multiple front-ends, then the FeatureActivated event only gets fired on a single web front-end.  This is absolutely TRUE, and an oversight on my part (thanks guys!).  The solution is extremely simple – put your code in the FeatureInstalled and FeatureUninstalling events instead, as these get fired on EVERY web front-end in your farm!!  I’ve modified the code to reflect this:

public class FeatureReceiver: SPFeatureReceiver {

    private enum ModificationType { Add, Remove }

    public override void FeatureInstalled(SPFeatureReceiverProperties properties) {
        ModifySPTheme(ModificationType.Add);

        // if necessary, loop through all sites and set theme
    }

    public override void FeatureUninstalling(SPFeatureReceiverProperties properties) {
        ModifySPTheme(ModificationType.Remove);

        // if necessary, loop through all sites and reset theme
    }

    public override void FeatureActivated(SPFeatureReceiverProperties properties) {
        // do nothing
    }

    public override void FeatureDeactivating(SPFeatureReceiverProperties properties) {
        // do nothing
    }
}

For the sake of simplicity, I’m not including code to set the theme on any sites.  Since this is a farm feature, it doesn’t make sense to set the theme for a particular site here, but by all means if you wanted to you could.  Basically this feature receiver is only for modifying the SPTHEMES.XML file.

Let’s take a look at the ModifySPTheme() method.  It uses LINQ to XML to open and parse the file, add the necessary elements when the feature is installed, and remove it when the feature is uninstalling:

private void ModifySPTheme(ModificationType type) {
    XDocument doc = null;
    XNamespace ns = "http://tempuri.org/SPThemes.xsd";

    // path to the SPTHEMES.XML file
    string spthemePath = Path.Combine(SPUtility.GetGenericSetupPath(@"TEMPLATE\LAYOUTS\1033"), "SPTHEMES.XML");
    string contents = string.Empty;

    // read the contents of the SPTHEMES.XML file
    using (StreamReader streamReader = new StreamReader(spthemePath)) {
        contents = streamReader.ReadToEnd();
        streamReader.Close();
    }

    using (StringReader stringReader = new StringReader(contents.Trim())) {
        // create a new XDocument from the contents of the file
        doc = XDocument.Load(stringReader);

        // retrieve all elements with a TemplateID of 'VISTA'.  At most, there should only be one
        var element = from b in doc.Element(ns + "SPThemes").Elements(ns + "Templates")
                      where b.Element(ns + "TemplateID").Value == "VISTA"
                      select b;

        // determine if the VISTA theme element already exists
        bool exists = (element != null && element.Count() > 0);

        if (type == ModificationType.Add) {
            if (!exists) {
                // create an XElement that defines our custom VISTA theme
                XElement xml =
                    new XElement(ns + "Templates",
                        new XElement(ns + "TemplateID", "VISTA"),
                        new XElement(ns + "DisplayName", "DevExpertise Vista Theme"),
                        new XElement(ns + "Description", "A Vista-like Theme"),
                        new XElement(ns + "Thumbnail", "images/DevExpertise.SharePoint.Themes/VISTA/thVISTA.gif"),
                        new XElement(ns + "Preview", "images/DevExpertise.SharePoint.Themes/VISTA/thVISTA.gif"));

                // add the element to the file and save
                doc.Element(ns + "SPThemes").Add(xml);
                doc.Save(spthemePath);
            }
        }
        else {
            if (exists) {
                // if the element exists, remove it and save
                element.Remove();
                doc.Save(spthemePath);
            }
        }

        stringReader.Close();
    }
}

Pretty slick, huh? Now, keep in mind that this only modifies the SPTHEMES.XML file – it does NOT set the theme for any site.  It will still be up to the user or site admins to set the theme for a given site.  Also, if this theme is already applied to a site and the feature is deactivated, it won’t reset the theme – it will only remove the entry from the theme settings page in Site Settings.  Finally, if a site has this theme installed and the solution package is uninstalled and/or removed, your site’s theme will be messed up because the source files are gone.  It is probably beneficial to at least loop through all the sites and reset the theme to something else if and when the feature is deactivated, but I’ll leave that to you. Enjoy!