Wednesday, May 14, 2008

Creating a site administration page that looks like a real SharePoint administration page

This page will have to run in the context of the site.

At the end of this article our administration page will look like this:

When a user submits the page, the page will also validate if the url that was entered is a valid SharePoint site.


Step 1 Add a link to the

Site Settings menu.

The first step is to create a link to the Site Settings menu. We will lock this down, so that it is only available for administrators. The easiest way to do this is by using a SharePoint Feature. How to install and activate can be found in the previous article. The feature xml for this feature looks like this




<Feature Id="06d77b33-76b2-4a14-bef4-3e4b4203d88e"
Title="Custom Navigation Site Menu items by Ton"
Description="My custom Site Menuitems for setting up navigation."
Version="1.0.0.0"
Scope="Site"
xmlns="http://schemas.microsoft.com/sharepoint/">
<ElementManifests>
<ElementManifest Location="tstsitemenus.xml"/>
</ElementManifests>
</Feature>






This is the XML for installing the feature. The file that is referenced in the ElementManifest node actually adds the menu item:





<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction
Id="TSTSiteMenus.SiteSettings"
Title="Setup Custom Navigation"> Location="Microsoft.SharePoint.SiteSettings" GroupId="Customization"
Sequence="106"
RequireSiteAdministrator="TRUE"
<UrlAction Url="~site/_layouts/CustomNavigation.aspx"/>
</CustomAction>
</Elements>



A number of attributes further explained:

· Title – the title of the link

· Location – The location of the new action. This can be the Site Actions menu, edit menus, toolbars etc. I have picked “Microsoft.SharePoint.SiteSettings” to make it appear in the site settings page.

· GroupId – The group in which the action will appear. I have picked “Customization”, because this makes our action appear in the “Look and Feel” section of the site settings. You can add these sections yourself using a “CustomActionGroup”. See the WSS SDK for more details.

· RequireSiteAdministrator – This makes the option only appear for Site Administrators.

· UrlAction – The url to navigate to when the user clicks the link. By using the “~site” in the url, we make our administration page run in the context of the site.

After installing and activating the feature, our site administration now has a new item:



Step 2 – Create the administration page

In the second step we will create the CustomNavigation.aspx page that is referenced from the menuoption in step 1. The first step in making your administration page look like real SharePoint administration pages, is inheriting it from “WebAdminPageBase”, which is available in the “Microsoft.SharePoint.ApplicationPages” namespace. I created a new class library project and added a new class called “CustomNavigation”.

Our aspx page should use this code behind, and also register the namespaces and controls that we will use to build the page. I will not copy all code, you can find that in the attached ZIP file.

<%@ Assembly Name="Microsoft.SharePoint.ApplicationPages, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c"%>

<%@ Page Language="C#" Inherits="Eog.OfficeServer.ApplicationPages.CustomNavigation, Eog.OfficeServer.ApplicationPages, Version=1.0.0.0, Culture=neutral, PublicKeyToken=4765c72bbf274873" MasterPageFile="~/_layouts/application.master" %>


Step 3 – Add controls to the placeholders

Because our page inherits from WebAdminPageBase, we now have several placeholders that we need to populate. We don’t need to build the whole page, the masterpage does that for us, we just populate a few placeholder. The first placeholders are the title placeholders:

<asp:Content

ContentPlaceHolderId="PlaceHolderPageTitle"

runat="server">

<SharePoint:EncodedLiteral

runat="server"

text="Custom Navigation"

EncodeMethod='HtmlEncode'/>

asp:Content>

<asp:Content

ContentPlaceHolderId="PlaceHolderPageTitleInTitleArea"

runat="server">

Setup Custom Navigation

asp:Content>

The main content are of the page (called PlaceHolderMain) will re-use some standard control templates that are available in the ControlTemplates folder.

These are registered at the top of the page as well:

<%@ Register TagPrefix="wssuc" TagName="InputFormSection" src="~/_controltemplates/InputFormSection.ascx" %>

We start off creating a new section on the page for our “Local Navigation” settings. This can be done by using the InputFormSection control. The InputFormSection can have one or multiple controls. These are added within a “<Template_InputFormControls>“.

This template can have multiple controls. These controls are InputFormControl controls, that are a combination of the label and the control. They look like this:

<wssuc:InputFormControl

LabelText="Navigation Expand Depth"

LabelAssociatedControlID="navigationExpandTextBox"

runat="server">

<Template_Control>

<wssawc:InputFormTextBox

Title="Navigation Expand Depth"

class="ms-input"

ID="navigationExpandTextBox"

Runat="server"

MaxLength="255" />

Template_Control>

wssuc:InputFormControl>



Step 4 – Add OK and Cancel button

After adding the control to edit the values, we add the OK and Cancel button to the page. These are added in a special ButtonSection, that will be added just below the InputFormSection. The code for the OK button (see the zip for the rest):

<Template_Buttons>

<asp:Button

UseSubmitBehavior="false"

runat="server"

class="ms-ButtonHeightWidth"

OnClick="HandleOKButtonClick"

Text="<%$Resources:wss,multipages_okbutton_text%>"

id="buttonOK"

accesskey="<%$Resources:wss,okbutton_accesskey%>"/>

Template_Buttons>


Step 5 – Add validation

The last part of the aspx page at this stage is the validation of the page. Most out of the box administration pages add a FormDigest control to the page. This is a SharePoint control that adds security validation to the page. This is specific for the user requesting the page and the time it is requested. After some time it expires, making it impossible to post the page. I have not added this yet to my page, will write a post on it after I sorted this out.

The validation that we will add is a validator for checking if the url entered in the Navigation Parent field is a valid SharePoint site. Just after the InputFormTextbox, we add a CustomValidator:

<asp:CustomValidator

ID="validateParent"

ControlToValidate="navigationParentTextBox"

Display = "Dynamic"

ErrorMessage = "Please enter a url for a SharePoint site."

OnServerValidate="ValidateNavigationParent"

runat="server"/>



Step 6 – Implement code-behind

The code to actually make the page work is implemented in the CustomNavigation.cs. First we need to ensure that users who are not administrator cannot access the page by using the url directly. That is easy J; just add these lines :

protected override bool RequireSiteAdministrator

{

get

{

return true;

}

}

You can find all code to load and save the siteproperties in the attached zip file. Saving a property to the property bag can be done like this:

// Store NavigationExpand in the property bag.

if (web.Properties.ContainsKey("navigationexpand"))

{

if (web.Properties["navigationexpand"].ToLower() != navigationExpandTextBox.Text.ToLower())

{

web.Properties["navigationexpand"] = navigationExpandTextBox.Text;

modified = true;

}

}

else

{

web.Properties.Add("navigationexpand", navigationExpandTextBox.Text);

modified = true;

}

And don’t forget to call Update:

web.Properties.Update();

After saving the properties to the property bag, we will redirect the user back to the site settings page. The code to do that:

SPUtility.Redirect(

"settings.aspx",

SPRedirectFlags.UseSource

SPRedirectFlags.RelativeToLayoutsPage,

this.Context);

}

}


Step 7 – Deploy the administration page

The proper way to deploy our administration page in SharePoint 2007 is through a Solution Deployment package. I haven’t had the time to sort that out, but is a very nice way of deploying packages like this.






1 comment:

SharePoint Adam said...

CustomAction is the perfect solution for such requirements.

Here is the step by step instructions to add new custom link in site settings page: Add a Link to Site Settings Page in SharePoint.