SharePoint Magazine » Customization

Everything You Need to Know about BDC: Part 8 of 8

Wen He — Mon, 08 Feb 2010 10:53:04 +0000

Welcome back to Part 8 of our 8-part series on the Business Data Catalog (BDC). From the previous 7 installments, we have covered everything about BDC, from BDC architecture, ADF, BDC Web parts, BDC search and profile, to the BDC object model in details. We also touched the surface of BDC actions in Part 4 and Part 5. As promised, we’ll dedicate this final article to actions. We’ll explain what the BDC actions are and what they can do for you. We’ll then walk you through how to create custom actions and how to perform these actions by using custom Web parts and InfoPath forms. As you will soon learn, this is another power capability of BDC because it extends the ability to link content to Web sites. This allows you to quickly create mashups that are item-specific so that you can take actions in context, such as write back to your LOB systems.

For your reference, these are our previous seven articles:

Part 1, BDC Purpose and technical architecture
Part 2, Application Definition File (ADF) and its Development
Part 3, Developing an ADF to Connect to Web Services
Part 4, Consuming Business Data through Web Parts and SharePoint Lists
Part 5, Implementing Enterprise Search with Business Data
Part 6, Integrating User Profiles with Business Data
Part 7, Working with the BDC Object Model

With that, let’s dive into BDC actions and start by asking what is an action.

What is an action?

An action is simply an operation upon a selected item. The operation can retrieve information about the selected item, or it can launch a program or Web page with the selected item as a parameter. The operation is a predefined URL link in each BDC item that enables you to act on the item, such as editing, or mapping it using Live Search as we demonstrated in Part 4.
An action is composed of a URL target where the action is to occur, and the matching parameters in the URL QueryString format. When we associate an action with an entity, we can pass parameters to that action based on the contents of one or more fields. For example, in the Live Search example in Part 4, we associate the Live Search page’s URL with a customer and provide the customer’s address to parameterize the search.

From the above, major characteristics of actions are as follows:

URL-based, parameter-driven
Actions on any entity and appear everywhere an entity goes
User can take action in ECB menu
Custom actions means custom code

A perfect example of action is the default View Profile action, as shown in Figure 1.

Figure 1 View Profile action in a Business Data Actions Web Part

Through a View Profile action we can navigate to the profile page of an entity. Clicking the View Profile action in a Business Data Actions Web Part as shown in Figure 1 above, as well as in a Business Data column, or in a Business Data List Web Part, lets us view the details of an item on that item’s profile page. Figure 2 shows that a Profile page that displays employee details.

Figure 2 A Profile page that displays employee details

What is a Profile page?

A profile page is automatically generated for each entity that has a SpecificFinder method after BDC imports an ADF file, a profile page can display all the information from a record in the BDC. As we’ve seen in Figure 2, a profile page can display all the fields in a record for a specific employee. The default profile page contains a BDC Item Web Part for that entity.
If we put the profile page in Edit mode, there are actually two Web parts: a Business Data Item Builder and a Business Data Item that connect together. The Item Builder parses the querystring (http://win7:10001/ssp/admin/Content/Employee.aspx?EmployeeID=1) and passes the EmployeeID value to the Business Data Item, which then executes the SpecificFinder method and returns a record of Employee data.

Figure 3 Profile page components

Default Profile Page and default action

As we have seen from above section, the default action (View Profile) along with the default Profile page is automatically created when the entity has a SpecificFinder method. To provide an ECB menu user experience, we can also add actions in a Business Data List Web part without using the Business Data Actions Web Part.

Defining an Action

There are three ways to add an action: 1) defining it in the ADF, 2) adding it in the BDC admin page after the ADF has been imported into BDC, and 3) through the BDC Object Model. Here we’re focus the first two.

Defining it in the ADF

To define an Action for the specified BDC entity, we’ll first locate the section within the and hierarchy.

Figure 4 Actions is nested within the Entities/Entity in ADF

And insert the portion like this one:

Adding an action in the BDC admin page

In the SSP administration page (View Application –> View Entity), the action is defined below and the URL that takes EmployeeID as a parameter: http://dpm:10001/ssp/admin/Content/Employee.aspx?EmployeeID={0}

Figure 5 Add an action the SSP Admin page

Custom Actions

We also can create custom actions for entities in BDC. Among other things, custom actions allow users to navigate to any custom page to manipulate business data.
Here are some scenarios that custom actions can do:

Parameterize custom search
Update employee in HR system
Customize profile page for an entity
Integrate BDC search into enterprise report center

We’ll be creating custom actions in the last part the article.

Figure 6 Enable View Profile action in a Business Data List Web part

This enables the ECB-style action, we will specify a Title property and add the following in the ADF:

LastName

It specifies which column in the Business Data List/Related List Web part displays the Actions menu. It also specifies the name of the TypeDescriptor that corresponds to the column you want to display as the default column in Business Data lists.

In the Business Data Column scenario, we can also display the action menu and link the column to the business data profile in a Business Data list.

Figure 7 View Profile action in Business Data Column

This is default behavior OOB for a Business Data column. When adding the column, just make sure the following two are checked:

Display the actions menu
Link this column to the profile page to

Figure 7 Enable the actions menu and profile page in Business Data list

These profile pages are used and being indexed by BDC Search. The following search results display the profile pages that contain the search keyword (s). Notice in Figure 8 how a search for Great Lakes will display the profile pages for both this customer and their orders.

Figure 8 BDC Search Results in Profile Pages

Enhancing the Profile Page

By default, the profile page is hosted on the Shared Services Provider site collection where the BDC administration site is located. The search result (that is, the URL) links back to the Shared Services Administration site collection address that is not scalable when you extend the Web application. In real world, we may not want to give end users access to the SSP Admin site for security reason. A better practice is to create our own profile pages and host them in any site that is not part of the SSP site collection.
In this example, we’ve created a dashboard page in Report Center to replace the default Profile Page. The Report Center provides enterprise reporting capabilities that are scalable and centralized. We can direct users to custom profile pages by updating the View Profile action.

Figure 9 Replace the default Profile Page with Custom Report Center

As an alternative, we can also replace the default the URL in Action element in ADF with the path to the Profile.aspx page:

http://reportcenter/Pages/Profile.aspx?EmployeeID={0}” ImageUrl=”/_layouts/1033/images/viewprof.gif” Name=”View Profile”>

An action to call the Profile.aspx page for each Employee ID has been defined. This action will be the default action provides in the search result.

Now let’s create Profile page to display information about the Employee entity in Report Center. (The Report Center is a site that provides a central location for business-intelligence-related information.)

In the http://reportcenter site, create a new Blank Web Part Page called “Profile.aspx”.
Add the following two web parts: Query String (URL) Filter Web Part and Report Viewer Web Part.
Configure the Query String (URL) Filter Web Part to pickup parameter “EmployeeID” from the URL query string.
Configure the Report Viewer Web Part to display the employee profile report called “Employee Profile”.
Connect the Query String (URL) Filter Web Part parameter to the SQL Server Reporting Services Report Viewer Web Part parameter “EmployeeID”.

Figure 10 SQL Server Reporting Services Report Viewer

Note: Please make sure you use this Web Part and not the OOB Report Viewer Web Part.

Test that the page is picking up the URL string parameter “EmployeeID” correctly by typing the following URL: http://reportcenter/Pages/Profile.aspx?EmployeeID=108

Figure 11 Custom Profile Page in Report Center

Creating Custom Actions

Creating custom actions requires custom code. The approach we take is to treat the BDC source simply as a data reader, and to build our CRUD (create/read/update/delete) logic in custom code. The BDC object model provides the means to retrieve collections, list items and enumerators, and we can use GenericInvoker to perform CRUD, which has been extensively covered in Part 7. We get the Web Parts to display data, and then we can use custom actions to create and update records by using Web parts and InfoPath Forms.

Creating Web Parts

We have created and deployed two Web Parts using the Object Model as shown below, with one inserting a record and one updating an existing record. (Special thanks to Lightning Tools! I’ve used BDC Meta Man to help with creating the Web parts.)

Figure 12 The two Custom Web Parts can be used to add and update employee records

Add these two actions in the SSP Admin page:

Figure 13 Adding actions in the SSP Admin page

Now you can access the two actions from the content menu in the Employee List:

Figure 14 Custom Actions Add Employee and Update Employee in the context menu

Figure 15 Add Employee Web Part

Figure 16 Update Employee Web Part

Creating InfoPath Form

MSDN has a great article titled Using Business Data Catalog Actions to Pass Parameters to InfoPath 2007 Browser Forms that walks you through this in detail. So I’ve created our InfoPath Form and added the action using the Form Template path:
http://dpm/_layouts/FormServer.aspx?XsnLocation=http://dpm/FormServerTemplates/EmployeeUpdate.xsn&DefaultItemOpen=1&EmployeeID={0}&FirstName={1}&LastName={2}

Figure 17 Adding Custom Action that uses InfoPath Form

Figure 18 Update Employee in InfoPath Form

Conclusion

In this final article, we have focused on actions that users can take on the business entities. We can define actions in ADF or add it “after the fact”. We have also created custom actions using the BDC object model by using custom Web parts and InfoPath forms to enable CRUD (create/read/update/delete) operation support. Once added, actions can be performed from within the list, which becomes relatively transparent to the user where the data comes from. [The statement that the BDC data is read-only is not true anymore as we have just demonstrated.] As you have learned from our 8-part series, BDC enables user interaction in business intelligence, enterprise content management, collaboration and social features, and enterprise search.

Looking Forward to SharePoint Server 2010

BDC has evolved to what is now called BCS (business connectivity services) in SharePoint 2010. Even though we can use BDC to enable connectivity to external systems, it was difficult to create solutions because of the lack of a designer and it was not so simple to create a solution that enabled users to make changes and write that data back to the external store. BCS now enables you to integrate LOB data into SharePoint and Office with full CRUD support, tighter integration with Office client applications, and better tools for modeling business entities. BCS is all about connecting to external data. We look forward to sharing with you the exciting new features in BCS and what they can do for you in the near future. Until then, aloha!

SharePoint’s Branding Limitations, Part 4

Diantha van Marion — Fri, 24 Jul 2009 07:51:47 +0000

Introduction

As a Front-end Developer with a background in designing I’ll show you how to make a graphical design that works for a default SharePoint-environment. If you want to take control over the front-end, don’t use any themes. Create your art by using style sheets!

Not all graphical designs for a portal will work in a SharePoint environment. There are a couple of limitations the Graphical Designer must know. A Graphical designer needs to know the scope of the graphical design. For example, if a Graphical Designer puts a border on an element like a table, that will take him about 3 minutes to design, but this simple border could take the Front-end Developer a few hours to implement.

It’s really important that the Graphical Designer and the Front-end Developer work together and have a clear communication about the graphical design. Making a graphical design specifically for a MOSS environment could save you days on the implementation! This article will give the Graphical Designers more insight into the effect of these design decisions.

This article assumes that the reader has SharePoint and basic HTML knowledge.

Search

There are multiple search interface within a SharePoint portal. One of them is the search interface in the header. Part 1 of “The art of SharePoint, how to make a graphical design work for SharePoint” discusses that one.

The search result page has it’s own page layout. If you take a look at the search results page you will see that the search interface is no longer in the header but is now onto the content area. It is not another web part, because it has kept it’s ID #1, that is reserved for the search interface.

Page layout

There is a specific page layout for the search results. If you take a closer look at the Black Search Page (Welcome page) you can identify the following page elements:

• Tabs

• Input fields

• Results bar

• Search results

• Paging (only visible when there are more then 10 item found)

The next section discusses all page elements in detail.

Tabs

The code in the following image shows that the tabs are rendered inside a table, the .ms-ptabarea, which is rendered inside the .ms-pagetitleareaframe of the web part

This table has one more cell as there are tabs. In this case there are two tabs, so there are three cells. The last cell of the table has only one function; it makes sure that the whole table has a bottom border all the way to the right.

The ’s with a tab all contain the class name .ms-sctabcf, or if the tab is selected, the class name is .ms-sctabcn. This makes it possible to style the selected tab different from the others. The last, the one for the border, has the class name .ms-sctabrx.

You can make the tabs look like textual links by removing the background color and the borders of the ’s. Make sure that the selected item will be styled a bit different so that it is still visible that it’s the one selected. Also make sure you style the rollover state of them. Every class name will get “hover” behind the usual class name (except for the .ms-sctabrx). For example .ms-sctabcfhover and .ms-sctabcnhover.

Input fields

Another web part on the search result page is where the input fields are. The table the input fields are in, has a cell for every element, plus one.

All the ’s have the class name .ms-sbcell, except for the last cell, that is empty. This one is called .ms-slLastcell. The cell that has the search button in it, has two class names, the .ms-sbcell and the .ms-sbgo. You can style this area by using these class names.

Results bar

The results bar is located just above the search results. It has it’s own web part zone called #MidUpperLeftCell. This web part has a table with three <tr>’s. The first ans the second <tr>’s are empty. The third one has a with a web part that is responcible for showing the result text. The text and the sort-links have a classname, you can use to style it.

The second results-row, is an other web part, in the web part zone #MidLowerLeftCell. Inside the .ms-WPBody is a div.srch-WPBody. In there is the div .srch-stats in where the text is located.

Inside the #MidLowerRightCell is the upper paging positioned.

Search results

The search results are positioned in the web part zone #BottomCell. The div inside this web part does have class name: .srch-results. All the search results are positioned inside that div. For every search result there is a .srch-Icon, .srch-Title, .srch-Description and a .srch-Metadata, so every element can get its own styling.

All the elements inside a search result have a class name. It is, for example, possible to hide the icon of the document, or give the search title, description or url another color. I advise you to only style the colors and fonts and leave the position of the element as they are, which leaves as much space as possible for the search results.

Paging

Inside the #MidLowerRightCell is the upper paging positioned. The paging at the bottom of the screen is also positioned in the #BottomCell. Inside the paging div, the .srch-Page there is an -tag for every link. The page that is being visited at the moment does not have a link, nor a classname. So when styling the numbers, first style every element inside the .srch-Page, then restyle every -tag inside the .srch-Page.

My Site

The My Site is a bit different then the other sites of SharePoint. First of all it uses another master page, which is composed out of different files. If you want to make changes in the master page or page layout of the My Site, there’s no easy way to do it. How you can edit the master page will not be discussed in this article. Just stick to the existing layout and only change the style sheet. It is possible to make a beautiful my site.

Because the master page of the My Site is a bit different, it does not contain a reference to your style sheet you created. Ask a developer or architect to add the reference for you, or if that is not possible paste the css code underneath the rest of the styiling in the portal.css. This is not the best way to go, because you really want to separate the default styles from the new one’s. And you do not want to make changes in the style sheet twice (once in your custom stylesheet and once in the portal.css). So, it is better to make the master page of the My Site work with your style sheet by adding the reference to it.

If you apply the layout style sheet for the portal onto the My Site, you will see that your graphical design is implemented for about 90%. I advise to double check all the items and make sure every element is styled correctly. Pay special attention to the blog and wiki, the calendar and the colleague tracker.

SIFR

Scalable Inman Flash Replacement (SIFR) is ment to replace short pieces of text (for example a title or header) by any particular font. Users of the portal do not need to have the font installed on their machine. SIFR works with javascript, flash and css and replaces the particular piece of text in a split second.

In the configuration file of SIFR you can refer to a class name or ID, so that the text inside that element will be replaced by a SIFR object. It is very easy to use. There is one thing you need to consider before using SIFR on a portal.

SIFR replaces the text with a flash object, a swf. This object is placed on top of the text, while the text that is being replaced is made invisible. It is possible to edit some of the object styles, for example the color and the padding.

What if the text you are replacing with SIFR is a link? Like for example a news header? In the news overview page the header is a link. SIFR replaces the text by a swf-object, but the object does not copy the reference the link had. So be careful where to use SIFR on a SharePoint Portal, because, if what you are replacing a link with SIFR, which has the same class name/ID as referred to in the configuration file, you cannot use SIFR. Make sure your Graphical Designer knows this, and prevent him from designing a fancy menu with spiffy fonts.

Calendar and date picker

The calendar has its own style sheet. Just like the date picker. When you style the calendar, you should also style the date picker, because those two have the same table-like structure and use the same colors. I advise you to only style the colors and fonts of the calendar and use the layout default.

Because there already is a special calendar style sheet, the calendar.css, it is very easy to style the calendar.

1 First of all, find an element you would like to style.

2 Search in the style sheet for its color and/or background image or -color.

3 Copy all the class names and ID’s that have that particular color or background image.

4 Make a separate calendar section in the exsisting style sheet, for example after the last line, at the end of the other styling in the calendar.css.

5 Paste the class names and ID’s in there and give them the color and background images you would like to give them.

This way, you can end up by changing a handfull color codes, and it can be done pretty easy. You can work the same way for the date picker, and you can use the same colors as you did for the calendar.

Here are some examples:

Make sure you have checked the day, week and month view. Also check a short appointment, an appointment over a few days and an all day appoint.

Summary

Here’s a small overview with highlights of all four parts of the article “The art of SharePoint, how to make a graphical design work for SharePoint”.

Styling elements will work best on elements that have a class name, ID or a combination of both.
Always double check if you haven’t forgotten to style any elements.
The calendar and the date picker have their own style sheet.
The look and feel is well manageable when making custom master pages and page layouts. This gives you the opportunity to find the boundaries and give it all a bit more exciting looking.
Most of the time, adjusting the height, width or colors of an element, text or image is not that hard. It is more difficult to style the position, the location of the page elements. Because you cannot change the order in which elements are rendered, you will need style sheets to edit the location on the page where the elements are shown.
Changing an elements position can cause some trouble on other pages on the portal, because class names and ID’s are used through the whole portal. Changing one of them will cause another element on another page to change also.

Resources

CSS Reference Chart for SharePoint 2007

By Heather Solomon

SIFR

By Mike Davidson

Tamtam blog Diantha van Marion

By Diantha van Marion

Thank You Tam Tam !

A big thank you to Diantha and Tam Tam from Arno at SharePoint Magazine. This post is from the SharePoint Magazine Partner Spotlight Week, where our featued partner was Tam Tam.

If you would like to be featured on the SharePoint Magazine Partner Spotlight, please contact us

SharePoint’s Branding Limitations, Part 3

Diantha van Marion — Thu, 23 Jul 2009 08:04:48 +0000

Introduction

This article assumes that the reader has SharePoint and basic HTML knowledge.

Web parts

This section is all about SharePoint’s web parts. First the display mode of the web parts will be the point of interest, then the Edit mode, and after that the Article page layouts will be discussed.

The with class name .ms-bodyareacell is the overall container for the content. Inside this is a table with class .ms-propertysheet, and a td.ms-bodyareaframe inside that there is another table. These are the containers for the content on a page and are being defined in the page layout. Inside the .ms-bodyareaframe are a few nested tables and one of these tables is the table of a web part.

Web part ID’s

If a web part is placed inside a web part zone, it will get an ID. Depending on the amount of already placed web parts on that page, and the order in which they are placed, the ID will get its tracking number. It does not change when you change the order of the web part zones. So therefore, the ID of the web part actually isn’t unique, it is just unique for that page.

The web part in this example is the third web part of the page and as you can see, it carries number 3 in the ID. The search interface in the header is always the first web part of the page. In this case there were two web parts placed on the page, which together with the search makes three: the ID number of the last placed web part. If you want to style the web part in its entirety, you can only list all the web part ID’s and add styling to them. This nasty solution is the only solution to styling every web part on itself. A better solution would be for example to style the elements inside the web parts, such as the .ms-WPBody.

..
#MSOZoneCell_WebPartWPQ27,
#MSOZoneCell_WebPartWPQ28,
#MSOZoneCell_WebPartWPQ29,
#MSOZoneCell_WebPartWPQ30{
     Border:1px #f2f2f2 solid;
}

Because every web part has a and inside that a table as a container, it is possible to style the background of the web part with two background images, but it is very tricky an I advice you not to do so. Make sure every with ID #MSOZoneCell_WebPartWPQ2 (a web part ID of your choice) has a background image. Then style every table inside the with those ID’s with another background image. Secondly, hide every background image on every second or more nested table inside the with the web part ID.

Here’s an example of how, just for web part ID 3:

#MSOZoneCell_WebPartWPQ3{
     Background:transparent url(images/webparttop.jpg) repeat-x left top;
}
#MSOZoneCell_WebPartWPQ3 table{
     Background:transparent url(images/webpartbottom.jpg) repeat-x left top;
}
#MSOZoneCell_WebPartWPQ3 table table{
     Background:transparent none;
}

Which means “only apply if table is the first element inside #MSOZoneCell_WebPartWPQ3“, because it is not supported in Internet Explorer 6 and older versions.

Unfortunately you cannot use

#MSOZoneCell_WebPartWPQ3 > table {
     ..
}

Make sure the images you use are repeatable on the x-axis. If they are not, you will need to make a new page layout where the web part zones have a static width (set in the style sheet of course). This way you can control the width of the web parts in a particular web part zone, and make your background images as wide as the web parts.

Web part headers

Inside the with the web part ID is always a table with two ’s. The first one is for the header of the web part, the second one is for the content of the web part.

The first class you can use to style the header is the tr.ms-WPHeader. This has two ’s, one for the title of the header, and another one for the little arrow on the right pointing down. Only the first has an ID, which has the same ID-number as the web part-ID. To style the background and the borders of the header, you can style every inside the .ms-WPHeader.

.ms-WPHeader td {
     border-bottom:1px solid #4E7CB7;
}

To style the text of the header, style the .ms-WPTitle. Be aware that some web part titles contain a hyperlink. The little arrow is also a link, and to style that you can style the -tag inside the , and then overrule the styling for the header text. Like this:

/*This styles every link in the header*/
.ms-WPHeader td a{
	background-color:#000000;
}

/*This styles every textual link in the header*/
.ms-WPHeader .ms-WPTitle,
.ms-WPHeader .ms-WPTitle a:link,
.ms-WPHeader .ms-WPTitle a:visited{
	color:#4F3B2F;
}

It is possible to hide the header by changing the settings of the web part. Choose “appearance” and in the “chrome type” drop down and choose “none”. The with the header will not be rendered then.

Content Editor Web parts

The of the second of the #MSOZoneCell_WebPartWPQ contains a

with a web part ID that has the ID number related to the amount of web parts on the page, like #WebPartWPQ3. It also has a class called .ms-WPBody. The core.css uses this class to set the font family and size.

When using a Content Editor Web part, text is placed directly in the .ms-WPBody. The color of the text is set by the styling in the core.css, on the .ms-propertysheet and the body tag. The same goes for the hyper links in the text.

Lists

In a list web part, there is a table.ms-summarycustombody class, in where all the links are positioned. Every has a class.

Depending on what list with hyper links you use, the ’s will have one of the following class:

.ms-vh,
.ms-vh2,
.ms-vh-icon,
.ms-vh-icon-empty,
.ms-vhImage,
.ms-gb,
.ms-gb2,
.ms-gbload,
.ms-vb,
.ms-vb2,
.ms-vb-tall,
.ms-GRFont,
.ms-vb-user,
table.ms-disc td,
.ms-vh2-nofilter,
.ms-vh2-nograd,
.ms-vh3-nograd,
.ms-vh2-nograd-icon,
.ms-vh2-nofilter-icon,
.ms-pb,
.ms-pb-selected,
.ms-ph {
     font-family:tahoma,sans-serif;
     font-size:8pt;
}

The first two of this list are for example also used for list headers. Most graphical designs will have the same styling for all hyper links on the portal, so you can add your styling to the above classes and their -tags. The “add new” (add new announcement, add new event, add new link, etc. ) hyper links can be styled with their own class, for example: a.ms-addnew. Here’s an example of how you could style the lists.

Data table

SharePoint uses tables and lists to display its data. The Document Center is one of those ‘data tables’. The Document Center uses another page layout, because the purpose of the page is to show a big list with data and no text like articles. Therefore the Document Center has one web part zone that uses the whole width of the page. When styling the web parts, make sure the lists of the Document Center (Documents, Announcements, Tasks) are styled correctly. Pay special attention to the list headers here and make sure the fly outs of the top navigation are positioned above the list headers. If they are, make sure you position the .ms-vh div and .ms-vh2 div statically.

Width

Sharepoint comes with a set of page layouts. These page layouts have middle and right zones, but they do not always have an ID or class name for those zones. If you want to control the width of the web parts in either the middle or the right column, you need to create new ones, based on the existing page layouts. Make sure every web part zone has an ID or class, so you can set the width of those in the style sheet.

Edit mode

In edit mode the styling is usually kept default. Most of the classes and ID’s of the content are different when in edit mode, so the styling of elements inside web parts is rather easy to separate, but the web parts themselves aren’t. When editing a page, some web part zones and web parts will get other class.

System pages like the “site settings”-page and the “all site content”-page only contain the same header elements. The rest of the page has classes that are not used on the front-end. Therefore you can style those pages differently. I advise to only change the colors and fonts and leave the layout and the positioning the way it is by default. This way you won’t corrupt the usability of the system pages.

News articles

When creating a news article, it is possible to choose between several news article layouts; the page layouts. The first page layout for an article page is the “article page with body only”. Other page layouts are the “article page with image on left”, “article page with image on right” and the “article page with summary links”.

Article page with body only

This page contains a page content zone and a roll up image. When publishing the page, all the content will be inside the #MSO_ContentTable. Inside that is the div.pageContent.

Since the div.pageContent is an element of every news article page layout, you cannot set the width of the element. Styling this element will cause other page layouts also to be adjusted.

Article page with image on left

The second page layout is the “Article page with image on left”.

This page layout has the following elements:

Page image
Article date
Byline
Page content
Image caption
Roll up image

Page image

The .bodyareaframe contains two tables and some

’s. The first table has the property float:left. This makes the image positioned to the left of the text.

Article line and byline

The second table of the .bodyareaframe is the header. It contains two cells, one for the article date (.dateLine) and one for the “byline”.

Page content

The div.pageContent contains a div#ctl00_PlaceHolderMain_Content__ControlWrapper_RichHtmlField, which contains the text. The ID is not unique for this piece of page content, it is only unique on this page.

Other page layouts use the same ID, so by styling this element, the text looks the same, no matter what article page layout is chosen.

Article page with image on right

The “article page with image on right” has got the same fields and controls as the “Article page with image on left”. The only difference is the floating. Where in the “Article page with image on left” the table was floating left, here the table has no floating, but a

around it has a right floating. There’s an extra container div, the .articleLayout that was not in the “Article page with image on left”.

Article page with summary links

The “Article page with summary links” has, instead of the page image and image caption, a Summary Links control. These links are positioned inside a table that is floated to the right.

Next time in “SharePoint’s Branding Limitations”

Next time in part four of “the Art of SharePoint, how to make a graphical design work for SharePoint”, I will discuss some design decisions for search pages and the My Site. Other points of interest are the styling of the calendar and date picker and the use of SIFR.

SharePoint’s Branding Limitations, Part 2

Diantha van Marion — Wed, 22 Jul 2009 07:27:58 +0000

Introduction

This article assumes that the reader has SharePoint and basic HTML knowledge.

Navigation

This section is all about SharePoint’s navigation elements. First the meta navigation is discussed, secondly the top navigation with a focus on it’s fly outs. Thirdly, the quick launch navigation is discussed and last but not least the site actions menu.

Meta navigation

The meta navigation contains a set of links: Sign In/Welcome, My Links, etc. The meta navigation is positioned at the upper right top of the page. It has three textual links and a help icon as you can see in the image below.

The meta navigation begins with the table.ms-globalright. The table is floated to the right which causes the menu to be positioned at the right of the page. This table has five ’s and they all contain the class name .ms-globallinks.

The first is empty.
The second contains the welcome text and a fly out.
The third contains the vertical line.
The fourth contains a new table.This table contains the “My Site” link, separator, “My Links” link and separator.
The last contains the help icon.

Every of the meta navigation has the class name .ms-globallinks. Unfortunately you cannot give this class and every inside a color to change the color of all the links in the meta navigation. The Welcome link doesn’t change after applying a color to the .ms-globallinks and it’s -tags. Because this contains a

.ms-SPLink. Every link inside that

has a different color specified in the core.css style sheet. An other link that won’t change color is the My Links link.

When coloring all the links of the meta navigation add the declaration to the -tags in the class name .ms-SPLink, like this:

.ms-SPLink a:link,
.ms-SPLink a:visited,
.ms-globallinks,
.ms-globallinks a{
    color:green;
}

This will overrule the styles for the links in the .ms-SPLink, as defined in the core.css, the master style sheet which takes care of the default styling on a SharePoint portal.

Welcome ‘Your Name’ and ‘My Links’

The of these links contains two spans. The first one, which is hidden, contains the fly out. The second span contains a

which contains the -tag. Within the -tag the little arrow pointing down is positioned as well, as seen in the next picture.

The graphical behavior of the Welcome and “My Links” link is the same. When hovering the link, there’s a background-color and a border, suggesting it is a button. For consistent use of the graphical design you probably want to style the “My site” link the same as the other buttons.

Here’s the code to remove the background-color and border. Add the underline on hovering, to make it look like a textual link instead of a button:

.ms-HoverCellActive,
.ms-SpLinkButtonActive,
.ms-HoverCellActiveDark{
    background-image:none;
    border:0px none;
    background-color:transparent;
}
.ms-HoverCellActive a:hover,
.ms-SpLinkButtonActive a:hover,
.ms-HoverCellActiveDark a:hover{
    text-decoration:underline;
}

My site

The My Site link is the only link (in the meta navigation) that does not contain a fly out. Therefore, this link will respond to any styling assigned to .ms-globallinks a. The hover state of the .ms-globallinks a is not defined in the core.css style sheet, and therefore overridden by .ms-globalbreadcrumb a:hover. Style the .ms-globallinks a:hover to change the hover state.

Help icon

The help icon is an image inside an -tag. Because the image itself does not have a class name or ID, it is not specific enough to hide all the images inside the .ms-globallinks. That is because then the separators would also be effected. Therefor, you can use the -tag (with an ID) in where the image is, to hide the help icon (by hiding the -tag, the image will also be hidden). It is not recommended to hide the help icon because it’s function is to help the user. It is possible to show another image here. To do this you need to hide the image inside the -tag and make the -tag behave like a block. Then give it dimensions and place the new image of the icon as a background image.

An example:

.ms-globallinks a#ctl00_PlaceHolderGlobalNavigation_TopHelpLink img{
    display:none;
}
.ms-globallinks a#ctl00_PlaceHolderGlobalNavigation_TopHelpLink{
    display:block;
    background:transparent url(/_layouts/images/new_help_icon.gif) no-repeat left center;
    width:10px;
    height:10px;
}

Separators

It is possible to make the separators of the meta navigation hidden, because these are the only non-hyper links in the .ms-globallinks. Because they don’t have any class names or ID’s that are unique within the meta navigation, you need to style it all. Afterwards you can style the links differently. Giving all the items in the .ms-globallinks a visibility:invisible or a display:none, and the links a visibility:visible or a display:block, will cause your links to disappear, but only in Internet Explorer. The only way to hide them for all browsers is by giving them the same color as the background color of the meta menu, which off course should have a solid background color.

The steps are as follows: give the .ms-globallinks the same color as the background color (or any other color you wish), and give the links in the .ms-globallinks a of your choice. Like this:

.ms-globallinks{
    color:#FFFFFF !important;
}
.ms-SPLink a:link,
.ms-SPLink a:visited,
.ms-globallinks,
.ms-globallinks a{
    color:green;
}

You can remove some padding of the .ms-globallinks to make the spaces between the hyper links less wide.

It is not possible to style the links on multiple lines, because the ‘welcome’-link and the ‘my site’-link have the same class names, and will react the same.

Top navigation with fly outs

The top navigation is the horizontal navigation bar at the top of every page (inside the bannercontainer). The top navigation shows the sites or pages from the first level. This first level contains every page or site made from the homepage. The homepage is always level 0. SharePoint enables users to rename, remove or add a link.

The top navigation has a lot of nested tables. The table of the banner frame contains four ’s.

The first is empty.
The second contains the top navigation menu.
The third is empty.
The fourth contains the site actions menu.

The site actions will be discussed later. First I want to focus on the top navigation menu. In the ideal world and maybe in the future it will by default, the menu would look like this:


	
	
		
			 .. 
			 .. 
			 .. 
		
	
	
	siteactions menu goes here

The second contains a table, the .ms-topNavContainer, which contains multiple ’s. The first is the home menu item, the menu item of level 0. The rest of the ’s are empty or contain other items of the top navigation.

Home, the first menu item

The home menu item is placed into another table, the .ms-topnav. Every menu item of the top navigation is placed inside a table with the same class name. When the menu item is active, it gets another class name added, the .ms-topnavselected. By using this class name in your style sheet, it is possible to style the active menu items different. Another element contains the class name .ms-topnav as well: the -tagtable.ms-topnav or a.ms-topnav, or use just .ms-topnav for giving them both the sames styling. The same goes for the .ms-topnavselected. of the menu item. Be sure to style the right item by styling the

It is not possible to style the home menu-item differently then the other menu items, because they all have the same class names. If you want to do it anyway, you need to edit the HTML that is rendered for this menu.

Other first level menu items

The with the other menu items, contains a table with two cells. The first cell is empty, the next cell contains a table, the .ms-topnav. If the menu item does not contain any pages or sites at second level, the only contains the -tag, just like the home button.

Background images

To style the menu items, you can use the class table.ms-topnav. You can give it a background color or background image. Be aware that the image must be repeatable on the x-axis unless the menu items have a fixed width. You cannot use an image that is different on the left and right side when the images have variable widths. This is because items with no second level have only one . So you cannot use an image for the left side and another image for the right side.

If the table.ms-topnav has a fixed width, you can use one background image on the table, but be aware that menu items with a long text can be bigger then the set width. The styling of the menu item will fail.

The first image shows a menu item that has no arrow on the right. The second image shows the menu item when it does have an arrow on the right.

An example of how you could style the first level of the top navigation:

.ms-topnav {
     background-color:#70C8D4;
     background-image:none;
     border:0px none;
     color:#FFF;
}

.ms-topnavselected {
     background:#2B9AAE url(/_layout/images/topnavselected.gif) repeat-x fixed left bottom;
     border:0px none;
}

Hide the little arrow pointing down by:

table.ms-topnav td img{
     visibility:hidden;
}

Second level menu items (fly outs)

The second level menu items are the sub menu items that will become visible when you hover a top navigation menu item. In the HTML, the sub menu items are positioned underneath the overall table that contains the first level menu items. The whole fly out is rendered as a

, that contains a lot of nested

’s and tables, for every sub menu item and sub sub menu item.

Every sub menu item is rendered inside the table with class name .ms-topNavFlyOuts. This table contains a with the link to the concerning page. When there are sub sub menu items, there are two ’s. The first one contains the -tag. Only when there is a third level in the menu, the second one contains the little arrow image, pointing to the right.

The top navigation fly outs can be styled by referring to the ’s of the .ms-topNavFlyOuts table. The arrows are not that easy to style, because the image is not on the file system, but it is generated by code. To alter this image, you need to change a property of the AspMenu in your master page. How to do this is not discussed in these articles.

Reset the styling of the rollover of the menu items:

.ms-topNavFlyOutsHover,
.ms-topNavFlyOutsHover a{
     background-color:#000000;
}

Reset the styling of the background of the flyout items:

.ms-topNavFlyOuts{
     background-color:white;
}

The border that comes around the whole fly out area still has a blue border. This is set on the class name of the .zz1_TopNavigationMenu. Every fly out menu has it’s own class name, with a number. The number is variable and depends on the number of menu items on that page. You will never know which numbers will be used, since you do not know how many menu items there are. This for example will only work on one of the fly outs:

.zz1_TopNavigationMenu_8 {
     background-color:#F2F3F4;
     border:1px solid #A7B4CE;
}

When you look closer, you see that besides this class name, every fly out area has the same class name: zz1_TopNavigationMenu_0. So, to style the border of the fly out menu, you can change the border of this class name, like this:

div.zz1_TopNavigationMenu_0{
     border:1px #000000 solid;
}

Do check the fly out menu on a listpage, and double check if the list header is not visible on top of the fly out menu. This could happen when the the list header (.ms-vh or .ms-vh2) is relatively positioned. The solution for this is to make it static, it will not influence the styling of the menu.

.ms-vh div,
.ms-vh2 div{
     position:static !important;
}

Quick Launch navigation

The quick launch navigation is also known as the left menu. The quick launch has three parts.

• Quick Launch header

• Menu items

• Recycle Bin

The set of the three items together are rendered into two containers, the div.ms-quickLaunchouter and inside that is the div.ms-quickLaunch. Because the quick launch has two containers, it is possible to give the top of the menu another background image then the bottom, for example.

Hiding the quick launch menu

Some customers like the portal homepage to be without the left menu. There are several ways to do this. I’ll discuss three of them.

1: The first is to make a special page layout for the homepage. Make sure the control for the quick launch menu is inside the page layout and not in the master page. For that you have to edit all the other page layouts. Now make sure the left menu on the page layout you made for the homepage isn’t showed or even isn’t rendered at all, by removing the menu control. This solution will cost you the most effort and time.

2: The second way is to give the homepage page layout an extra reference to a style sheet. That would be a style sheet you make specially for the homepage and in where you add styles to hide the left menu.

3: Another solution to hide the left menu on the homepage is by adding styles that will make the menu disappear. It can be done in the style sheet, so the left menu will be hidden in every page, or it can be done by adding a Content Editor Web part on the page you wouldn’t want the left menu on.

First, add a Content Editor Web part to the particular page. Open the tool pane, and add some source code that will hide the left menu:

This way the quick launch outer is hidden and the left area is also gone, so that the content in the middle will have more space. The .ms-navframe is responsible for the width of the area the menu is in.

Next thing is to make sure the web part with the styling is not visible on the front end. For that, choose Chrome type “none”, in the Appearance menu and under the layout section check the check box for hiding the web part header. The menu (and the web part that is hiding the menu) is now hidden on only this page.

Quick Launch header

The header of the quick launch is a

with a and a .

The label contains the text “Quick Launch”, but is invisible because it is absolute positioned and placed out of sight by the core.css. The span contains a

with class name .ms-quickLaunchheader. This

has a background image and background color. There’s also font-color defined here, but the text inside this

is always a link. So if you want to style that, it’s more efficient to style the -tag.

Quick Launch menu items

The second part in the quick launch is the

with ID ctl00_PlaceHolderLeftNavBar_QuickLaunchNavigationManager. Inside this is a table with class name .ms-navSubMenu1. The 1 indicates the level of the menu items, The first level menu items. For every menu item there’s a in this table.

Every menu item is positioned inside it’s own table, the .ms-navheader. Only the menu items on the first level are called navheader. Besides that, the inside the table has an -tag containing a class name .ms-navheader. So when styling the whole area of the menu item, or just the link itself, make sure you use table.ms-navheader or a.ms-navheader.

Sub menu items of the quick launch

As there is a for every first level menu item, there is also a for a collection of second level menu items. Inside that is another table, the .ms-subNavMenu2 and every sub menu item has it’s own in there.

Changing the background of the sub menu items can be done very easily, because of the .ms-navSubMenu2 class name. By default the of this table has the bullet background image.

Removing this bullet can be done like this:

table.ms-navitem td, span.ms-navitem {
	Background-image:none;
	Padding-left:0px;
}

Every sub menu item has it’s own table and only one . Therefore it is possible to use two background images underneath the text of the -tag of a second level menu item. One image for the left and one for the right side.

Recycle bin

The recycle bin is the third item inside the quick launch. This table contains another table named .ms-recyclebin. Inside this table is the -tag, containing the icon and the text “recycle bin”.

It is possible to hide the trash bin icon, because it is the only image inside the -tag. There’s no padding on the -tag, so by removing the image like this, the -tag should automatically align with the other menu items.

.ms-recyclebin a img{
	display:none;
}

Site Actions navigation

If you have at least editor rights, you will find the site actions button on the right top of your screen.

The site actions button has a few nested tables and

’s. Only a few of them have ID’s or class names. From the outside to the inside:

Table.ms-siteaction
Td#siteactiontd.ms-siteactionsmenu
Div
Div
Span
Div (on hover it does have a class name: .ms-siteactionsmenuhover)
a

The -tag for example does have an ID, but since it is an index number that points to the number of menu items, it is not wise to use this ID, because it could change per page or after a menu item was added.

When changing the background image of the button, refer to .ms-siteactionsmenu div div div and .ms-siteactionsmenu div div div.ms-siteactionsmenuhover.

Here’s some css to clear up the button and undo it from it’s (background-)colors, so that it looks like it is a textual link:

.ms-siteactionsmenu div div div,
.ms-siteactionsmenu div div div.ms-siteactionsmenuhover{
    background-color:transparent;
    background-image:none;
    background-repeat:no-repeat;
    border:0px none;
}

The secret of the little arrow

What is up with the little arrow in the site actions button? As you can see in the code, there is a blank.gif, which is not the image of the arrow. And there is no background image on it whatsoever. The arrow isn’t a background image of the -tag either. So, where does this arrow come from then? It looks like it’s the -tag’s parent

, but that one only has a background image that is responsible for the blue background. The answer is closer than you think, because there is an image next to the -tag, which is called whitearrow.gif. The question I cannot answer is why it is not inside the -tag, since it should also be click-able, right? Well, it does explains why at first sight I couldn’t find the image. Mystery solved.

The site actions fly outs

The site action button had also a fly out menu when you have clicked on it. This menu is hidden in the span by an in-line display:none.

This menu is a bit different from the other menu’s. It has a

tag and a for each sub menu item. These objects cannot be styled in the style sheet.

Next time in “SharePoint’s Branding Limitations”

Next part of this article will contain information about web parts with text zones, lists and tables. Other topics are the graphical possibility’s of the edit mode and the news articles. Stay tuned!

SharePoint’s Branding Limitations, Part 1

Diantha van Marion — Tue, 21 Jul 2009 14:40:38 +0000

Introduction

This article assumes that the reader has SharePoint and basic HTML knowledge.

Process description

Communication flows

The communication between the Graphical Designer and the Front-end Developer is all about the graphical design for SharePoint and the ways to implement it. The Graphical Designer discusses the design he wants to make with the Front-end Developer to check if his design ideas are implementable on a SharePoint environment. After the Graphical Designer has a first version of the graphical design, the Front-end Developer determines if it can be implemented in the available time. If the actual costs are higher than the estimated costs, the Graphical Designer and the Front-end Developer could look for another elaboration of the customers idea, one that is easier to implement, and more predictable.

The communication between the Graphical Designer and the Front-end Developer will continue like this until the graphical design is approved by the customer and the implementation can start. The communication between the Graphical DesignerGraphical Designer has in mind for its design. Decisions concerning the colors, fonts, margins, menu’s and links are transferred by a style guide. However, if there’s a lack of time frequently the style guide isn’t fully developed, so the Graphical Designer needs to explain the Front-end Developer about the styling guides. Disadvantage of this is that the Front-end Developer co and the Front-end Developer will change and will all be about the transfer of knowledge about what can be implemented and what can’t. It is important that the Front-end Developer knows exactly what the uld forget information or interpret it differently than the Graphical Designer has in mind, and the Front-end Developer cannot check it in the style guide. Therefore, be sure that there is always a style guide that is as extended as possible.

What can happen after the graphical design is implemented is that the customer decides to change a component in the graphical design. Depending on the change, the Graphical Designer must be consulted again, or the Front-end Developer can modify it, in consultation with the Graphical Designer. The ideal situation is to adapt the style guide too.

The style guide is made by the Graphical Designer. Since he has made the design and knows exactly how the design should look like and elements graphically should behave. Beside the style guide the Front-end Developer also needs the design files of the Graphical Designer to be able to implement the Graphical Designer, for example the PSD files.

Image of default homepage

Knowledge transfer

The graphical design is based on the requirements of the customer and its company, depending on the browsers to use and its users, and of course the estimated capacity and the creative ideas of the Graphical Designer. Graphical Designers which design for MOSS must have knowledge of SharePoint. Most Graphical Designer’s will catch the default (blue) graphical design of a MOSS portal as a basis for the graphical design. They can take the default or frequently used elements of MOSS and use them for their graphical design. They keep the location of the elements approximately the same to what they see on the default portal, their example. This is the most common way to start a graphical design for MOSS.

The Graphical Designer also needs to have some knowledge about how the designed elements of the graphical design will be implemented. He needs to know how the Front-end Developer will implement a graphical design. Because the Graphical Designer does not know of every table, div and so, it is important that the Front-end Developer informs the Graphical Designer about the possibilities of implementation, however the Front-end Developer does need to have this knowledge of course. Even if the Graphical Designer used a default MOSS portal for making the graphical design, it is possible that there are elements in the graphical design that cannot be implemented on a default MOSS portal, because the default HTML won’t let you. That’s why it is very important to communicate a lot and involve the Front-end Developer at an early stage of the graphic design.

Design decisions

In this part I will evaluate some design decisions. I will comment on a number of standard components of a SharePoint publishing portal and indicate per component how the element’ HTML has been rendered and the possibilities for implementing a design on that HTML.

Scaling pages

The Graphical Designer needs to know how the page will behave if the visitor of the portal gives another format to the browser window. In case of a portal the Graphical Designer will generally recommend to use the complete width of the browser window, because portals are all about displaying lots of information. It is desirable to be able to use the full width to place as much information on the page as needed/possible, and make it liquid. This is default by MOSS, when widening the browser window, the middle column will become wider and more space for content will be available. The left column with the menu will keep its width, just like the right column.

However it is possible that the customer chooses to let the scaling behave differently. For example by dividing the available space to the left and right column. In this case the fixed width of the right column is put on a certain percentage in the style sheet instead of a fixed number of pixels, mostly 20 or 30%. The middle column should also get a width in a certain percentage. For making another partitioning it is desirable to make a custom page layout.

Example of page with variable width

Header

The area positioning on a page consists out of several rows. First there is the header, then a content area and then the footer. All visual elements of SharePoint are in one of those zones. The elements of the edit console are underneath the header, they will be discussed later.

The header itself is also built out of rows, with in every row a few SharePoint elements. In the header every row has a class name or unique ID name. The header is built with tables, and nested tables, who together are responsible for the area positioning.

Global breadcrumb

The global breadcrumb, which is the first row of the header, contains two tables, each with its own class name. This aligns the text to the left and the meta menu to the right. Therefore the global links on the left side and the global links on the right side can be styled and positioned differently.

Global breadcrumb

The menu items of the meta menu can be styled separately. However, frequently it is desirable to style all meta menu items the same. The styling can be done by using the class name of the common parent element. This way the styling isn’t influenced by any nested tables or divs that may be in the menu table.

Customized metamenu

.ms-SPLink a:link,
.ms-SPLink a:visited {
                color:green;
}

The icon that is used for the help function can be styled too. Just keep the width and height of the new image the same as the original, so that a replacement can be done easily. Always keep a copy of the original image, for back-up.

Global title area

The global title area is the second row of the header. It contains a table with three cells, the global title area image, the site title and the search function.

Global title area

The global title area image can be used to display the logo, because this element has a link with a reference to home. Therefore it is important to hide the image, stretch the a-tag to the dimensions of the logo and make the logo disappear as the background image of the -tag. Then, the text of the -tag will be placed outside the view of the browser with a negative indent. This way the logo will still have a textual link for users that use screen readers.

Global Title Area Image

.ms-globalTitleArea {
    background:blue url(/_layouts/images/logo.gif) no-repeat left top;
}

 .ms-globalTitleArea #GlobalTitleAreaImage img{
    visibility:hidden;
}

.ms-sitetitle h1 a{
    display:block;
    height:30px;
    width:100px;
    text-indent:-2000px;
}

The last cell with the search functionality doesn’t have a class name or ID. To style the search function you’ll need to dig deeper into the HTML-structure. It is possible to style the search function in the header differently than the other search functions that could appear on the portal, even if they are built the same way. That’s why you’ll need to find a unique class name combination or unique ID name or a combination of both. It is possible to style the search function in the header differently, but the other search functions, in the content zone will be styled the same, since they have the same structure. Do not style the search engine absolute, since the search engine needs to come down in the content zone when searching advanced.

#SRSB{
	position:relative;
	top:100px;
}

The icon that is used to start the search request can also be styled. Keep the width and height of the new image the same as the original, so that a replacement can be done easily. Always keep a copy of the original image, for back-up. The easiest way to style the icon is to replace the default one on the file server. A result of this is that all search icons will change, through the whole portal. As mentioned above, it is possible to style the search icon in the header differently, but the other search icons will be styled the same, since they have the same structure.

Customized search engine

Banner Container

The third row from above is the banner container or oneidtopnavbar container. In here is the banner frame wherein there is a section for the top navigation menu, the banner and the site actions menu.

Top navigation menu

The top navigation menu is built out of a table, whereof the first cell contains the first menu item and the second cell contains a set of other menu items. In each of these cells is a table with a class name that marks it as topnav and if selected, it marks it also as selected. In the first cell of this table is the a-tag, the link. If the menu item contains any child elements, there is a second cell in this table to place the little arrow pointing down. This arrow is an indicator for any child menu items available, the fly outs.

The ’s of this table do not have a unique class name combination or ID. This means the of the text link cannot be styled differently than the of the arrow. This could lead to difficulties when implementing background images on the menu items. A background image cannot be placed on the , because this will cause it to disappear twice. Once for the text link and once for the arrow td. The image must be placed as a background image on the table. This means the image will be visible underneath the text link all the way to the arrow on the right. So there can only be one background image on a menu item. It isn’t possible to use two images, like when the left side of the menu item has a different ending as the right side of the menu item, when the image isn’t repeatable on the x axis. It isn’t possible to make two images out of one, so make it a background image of the table. It is always unsure how wide the menu item will be, and so how wide the background image must be. The arrow is rendered by the code, so you cannot style the arrow or replace it with an image, though.

It is possible to give the first menu item a different styling then the others, because this menu item is considered as the top level menu item and is rendered a bit different then the other menu items. For this menu item also counts that you do not know how wide the menu item will be, so be cautious about it when making the graphical design.

If you need to use background images on the top navigation menu, use images that are repeatable on the x axis and have the same pattern at the outer left pixels and at the outer right pixels. This of course also counts for the hover states and active states of the menu items.

Next thing to style are the fly outs. These child menu items are inside a table, and there is one table, and for every child menu item. Only the table has a class name, so all the ’s, that is all the child menu items will have the same styling. The menu item that has a mouse hover can be styled differently though. For the fly outs there is the same rule, you do not know how wide the content inside it will become. Use that information wisely when making the graphical design. You can use these class names to style the fly outs:

.ms-topNavFlyOutsContainer{}
.ms-topNavFlyOuts{}
.ms-topNavFlyOuts a{}
.ms-topNavFlyOutsHover{}
.ms-topNavFlyOutsHover a{}
.zz1_TopNavigationMenu_8 {}

Banner

The banner is empty, and does not contain anything. Therefore, it will not be discussed here.

Site actions menu

The cell that contains the site action button has a table with a class name for its own. Inside that, there is one cell wherein there are different kinds of nested

’s. The a-tag inside does not have a class name or ID, just like the nested

’s. But it could be referenced using this declaration:

Default siteactions button

.ms-siteactionsmenu div div div a {...}

The site action button usually isn’t restyled, but only made blank, by removing its colors and background image. Most of the time it is repositioned by giving the table a relative or absolute position. This button is only visible for users with editor rights, so only a select group of users will see the site actions button.

Customized site actions button

.ms-siteactionsmenu div div div,
.ms-siteactionsmenu div div div.ms-siteactionsmenuhover{
    background-color:transparent;
    background-image:none;
    background-repeat:no-repeat;
    border:0px none;
}

The fly out of the site actions button is a default SharePoint fly out, and usually isn’t styled. This fly out is reused throughout the whole portal, so styling it could give some unwanted results. In the next part, I’ll tell more about the menu’s and fly outs.

Web part zones

Underneath the header is the content part. In here are the left menu and the content container. The number of web part zones in the content container depends on which page layout is chosen when creating the page. Most of the page layouts contain two columns, a wide one in the middle and a smaller one on the right. Other page layouts do not contain a left or right column, just one big zone for the content.

Page layout

The partitioning of the web part zones depends on the page layout that is chosen. There are a few default page layouts in SharePoint, but these can easily be made custom.

Not all the default page layouts have got a left and right separation; some page layouts use the whole width to show the content. The page layouts that do have a partitioning, not always do have a class name or ID on the that separates the zones. The page is then partitioned by a table with two or more columns, were for example the first cell has a hard coded width of 70% and the second cell a hard coded width of 30%. If the cells do not contain a class name or ID, you cannot overrule the width and it makes it impossible to style them separately or give them another width.

Example of page layout with variable widths

Since these class names and ID’s are the hand dishes for the styling, it makes it difficult to style a particular column or web part zone. Not only the width but also the other styling like headers, links and content could need to be styled differently, dependent on which column or zone they are in. Creating a custom page layout has the advantage that you can style the columns or web part zones differently.

Web part zone

Except the fact that a columns separation can be made easily when creating custom page layouts, web part zones can be added if wished. It is possible to provide every web part zone width a class name or ID, which means that the web parts can be styled differently depending on the web part zone they are in. If web parts are dragged to another web part zone, they will adjust to the styling of that particular web part zone.

Two column page with two web part zones in the right zone

This cannot be done with SharePoint’s default page layouts. So if there’s no budget for creating page layouts, the Graphical Designer should take notice of that and style all the web parts the same. By default there’s no way to separate styling for particular web parts or web parts in particular columns.

Two column page with one web part zone in the right zone

Footer

The content container contains the columns with web part zones and the menu and is as wide as the whole page. Underneath this container is the footer. By default, SharePoint does not have a real footer. Actually there are a few table cells, which make the optical margin, just like the left and right margin of the page. These cells can be used to create a footer.

Position of the footer

The lower down cells of the page, the footer, always are down under on the page. Even if the page does not contain a lot of content and the content does not fill the page, the footer is always at the bottom of the page, against your browser window. It speaks for itself that the footer is also on the bottom of the page when there is a lot of content and the used needs to scroll.

The footer sticks to the browser

The footer is built like this:

Page Bottom Margin Left

Page Bottom margin

Body Area Page Margin

Page Bottom Margin Right

When you remove the background color and image of these cells, you’ll keep an empty space, which is a nice margin for the bottom of the page. It is also possible to use these cells for a footer image.

Example of footer with rounded corners

Since every cell has its own class name, it is possible to make a colored bar for example with small rounded corners. Such a footer can be placed underneath the menu and content, or just underneath the content. The width of the image depends on the cells you use to display the image in, as a background image. The height of the footer is also adjustable. To place text in the footer, the master page must be edited. Making the master page custom allows you to make the custom footer instead of using the default margin cells at the bottom of the page.

Next time in “SharePoint’s Branding Limitations”

Part two of this article will contain information about the menus. The meta menu and the top navigation with fly outs in the header and the quick launch menu and site actions menu. What are the possibilities for styling this menu’s? And how is it implemented? Stay tuned!

This post is from the SharePoint Magazine Partner Spotlight Week, where our featued partner is Tam Tam

Everything You Need to Know about BDC: Part 5 of 8

Wen He — Tue, 03 Mar 2009 06:00:56 +0000

Welcome back to Part 5 of our 8 Business Data Catalog (BDC) series. In this article, we will be focusing on BDC Search. Specifically we’ll be focusing on how to enable BDC Search, how to enable full and incremental crawls of BDC data sources, and how to create a search content source and search scopes. We’ll then walk you through how to make our customer data searchable and how to make the search results “actionable”.

If you’ve been following our BDC series, we’ve previously gone through the following topics:

Part 1, BDC Technical Architecture
Part 2, Application Definition File (ADF) and its Development
Part 3, Developing an ADF to Connect to Web Services
Part 4, Using BDC Web Parts to Consume BDC Data and Embedding BDC Data in Lists

Now consider the following scenarios:

How can I find the customer information for Great Lake Good Market in CRM?
How can I find the projects and resources details in Project Server 2007?
How can I find an employee’s legal name in HR system?

With the help of the BDC Search, these all become possible. The Enterprise Search in MOSS can gather, index, and offer full-text search on all business data (entity instances) from applications registered in the BDC. Not only does it enable us to find answers in MOSS, but also it allows us to do so without having to leave SharePoint to go to these systems individually. It makes integrating search into existing line of business (LOB) applications like a CRM solution easier.

For example, if we register the Northwind sample database in the BDC, Enterprise Search can crawl it and return customer data in search results. In addition, the Enterprise Search feature’s extensibility enables us to create customized search experiences. We can create a custom search tab in the Search Center where our users can search for customers in the database, and we can also create a custom UI for the search results based on which we can also take action. So let’s dive right into it.

BDC Search Overview

As we’ve covered in prior articles, surfacing the BDC data to SharePoint using BDC Web Parts and lists is just first part of the BDC saga, it can also enable you to index and search on the BDC data. The following figure is an example of searching for information about a customer and then displaying both structured data from the database and unstructured documents and content stored within SharePoint.

Figure 1: Enterprise Search with BDC

Here’s another example of leveraging BDC to index Project Server data and enable us to search the different objects (projects, tasks, resources, custom fields, lookup tables, and so on). This is of great value because out of the box the Project Server data is not indexed. Only the objects in project workspace are indexed such as Issues, Risks, Documents, etc. For instance, if we are looking for project detail information for the Enterprise resource planning (ERP) project, we can search our Project Server and find the answers as shown in Figure 2:

Figure 2: Search Project Server with BDC

The BDC is truly a catalog of business applications that helps bridge the gap between MOSS and business applications by bringing in key data from various applications to SharePoint sites, lists, searches, and user profiles. Let’s revisit the BDC architecture from Part 1 with both XML Metadata and Search components highlighted in Figure 3.

Figure 3: BDC architecture with emphasis on the Search

Firstly, we’ve highlighted the XML Metadata because it is the key element in the Application Definition that makes the BDC Search possible. BDC operates off of an XML-based Application Definition File (ADF). The metadata in ADF enables MOSS to crawl the BDC data source and add them to the search index.

Secondly, we highlight the Search component because the search engine uses a protocol handler to crawl and a security trimmer to filter results. BDC uses these just like third party implementations when supporting BDC searching.

BDC Search enables us to quickly find content in business data through search queries. It also integrates with search scopes and search center to become an integral part of MOSS Enterprise Search. Here I’ve created a custom search tab and a search scope for the BDC data to create a unique search experience in which the BDC search results are segregated from the rest of SharePoint search results. See Figure 4.

Figure 4: Customized BDC Search Experience in Search Center

By enabling the search of BDC data, BDC Search extends the SharePoint search capabilities. This extends the reach of the back-end LOB systems. Today most LOB systems don’t have Full-Text search capability and BDC Search can serve for that purpose.

However, out of the box the BDC Search does not support indexing unstructured data like documents in a document management system. This is because the protocol handler for BDC is meant to connect to external structured data only. With custom protocol handlers, it’s possible to make MOSS index unstructured data . For example, using Web services to directly support BDC we can enable SharePoint to search, list, and retrieve documents from an external document management system via Web services.

Now let’s look into how to enable BDC Search.

Enabling BDC Search

One might think once we import an ADF, we can start to search. BDC Search doesn’t come automatically, and we must enable it. To enable BDC Search, we must first make sure these two methods exist in the ADF for the entity you want to crawl:

SpecificFinder
IdEnumerator

These are the only required metadata for Enterprise Search to use BDC to index the business application’s data.

In Part 2, we’ve covered the ADF and its vocabulary: System (data source), Entity (table), Method (operation on entity), and Association (relationship). There are three primary types of methods: Finder, SpecificFinder and IdEnumerator. An IdEnumerator method returns a searchable list of unique IDs for an entity. This list enables indexing of the entities and SpecificFinder is then used to find details for the entity instance based on the specific ID. Therefore, IdEnumerator and SpecificFinder work together to enable Enterprise Search to use BDC to crawl the business data.

Now since we have a good understanding of what it takes, let’s put it in action. We’re going to use Business Data Catalog Definition Editor, a free tool from the MOSS SDK, to create our ADF (shown in Figure 5 below). Though one of the limitations of this tool is that it doesn’t create a Finder method, BDC Search doesn’t need use this anyway, so it works very well for creating an ADF that’s just used for searching. You can learn how to use this tool here.

Incidentally, both MOSS BDC Design Studio and BDCMetaMan will create these methods necessary to implement BDC searching.

We begin by adding a LOB system for our sample database, a modified version of Northwind database. We’re going to use the Customers entity that resembles one in a CRM system (or the like).

Figure 5: Create Application Definition

To index and search for Customers entity in the database, we’re performing the following tasks:

Define an IdEnumerator method in the BDC definition (Figure 6)
Define a SpecificFinder method in the BDC definition (Figure 7)

Figure 6: Define a special type of MethodInstance method IdEnumerator.

The IdEnumerator method returns a list of CustomerID records, which will be indexed by MOSS Search. So now we know that the sole purpose of IdEnumerator here is to enable Search. Here’s the SQL query:

Select CustomerID from Customers

Figure 7: Define a SpecificFinder

The SpecificFinder method then uses the CustomerID returned from above IdEnumerator method as a parameter (where CustomerID=@CustomerID) to retrieve the fields for this particular customer. This is how the BDC search is able to search the entire Customers entity. So to make a field searchable, we just include it in the query and return as type string. Here’s the SQL Query:

Select CustomerID,CompanyName,ContactName,ContactTitle,Address,City,Region,PostalCode,Country,Phone,Fax
from Customers
where customerID=@CustomerID

Import Application Definition

Now we have our required metadata well-defined in the ADF, we are ready to export the XML metadata to an ADF file and then import it to MOSS. Once we have it imported, we can confirm that our Customers entity implements the two methods in SSP Administration page by viewing application and then entity. The Crawlable property under Entity Information means our Customers entity is available to be crawled, as shown in Figure 8.

Figure 8: View Entity Information in SSP

So far we have started from creating the ADF to importing it to enable searching. Since we can enable searching on any entity that has an IdEnumerator and SpecificFinder defined, we don’t have to start from scratch to set this up specifically for search. We can just go straight to configuring the Enterprise Search.

Configuring the Enterprise Search

Configuring the Enterprise Search consists of the following steps:

Create a content source
Perform a full crawl
Create a search scope (optional)
Add scope rule (optional)

We start by creating a content source for our BDC application and performing a full crawl, then optionally create a search scope and scope rule. These steps are very straight forward so I will focus on the main points. If you’re interested in each and every detail, check out the Customizing Search Series by Steve Mann.

Step 1: Create a content source (Figure 9)

In order to create a content source, go to SSP Administration page –> Search Settings under Search section, and click on “Content Sources and Crawl Schedules”. Click on “New Content Source” and give a name for this content source; specify “Business Data” as the type of the content to be crawled. Additionally, if we wish to index the content at regular intervals we could create a Crawl schedule that defines our full crawl schedules. Here is how my screen looks:

Figure 9: Create a content source

Step 2: Perform a full crawl (Figure 10)

In the above step, since I’ve checked the Start full crawl of this content source, it will initiate a full crawl of the new content source, and we should now see the content source crawling as shown below:

Figure 10: Perform a full crawl

We can also check the crawl log to make sure that the BDC data has been indexed correctly. At this point, we should be able to search our customers table. If we search for “great lakes”, we get search results as shown in Figure 1 above.

As we can see, both documents and BDC Search Results are listed together. This demonstrates some of the real power behind Enterprise Search. That is, we’re seeing SharePoint content side by side with external BDC content. This is great especially when we intend to search everything including both documents and BDC sources.

Another real power of Enterprise Search is its extensibility. We can create customized search experiences by creating a custom search tab in the Search Center where our users can search for customers in the database, and we can create a custom UI for the search results. This is what we’re going to do to separate the BDC Search results from other content. We can achieve this by performing the following two additional steps: 1) creating a search scope for BDC and 2) adding a scope rule.

Step 3: Create a search scope (Figure 11)

In order to create a search scope, go to the SSP Administration page, under Search section, click on Search settings. In the “Scopes” area, click on “View Scopes”. Click on “New Scope”, give it a name.

Figure 11: Create a search scope

Step 4: Add scope rule

Click on “Add Rules” where it says “Empty – Add Rules” on the newly added scope (Figure 12).

Figure 12: Add scope rule

Specify a Content Source as shown below (Figure 13):

Figure 13: Add scope rule – specifying a content source

Our BDC Search scope has been created and is now available in the search drop-down as shown in Figure 14. If we now search for “great lakes”, we get search results back from the existing database as shown in Figure 4 above.

Figure 14: BDC Search scope is available for use

As you have seen, the last two steps, even though optional, do give us additional value. That is, to segregate the BDC search results from the rest of SharePoint search results so that we can focus on just business data. Thus better search relevance is accomplished through the extensibility!

BDC Search Access Permission

It is a good time for us to know how to configure BDC Search access permission so that it will work out-of-the-gate. Often times we forget about it or ignore it, and only when the crawling fails or when the search returns no results, do we go in and dig the logs, even though it is not a bad troubleshooting methodology.

In these examples, we’ve been using “PassThrough” authentication in the ADF. That means additional settings have to be configured so that the “Default Content Access Account” (the account used to crawl) has access to the database. Also the “Default Content Access Account” must have appropriate rights to the BDC application and entity.

We’ll achieve that in the following steps:

Create a new Active Directory account for BDC search. We’ll call ours MOSS.Search.
Change the default content access account to that account in search settings (Figure 15).
Change search crawler account to that account under Operations –> Services –> Office SharePoint Server Search.
Grant this account db_datareader access to the database in SQL Server.
Grant this account Execute, Selectable in clients in Manage permissions for the ADF (Figure 16).

Figure 15: Specify the Default Content Access Account

Figure 16: Grant Execute, Selectable permissions

Note: there might be a delay of a few minutes after the permission is changed on BDC application. You may delete and re-import the BDC application definition at when needed — no need to re-crawl as long as the BDC name is not changed.

Enabling Incremental Crawling

Next, we’re going to show you how create an enhancement to our ADF to support incremental crawling through the use of the __BdcLastModifiedTimestamp entity property.

To optimize search performance, it’s important to have incremental crawl. As you may know, Incremental Crawl is a process of crawling only new or changed content from the previous full or incremental crawl. This means that we have to let BDC know what has changed since its last crawl.

To ensure that incremental crawls can be performed in the database when indexing, we’ll need to enhance the IdEnumerator method that has a return field that represents the last update time for that particular row. The Type attribute of the __BdcLastModifiedTimestamp property must be System.String and its value must be set to the value of the Name attribute of the TypeDescriptor for the field returned by the IDEnumerator method that contains the last modified date and time of the entity instance. This is illustrated below.

In our Customers table, we start by adding a column called LastUpdated of data type DateTime to indicate the last modified time of a single row. SharePoint indexing service will use that as a time stamp and incremental crawling is enabled. SQL-knowledgeable people should not confuse this with a timestamp data type. The example we are walking through is specific to SQL Server, but the concept will apply to other databases or Web Service methods.

Here are the specific steps to enable incremental crawling:

Update the database table to add a LastUpdated column of datetime data type (Figure 16).
Ensure the value of LastUpdated column is set to the current date and time when the row changes. (This can be accomplished with an Update trigger.)
Update ADF to have the __BdcLastModifiedTimestamp property of the entity set to LastUpdated (Figure 17).
Update ADF to have IdEnumerator mothod return LastUpdated field (Figure 18).
Update ADF to have a TypeDescriptor with its TypeName attribute set to System.DateTime (Figure 19).

The following figures are the screens for performing the above tasks:

Figure 16: Create a LastUpdated column of datetime type in SQL Server

Figure 17: Add the __BdcLastModifiedTimestamp property

Figure 18: Have IdEnumerator method return LastUpdated field

Figure 19: Add a TypeDescriptor with its TypeName attribute set to System.DateTime

To compare the performance, I then performed an incremental crawl. This is shown in Figure 20 below.

Figure 20: Comparison between the incremental crawling and the full crawling.

In our sample, it took significantly less time in the incremental crawling than the full crawl (35 seconds vs. 54 seconds). Depending on the size of the database and the number of changes that need to be processed with each crawl, the difference in crawl times will vary. The key of enabling incremental crawl here is performance so that the back-end systems are not unnecessarily burdened by the crawling.

Actions

Lastly, let’s show you how we can make our BDC search results “actionable” by creating a custom action on the Customers entity. There are two ways to create a custom action. It can be defined either in the ADF or added after the ADF is imported by going to SSP administration page (View Application –> View Entity).

By default through the SpecificFinder method, we get a default view Profile action that links to a simple page with your search results. This is where the customization comes in, and you could create custom Web Parts to provide more user-friendly and richer user experience. We’ll dedicate Part 8 of this series to Custom Actions so you have the best for last. For this article, let’s quickly create a custom action to map the customer using Live Search Maps (maps.Live.com).

Here are the specific steps to enable custom action with Live Search Maps:

Add Action and set parameters (Figure 21)
Check action (Figure 22)

Go to SSP administration page (View Application –> View Entity), add action and configure URL parameters.

Figure 21: Create a custom action in SSP

The parameter “Address” will be substituted at index “0″, which is specified as a querystring URL to maps.live.com. If you have already deployed your ADF before creating a custom action, you will need to redeploy it if you use this approach to adding a custom action.

Check the custom action to ensure it’s configured and ready for use (Figure 22).

Figure 22: Live Map Action appears under Actions

Now let’s test-drive our search and custom action in the following two steps:

Search any customer in the Search Center (Figure 23)
Perform the custom action based on the search result (Figure 24)

Figure 23: Search result of a customer entity

Clicking on “The Big Cheese“ will take us to the default profile page, where we can see and act upon the custom action Live Map (maps.live.com) as shown below. Clicking on Live Map will issue a search on maps.live.com using the address of “The Big Cheese”. Here’s the live map (Figure 26). Neat!

Figure 24: BDC Search Results with Live Map action available

Figure 25: Live Map of the searched customer

Conclusion

In this article we have covered the concepts behind BDC search and how to enable it. We’ve then walked you through how to make our Customer data searchable, and how to make a custom action on search results. In doing so, we’ve demonstrated the power behind BDC and MOSS Enterprise Search. Even though we have only used a database in our example, this is also all possible with Web Services, provided the SpecificFinder and IdEnumerator methods are still in place. Hope you have enjoyed reading it as much as I have enjoyed writing it. Look forward to your comments and suggestions. Aloha!

Incorporating a Master Page into a SharePoint site definition

ggalipeau — Mon, 08 Dec 2008 14:35:37 +0000

Introduction

This is the sixth article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

In the previous article of this series we discussed how to build a customized master page and deploy it with a feature. However, the manual process of deploying the feature to each server in the farm and activating it isn’t as seamless as most developers would like. It would be nice to have the features automatically activate themselves when a new site in SharePoint is created from a template.

This article will discuss the creation of SharePoint site definitions, which are templates for SharePoint sites that will automatically create the master page feature on the site when created.

Site Definition

Site Definitions are templates that developers can build in SharePoint. You might also hear the term Site Template in SharePoint, which is a customization of a Site Definition. In order to clear up any confusion on these two terms, you can just think of them like this:

Site Definitions – SharePoint template that developers can create to manipulate how a site should be created. These are stored in the 12 hive of SharePoint and are referenced during site creation.

Site Templates – Customization of a Site Definition that administrators of the SharePoint site can create from the UI screens. These are stored in the content database and these are not meant for developers to manipulate.

When you create a SharePoint site and use one of the out of the box templates, you are actually using a Site Definition that Microsoft created and shipped with the SharePoint product. For more information about how SharePoint constructs the out of the box Site Definitions, please refer to the second article in this series: Examining the out of the box Master Pages in SharePoint .

WSP Solutions

In the fourth article of this series: Deploy a Master Page for a production ready system , we discussed the manual process of creating a feature, placing it in the 12 hive and deploying it with stsadm commands. While that is a valid process to deploy to SharePoint, it is a very manual process. Also, we are now bringing another factor into our project (i.e.: the Site Definition). So, we could manually deploy the site definition in addition to the feature, but now we are starting to have a lot of manual steps. Plus, if we have a large SharePoint farm, we are going to have to repeat these steps on each server.

Thus, SharePoint created a way to incorporate all your features, site definitions, etc… into one deployable solution. These solutions are called WSP files. WSP files are basically CAB files with an extension SharePoint understands so it can deploy to a SharePoint farm. These solutions automatically get deployed to all appropriate servers in the farm. Thus, you only have to install the WSP against the SharePoint web application in order to install all your features, site definitions, etc…

What are we showing in this article?

In this article we are going to show how to create a Feature, Site Definition and WSP solution.

The Feature will deploy the master page to the master page gallery of our site, just like in article four of this series: Deploy a Master Page for a production ready system.

The Site Definition will create the template for our site. This template tells SharePoint which aspx pages to create, which web zones to create, what features to activate, etc…

Lastly, the WSP solution will wrap everything up into one deployable package.

One question that undoubtedly comes up is “why are you incorporating the feature into the site definition instead of using feature stapling?” Feature stapling is the process of creating features and stapling them to Site Definitions that already exist. For example: let’s say you created a web part in a feature and you wanted that feature to be activated on all sites created with the WSS team site definition that comes out of the box in SharePoint. However, you want to keep all the other parts of that site definition intact, all you want to do is add one more feature onto it. With feature stapling you can create a feature and tell it to attach itself to pre-existing site definitions (even the ones that come out of the box in SharePoint).

The decision to use feature stapling versus custom site definitions has to deal with the amount of customizations you need to make. There might be times when you want to use feature stapling instead of brand new site definitions. However, in a lot of cases you need to make changes that go above and beyond just the features in a site definition. Thus, it is good to create custom site definitions to manipulate these functionalities. Plus, custom site definitions activate the features when the site collection is getting created, while feature stapling activates the features after the site has been created. This timing is important to understand in some complicated situations.

So, for this particular demo I am going to activate my master page feature in a custom site definition to show the process. But, I am not saying this is the best way. If you already have a site created and just need to deploy the master page feature, you might want to look into feature stapling as an option.

What tools are we going to use?

One of the more difficult things to understand when you first learn how to create WSP solutions is the install files that are needed to build the WSP solution. These files are called the manifest and the ddf files. These files basically explain to SharePoint what features, site definitions, etc… is part of your solution so that SharePoint can install the solution to the web application.

Since these files are difficult to understand, there are a lot of third party tools available that will build the manifest and ddf files for you. These tools are usually extensions to Visual Studio. Microsoft built one called Visual Studio Extensions for WSS. Plus, there are many open source ones on CodePlex including STSDEV, SPBuilder, WSPBuilder, etc… Each of these tools provides a different approach to building SharePoint solutions.

My personal favorite is WSPBuilder. The way this product works is it mimics the 12 hive in a Visual Studio solution. As long as your Visual Studio solution has the same folder structure as the 12 hive, it will build the correct files to create the WSP solution. This is very powerful and flexible. I like this over the Visual Studio Extensions for WSS because I feel that I am restricted in what I can do with Visual Studio Extensions for WSS.

The choice of the solution builder tools you want to use is a personal choice. For this article I am going to work with the WSPBuilder add-in for Visual Studio.

Here is an example of how WSPBuilder works. Notice that the servers 12 hive matches the Visual Studio solution:

Servers 12 hive

Visual Studio Solution

As long as the 12 hive matches, you can right click on your project and use the WSP Builder menu options to build your WSP file.

Also, when you are developing on a SharePoint server, you can right click on your project and use the WSPBuilder menu options to deploy your WSP file to the local server. This will deploy it to all web applications on your development machine.

Thus, when you are developing, you should be developing on a SharePoint server. Virtual machines such as VPC or VMWare are great for this. Then, every time you make a change you can just go to the deploy menu option of the WSPBuilder menu. After you are finished developing, you can build the WSP file using the menu options and it will physically place the WSP file in your projects folder. At this point you can copy that WSP file to the production machine and deploy it with stsadm commands.

Walkthrough

Create The Structure

Start Visual Studio and choose a new WSPBuilder project.

Create a folder structure for the solution that matches the folder structure for the SharePoint 12 hive (this is really important – WSPBuilder works on the premise that the Visual Studio solution matches the structure of the SharePoint 12 hive). For now we are just going to create the following folders:
- Template – subfolder under 12 that holds the other subfolders
- 1033 – holds the xml files that will tell SharePoint about our new site definitions
- Features – holds the new features we are going to build (i.e.: lists, webparts, master pages, etc…)
- Layouts – holds our reference files (i.e.: images, css, js, etc…)
- Site Templates – holds our site definitions

Create a Site Definition

Create a new site definition based off the team site definition in SharePoint.
Copy the team site definition folder from the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\SiteTemplates\sts

- Paste the folder in the Visual Studio solutions SiteTemplates folder.
- Rename the sts folder to something unique (DemoCompanySiteDef for this example)
- Delete the defaultdws.aspx file because we aren’t going to use it for this example.

- Open the default.aspx file and change the master page to a new master page. Call this custom.master (yes, I know that this is not the name of our master page. We are going to configure SharePoint to do a string replacement of custom.master with DemoCompany.master in later steps). We will create this master page in the next step.

<%@ Page language=”C#” MasterPageFile=”~masterurl/custom.master”

Modify the Onet.xml file of the Site Definition for initial preparation

Open the Onet.xml file (located in the xml folder) and clean it up for our simple site definition.

The Onet.xml file is the file that tells SharePoint how to create the site definition. Whenever you create a new site in SharePoint it reads from the Onet.xml file to determine how to create the site. It is important to note that SharePoint is reading from the Onet.xml file when the site is being created. So, if you already have created a site, you can’t go back to the Onet.xml file, make changes, and expect it to show up on your already created sites.

Scroll down to the Configurations XML nodes and remove 2 configurations:
- ID=1 – Blank
- ID-2 – DWS

Be very careful not to remove ID=0 – Default, because this is the configuration we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

Scroll down to the Modules XML nodes and remove 2 modules:
- DefaultBlank
- DWS

Once again, be very careful not to remove the Default module because this is the module we are going to use for this site definition. When removing the other two get rid of the whole xml tag as well as everything within their xml tag.

Create the new master page feature

The master page will be created as a feature. The reason for this is that if the master page is in a feature the master page can be added to the master page gallery of SharePoint. This allows you to set out-of-the-box pages to the master page or your own custom site definitions. It also allows you to turn on or turn off the master page features on specific sites. Basically, having it in a feature (rather than directly in the site definition or in the layouts folder) gives you much more flexibility.

Create a new folder under “FEATURES” and call it something unique for your master page. For this example we will call it DemoCompanyMasterPage.
Create a folder under the DemoCompanyMasterPage called “MasterPages”.
- Copy the general SharePoint master page from the 12 hive: C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\GLOBAL\default.master
- Paste the file under the “MasterPages” folder in the Visual Studio solution.
- Rename the file to something unique (DemoCompany.master for this example).
Create two xml files under the DemoCompanyMasterPage folder.
- feature.xml – this will give a unique GUID to the feature (which we will reference later). This file also gives some important information about the Scope of the feature. Lastly, this file tells SharePoint where all the other files that make up this feature lives. This file must be called feature.xml (this is because SharePoint will read all files called feature.xml from the Features folder).

Scope=”Site” Version=”1.0.0.0″ Hidden=”FALSE” DefaultResourceFile=”core” xmlns=”http://schemas.microsoft.com/sharepoint/”
Description=”This Feature contains the demo master page”>

Please note that the Scope=”Site”. This is very important. This is telling SharePoint that this feature is for the site collection. If that Scope=”Web” then it would be telling SharePoint that this feature is for an individual site.

elements.xml – this file is telling SharePoint to place the new master page into the master page gallery. This file does not have to be called elements.xml (unlike the feature file which has to be called feature.xml). It just has to match the name located in the “ElementManifest” of the feature.xml file.

Modify Onet.xml file of the Site Definition

We are modifying the Onet.xml file of the Site Definition in order to tell this Site Definition to activate our Master Page feature when the site is created and to use our custom master page with the dynamic url replacement technique.

Dynamic Token URL replacement

To learn more about Dynamic URL replacement please refer to the second article in this series: Examining the out of the box SharePoint Master Pages.

Open the onet.xml file in Visual Studio (located at SiteTemplates/DemoCompanySiteDef/xml).
Find the xml node that says Configuration ID=0 Name=”Default”.
Add in a reference for the new master page:

MasterUrl=”~SiteCollection/_catalogs/masterpage/DemoCompany.master”>

Note: SharePoint will do a string replacement of any aspx page with ~masterurl/custom.master with the reference in CustomMasterUrl. And, it will replace any aspx page with ~masterurl/default.master with the reference in MasterUrl.

Activate the Feature

Find the SiteFeatures XML node.
Add a new Feature node in there that matches the GUID of the feature.xml file we created for our master page.

This section of the onet.xml tells the site to activate this particular feature on this particular site when it is being created. The reason it goes into the SiteFeatures (instead of the WebFeatures) is because this particular feature was scoped for a Site Collection. If the feature was scoped for an individual site then it would go in the WebFeatures.

Create the WebTemp*.xml file

WebTemp*.xml files tell SharePoint about site definitions. When a new site is being created in SharePoint the “Select Templates” list box is populated by anything it can find in the WebTemp*.xml files. There can be multiple of these files in SharePoint as long as they are in the 12/Template/1033/XML folder. SharePoint will basically read this folder for any file that starts with the word WebTemp.

Add a new folder under 12/Template/1033 in our Visual Studio solution called XML.
Add a new file to the 12/Template/1033/XML folder in our Visual Studio solution. This file must start with WebTemp. We will call this file WebTempDemoCompany.xml.

Add in the proper xml to tell SharePoint about our new site definition

A few things to note:

The “Name” must match the site definition folder exactly. We used the name DemoCompanySiteDef. This matches our site definition name exactly.
The Configuration ID must match the configuration ID in our onet.xml file of our Site Definition. We used configuration id 0.
The display category will create a new tab on the new site screen in SharePoint.
The ID has to be unique and SharePoint has already reserved certain IDs. To be safe use an ID over 10000 and make sure it is unique.

Use WSP Builder to build and deploy the solution

Now, at this point (in a regular SharePoint solution) we would create manifest.xml and ddf files. These are files SharePoint needs to install the solution properly. However, since we are using WSPBuilder, it will do that for us.

Right click the project and click WSPBuilder – Build

Verify your Web Application is created on your local SharePoint environment. Note: the Site Collection should not be created at this point, just the Web Application. And, you only need to do this once.
If the build is successful, right click the project and click WSPBuilder – Deploy.

This is needed because the build command in WSPBuilder just builds a wsp file. This file can be sent to other machines and you can use stsadm scripts to install it on other SharePoint farms. However, in development, we need a quick way to deploy it to the current SharePoint farm. The WSPBuilder – Deploy command will deploy the wsp file on all the Web Applications in the local SharePoint farm.

Use the Site Definition

Open up SharePoint Central Administration and create a new Site Collection with the site definition we just created.

Now you can go back and modify the master page or default.aspx page as you wish. Just be careful not to mess with the ContentPlaceHolders too much. SharePoint reserve these for certain actions on some of its internal pages. After every change you make you can rebuild by clicking WSPBuilder – Build and update the solution by clicking WSPBuilder – Deploy. Then you can just go to the website and see your changes. Just be aware that everytime you deploy WSPBuilder does an app pool recycle (to ensure the changes get pushed out through IIS), so you might have to wait a few seconds to see your changes (during that few seconds the site could say Service Unavailable).

It is also important to note that the first time you deploy with WSPBuilder it does a true SharePoint install. However, every subsequent time it does a SharePoint solution update. Solution updates work for most changes, however, there are some things it can’t do. So, if you run into errors it is sometimes good to do WSPBuilder – Uninstall and then WSPBuilder-Deploy to do a real install in certain situations when you are making changes.

If you are curious to what a SharePoint solution is doing, then just check out the files in the 12 hive:

C:\Program Files\Common Files\Microsoft Shared\web server extensions\12

You will notice that all the files we created in our Visual Studio solution have been “pushed” down to the folders in the 12 hive. The WSP knows to “push” these files there. The WSP also knows to tell SharePoint that these files exist. This is exactly how SharePoint develops it’s out of the box site definitions.

Side Notes:

1. Any file you place in the Layouts folder can be reference in the aspx pages as “/_layouts/{filename}”. I usually recommend placing another folder under Layouts in the Visual Studio solution (just because it makes it easy to find later – you can call this folder the name of your company or the name of your project or anything that is obvious that it contains your custom reference files). Then you can reference everything in there by “/_layouts/{folder}/{filename}”. An example of this is css files in the master page. This is possible because SharePoint sets an IIS path up to the Layouts folder in the 12 hive and calls it _layouts.

2. If you want to create a custom webpart with WSPBuilder just click Add – new item… WSPBuilder – WebPartFeature. This will create the feature folder, for your webpart, and the .cs class for your webpart. This way you can go directly into coding and not have to worry about the Feature creation. Once you are done coding the webpart just make sure it is in the appropriate scope of your onet.xml file (SiteFeatures or WebFeatures) and it will become available to you in your webpart gallery. Then all you have to do is worry about your dll being installed in the Bin or GAC. If you choose GAC I recommend post-build scripts to move it.

3. Do not remove Content Place Holders from your master page if you start doing customizations. The reason for this is if you assign other files in SharePoint (such as list pages) to use your master pages, they will assume certain Content Place Holders exist. If they are not there, your site will just break.

Customizing Application Master Pages – part 5 of 6

ggalipeau — Fri, 31 Oct 2008 10:17:41 +0000

Introduction

This is the fith article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

In this series we have discussed master pages and we have shown how to customize a master page. Before we finish up the process (i.e.: incorporating master pages into a SharePoint site definition), I would like to diverge and talk about a frustrating subject – application master pages. Customizing application master pages is a little different than other master pages within SharePoint. Thus, I wanted to break this out into its own article to describe the subtle complexities of them and why they exist.

What is the application master page?

The application master page is the master page for application pages (also called layout pages). Thus, to answer the question “what is the application master page?”, we will discuss what an application page is. In previous articles we discussed how SharePoint web pages are a mix of templates and content data from the database. This combination is merged behind the scene and the end user sees the page. This gives us the ability to create custom pages on the fly. However, there are some pages in SharePoint that are static and used across all web applications, site collections and sites. These pages are stored in the 12 hive and are not dynamically generated with content from the database (even though they might have webparts or user controls on them). These pages are usually used for setting or admin pages. A good example is the site setting page of your site. There is an easy way to tell if a page is an application page: it will contain the word “_layouts” in the url.

Most articles or posts on how to customize SharePoint web pages ignore the fact that these application pages exist. The reason is that the argument can be made that only adminstrators can access these pages. Well… that can be true in certain situations, but it is all about how the site is set up out of the box. If you don’t take the necessary steps to make sure that application pages don’t show up, then they will. A good example of this is the search page (I am talking about the site search page, not the Search Center). When you do a search in SharPoint and the search scope is set to the current site, then SharePoint will display the results on a search page that is an application page. Thus, the end user will see an application page in this instance. So, as you can see, it is important to customize the application master page unless you remove all references to all application pages that the end user of the system might see. This is very important if you are trying to customize an entire portal to change the look so it doesn’t look like a SharePoint site.

The out of the box application master page can be found at: %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS.

Microsoft’s recommendations for customizing application.master

According to this support site: http://support.microsoft.com/kb/944105 – there is two ways to modify/customize the application.master page.

Modify the application.master page in the 12 hive – Now… if you have been following this series of articles (or any other best practice article about SharePoint), then you will know you are NEVER suppose to modify files in the 12 hive. Other than the obvious issues this causes, including breaking the best practices Microsoft lays out, it also means we have to have the same application.master page for all web applications of a server. This means we can’t have two web applications on a server that have different look and feels.
Create a custom layouts folder – In my opinion this is a maintenance nightmare. You are copying your entire layouts folder to do this – not just the things that deal with application master pages. This seems like an extreme way to do something that I do not recommend.

For the reasons listed above, I don’t particularly agree with either of these recommendations.

Luckily others in the SharePoint community agree with my thoughts here and a common solution has been introduced throughout the SharePoint community. The solution is to implement custom HttpModules.

This approach is a non-supported approach, but the SharePoint framework leaves us little options. And, the “supported” approaches above seem to do more damage than good, so I can live with non-supported for now.

HTTP Modules

Http modules intercept page requests and allow custom code to run before the page actually renders. Thus, we can intercept the request and check if it is an application page. Then we can change the master page reference dynamically as the page renders.

Note: I originally learned the steps below from this blog by David Wise – http://www.sharepointblogs.com/dwise/archive/2007/01/08/one-master-to-rule-them-all-two-actually.aspx . I would like to thank David to allow me to use his steps in this article posting. David would also like to give credit to K. Scott Allen whom he originally got the dynamic replacement of master pages idea for regular asp.net applications.

Step 1 – build the project

Open Visual Studio
Create a New Project
Choose a Class Library project (for this walkthrough I am referring to a C# class library, but the steps are the same for other types)
Call it ApplicationHttpModule
Rename Class1 to ApplicationMasterModule
Change the code in ApplicaitonMasterModule to look like this:

using System;
using System.Web;
using System.Web.UI;
using System.IO;

namespace ApplicationHttpModule
{
public class ApplicationMasterModule: IHttpModule
{
public void Init(HttpApplication context)
{
context.PreRequestHandlerExecute += new EventHandler(context_PreRequestHandlerExecute);
}
void context_PreRequestHandlerExecute(object sender, EventArgs e)
{
Page page = HttpContext.Current.CurrentHandler as Page;
if (page != null)
{
page.PreInit += new EventHandler(page_PreInit);
}
}

void page_PreInit(object sender, EventArgs e)
{
Page page = sender as Page;
if (page != null)
{
if (page.MasterPageFile != null)
{
if (page.MasterPageFile.Contains(“application.master”))
{
page.MasterPageFile = “/_layouts/MasterPages/Custom.master”;
}
}
}
}

public void Dispose()
{
}
}
}

Sign the project – this is needed to add the dll to the GAC
- Right click on the ApplicationHttpModule project and go to the properties
- Go to the “Signing” link on the right side
- Click the checkbox to “Sign the assembly”
- In the “Choose a strong name key file” dropdown, choose “”
- Enter a “Key file name”.
- Uncheck the “Protect my key with a password” checkbox
- Click “Ok”
Build the project
Place the dll in the GAC
- If you built in Debug mode then the dll will be at: /bin/debug/ApplicationHttpModule.dll
- Drag the dll (do not copy and paste) into the GAC: C:\Windows\assembly

Step 2 – Register the module

Find the web config for your site. If you did not specify a path when you created your web application then this is located at C:\Inetpub\wwroot\wss\VirtualDirectories\. If you did specify a different path and don’t remember where it is, the best way to figure it out is to go into IIS, find your website, go to the properties, click on the “Home Directory” tab. Your path will be in the “Local path” text box.
Add this into the web.config file within the “httpModules” section

Note a few things:

Type=,
PublicKeyToken – this can be found by going to the dll in the GAC (C:\Windows\assmebly), then right click and look at the properties of the dll.

Step 3 – Put a custom master page in the layouts folder

In Step 1 we told the code to look for the master page in /_layouts/MasterPages/Custom.master. Thus, we need to actually have a master page there.

Copy the application.master from %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS
Create a new folder called “MasterPages” under %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS
Paste the application.master page in the newly created MasterPages folder
Rename the application.master page in the MasterPages folder to Custom.master

Step 4 – Make changes to the Custom.master

Now that you have built an HttpModule to redirect to the Custom.master page you can customize your Custom.master page however you want. But, you still have to be careful about keeping the content place holders around per the articles I have been writing in this series.

Be Careful

Just like the regular SharePoint master pages you must still be careful when you start modifying application master pages. Here are a couple of things to make sure you do:

Don’t remove content place holders. The pages that implement the application master page assume these content place holders are there. So, any content place holder from application.master must be in your custom application master page. If you are sure you have a content place holder that is not needed, then don’t remove it – just wrap it in a tag and turn the visible property to false.
You can’t have a search control on the application master pages. I am not sure of the reason for this, but you can’t have the out of the box search control on the application master pages.
Some of the application pages are actually formatted incorrectly. Thus, when you build a custom application master page you could inadvertently mess up an out of the box application page. This can happen even if your application master page is formatted perfectly. Please read my blog post on this subject for more information: http://greggalipeau.wordpress.com/2008/07/30/custom-applicationmaster-working-around-microsoft-bugs/
Do not use this method if your install has the SSP on the same server as the main SharePoint application. There has been reported issues of the SSP having issues with this approach because the system master pages they use have a different setup.

Conclusion

This is not as much of a conclusion, as it is a plea to the developers at Microsoft who are creating the next version of SharePoint. Please make sure we have a clear path to change application master pages. Hopefully the highly anticipated 14 hive will help with the current situation.

Customizing the user experience: Overview of the default interface (Part 1 of 6)

furuknap — Thu, 09 Oct 2008 01:00:12 +0000

Have you ever wondered how the built in interface actually works? Why is a list item shown the way it is? How are the input forms built and how can you change how they work and look?

This series will introduce you to a wide variety of customization options not usually covered in books or online articles.

Most articles will have rather high pre-requisites. Basically you should be very familiar with ASP.Net, SharePoint and CAML. You should, for instance, understand very well how master pages and content placeholders work, you must absolutely be able to create a feature from scratch and you should have some experience with working with content types.

So, if you are up for it, here is an article outline for the six parts:

Part 1: Overview of the default SharePoint interface from a technical point of view

In the first article we will look at how the default SharePoint interface is built. We will look at a site, going from top-down, explore some of the the default lists, the fields used to create the basic field types, which content types are available, and how list forms are rendered.

Part 2: Modifying the default experience

This article will show you which options are available for you to modify and improve the default setup. Learn how to override the default rendering of fields or forms without voiding your supported state.

Part 3: Lists and custom list forms

The third article will cover the basics of customizing lists using different views, custom list forms, and fields.

Part 4: Content types user interface

The next article will explore how you can utilize content types to display different input forms and display forms.

Part 5: Custom fields deep dive

Ever wanted to create a new field type? SharePoint enables you to do this and it is a very powerful tool for customizing the user experience.

Part 6: Fast track to feature generation

Writing custom lists with content types by hand can take a massive amount of time. In the final installment I will share with you some tools and techniques that makes list, field, and content type generation very fast.

So, what are your waiting for? Let’s get going…

Disclaimer

Before we go any further, be advised that any changes you make to files in the 12-hive may void your warranty and cause damage to your SharePoint installation. I will come back to changes you can make and what you cannot change in the next article, but for now, feel free to experiment only in your non-supportable lab environment. I would ask you to take backups of anything you change, but we both know you won’t do that anyway, so let’s cut the crap and just admit that we are and can be renegade cowboys, or cowgirls, as long as we do so in a lab where we will not be needing Microsoft’s rescue if something goes wrong.

Also, I won’t be covering everything. Simply not enough time, and I want to keep the article to at least below a day’s worth of reading.

That’s it.

Nothing else to see here, move along.

Overview of the default SharePoint interface from a technical point of view

Actually, the term overview may be a bit inaccurate. Be aware that we will go deep into some topics. However, each of the topics we will investigate are worthy of books and books of even deeper diving. While it may seem that this article covers a lot, it does not by far cover everything, but only gives an, you guess it, overview of a whole range of aspects.

Let’s start our journey of exploration right away and get to know our 12-hive a bit better. You know what the 12-hive is, right? If not, feel free to read up on it and come back to the group later. (Ok, I just wanted to sound a bit arrogant, the 12-hive is just another name of the file structure that usually resides in c:\Program Files\Common Files\Microsoft Shareed\web server extentions\12)

Oh, and by the way, from now on I will address the 12-hive as [12], so whenever you see [12] you should know where to go.

Sites

We want to know of what a site is actually made. How are the different lists made, how are the .aspx files created and from where do they come, why do you get all those _catalogs folders, and a lot of other things. For this I will use the Basic Meeting workspace site definition and really dive deep into how it is created. In the following articles we will use our knowledge to create new lists, pages, and definitions, but we need to know what is going on first.

The [12]\TEMPLATE\1033-folder, or the numbered folder that corresponds to the language pack you have installed, contains a few different things related to the language pack in question. For starters you will find your webtemp.xml files in the XML folder there. The ‘temp’ part of that filename is short for template, not temporary, by the way.

The webtemp.xml file, or files if you have created your own site templates, contain the templates available for site and site collection creation. The webtemp.xml is actually just the list of templates and some minor configuration data, the bulk of the site template definition is actually in the SiteTemplates folder in the [12]\TEMPLATE folder. We will get there later.

webtemp.xml

If you want to create your own site templates you need to add at least one file here, called webtempXXXXX.xml, where XXXXX is something of your choosing. You cannot modify the webtemp.xml file that ships with your language pack or you will void warranty. A notable exception to this is to change the hidden attribute. You can use this to hide any templates you do not want users to see during the site collection creation process.

If you open the default webtemp.xml file you will see both Template elements and one or more Configuration elements within those Template elements. The Configuration elements are the actual site definitions, and for each of these Configuration elements there must be a matching Configuration section in an onet.xml file somewhere.

Where? We will get there later, I told you! Be patient.

Look, for instance, in the Template element named MPS having an ID of 2, this being the template for the meeting workspaces. There are five different configurations there, each being a different type of meeting workspace. To properly reference a specific site definition you need both the name section and the ID, in the format of “NAME#ConfigurationID” . So, if you want to programmatically create a site you would use, for instance:

SPWeb newWeb = web.Webs.Add("NewMeetingSite", "My new basic meeting workspace", "My description", 1033, "MPS#0", false, false);

Now it is time to award your first bit of patience. You see, all the configurations in webtemp*.xml are very basic, but still you get a lot of stuff happening when you create a site using that configuration. There must be more stored somewhere, right?

Let’s head out of the 1033-folder and to [12]\Template\SiteTemplates for a while.

Notice anything in particular? Three are folders there, true, but what are they named? Exactly the same as the names of the site templates in webtemp*.xml! There must be a connection in there, we must press on if we are to discover the true secret of the site definitions.

Open the MPS folder. Now we are getting somewhere. Look at the default.aspx file using your favorite editor. If you dissect this file you will see that it is actually the file used to render the front page of the new meeting space. Not just that, but changes made to this file will alter any Meeting Workspace in your entire site collection. I can feel the power rushing to my head. Delete it an no one will be able to hold a meeting any longer! Muhahaha! (Cue music from Stargate SG-1 or your favorite evil ruler movie scene) Obey me, office slaves, kneel before your master! I rule your meeting life from this day and until eternity! Muhahaha!

Oh, sorry about that.

Actually, this is only partially cool. If you modify a page in SharePoint, for instance the default.aspx page of a meeting workspace, your page becomes ‘Customized’ meaning it is no longer the same as it was when it was created from the site definition. In practice, what happens when you customize a page is that SharePoint retrieves the page from the site definition, ie the page we just deleted (no, you really shouldn’t delete it, unlimited power does not come from getting yelled at from your users). Then it stores a copy of that file in the database. When you then make changes to the file you only change the file stored in the database, not the actual file on the file system.

If you use a function to restore the file to the site definition, for instance from the web interface under site settings or using a SharePoint compatible editor such as SharePoint Designer, you just say to SharePoint that you do no longer want to use the file stored in the database but want to use the one on the file system, which you should have restored from backup now if you deleted it earlier.

You know, that backup…

Oh, bother…

We still need to find out more about our site, and the really good stuff is still ahead.

onet.xml

Back in your MPS folder you will also find a folder named XML, and inside you will find a file called ONET.XML. onet.xml is the file that actually holds the details of the different configurations, amongst other things. It follows the wss.xsd schema so you can get intellisense if you are using Visual Studio as well and this is a real life saver when you start writing your own site definitions. You can check out the instructions for getting intellisense in onet.xml in my blog at http://furuknap.blogspot.com/2008/04/intellisense-in-onet.html.

If you close all the first-level nodes in Visual Studio you can get a quick overview of what is inside the Project root node. In the MPS onet.xml you will find NavBars, ListTemplates, DocumentTemplates, Configurations, Modules, Components, and ServerEmailFooter.

The NavBars element contain the NavBars, go figure. NavBars are the navigational elements of a site, such as the quick launch and the top navigation bar of a team site. The navbar elements are the places where you define navbars and create and modify the links that appear in each of these navbars. More on that in a later article.

The ListTemplates section contains the list templates that will be made available with the site definition. If you go to a newly created Basic Meeting workspace and click Create from the site actions menu you will see some additional custom lists that are not available in, for instance, the Team Site template. The ListTemplates section describes the basics of these custom lists.

Note that, as for the webtemp.xml and the configuration section there, the ListTemplates are only the list of listtemplates, not the actual list templates. Hang on a bit and we’ll dig even deeper to find the detailed list templates, just like we found onet.xml from our webtemp.xml file.

The DocumentTemplates section contains the document templates you can chose when you create a new document library. In your own onet.xml you can add document templates here and they will appear for all document libraries for all the configurations in your site template.

The next section, Configurations, is where the brunt of the work is done in onet.xml. Notice the ID of each Configuration element? These IDs correspond to the configuration elements of webtemp.xml. Our code snippet above created a site based on the site definition MPS#0. We know that the MPS refers to the onet.xml file in the MPS folder under SiteTemplate and now we find what the 0 means.

Open the Configuration element with ID 0 and name Basic. Note that it uses a CustomMasterUrl attribute that refers to “_catalogs/masterpage/MWSDefault.master”. We will explore how that file is actually created when we come to the modules section.

The Lists element and its children List elements tells SharePoint that we want lists of a certain type. Remember the ListTemplates section? The Type of the List elements refers to the ListTemplate of the ListTemplates section.

ListTemplates may also exist in other places than in the onet.xml file. If you look a bit further down you see that the Lists section contains a List of type 101, and we do not have a 101 type in out ListTemplates section. So, where is list 101 located?

Well, first of all, lists with numbers in the 100s, 200s and 300s are so-called built-in list templates. 101 happens to refer to the generic Document Library list template. You can find a complete list of the built-in template types at http://msdn.microsoft.com/en-us/library/ms462947.aspx. But where is it?

I’ll keep you on the tip of your seats a bit longer. We’ll get there soon, I promise.

Next you will find a Modules section with two Module elements named BasicHome and MWSMasterPage. These module elements tells SharePoint what files, for some reason termed modules, should be provisioned with the site. We only see the name of each module here, though, not which files are actually copied. The modules are defined in the Modules section of the root element so we will get there soon as well.

You will also find a SiteFeatures and a WebFeatures section. Each section refers to features that are site or web scoped, respectively. These section defines which features should be activated with the site definition. If can be confusing to know which features are actually activated since only their Guid reference is used so you would need to search in the Features folder of your [12]\Template folder to find the correct names. The two features activated with MPS#0 are the three-state workflow (Guid FDE5D850-671E-4143-950A-87B473922DC7) and team collaboration feature (Guid 00BFEA71-4EA5-48D4-A4AD-7EA5C011ABE5).

There is one more element of the configuration section that is not included in any of the MPS definitions, and it can be extremely useful so I will include it here. I am talking about the ExecuteUrl element. The ExecuteUrl is a URL that will be launched when the site is created. This can be incredibly powerful because it allows you to perform additional tasks such as further configuring your site, inviting users, giving users intructions on how to manage their new site, or any other task that you may want to accomplish. You can redirect the user to the Create new content page, for instance, or you can create your own configuration page tailored to your needs.

The ExecuteUrl is only launched when a user creates the site through the web interface, though, not when created by other means such as through custom code. Still, it can be extremely useful for creating a richer user experience. Use it. I do. And you want to be like me, right?

Don’t answer that.

Moving along, we can now close the Configuration section and look at the Modules section.

The modules are where many of the files for our site are defined. Remember we had two modules in our MPS#0 definition, named BasicHome and MWSMasterPage? This is where we find out what these two modules actually comprise. The reason we only needed to include the names of the modules in our configuration is that the rest is defined here.

A module can comprise multiple files, which may be why they are not simply called ‘Files’, and when a module is used by a site configuration all the files of the module are provisioned according to the module definition.

Open the BasicHome module. Notice that there is a Url and a path attribute. The Url attribute says where the files should be stored on the site. For BasicHome it is empty, but it is defined for the actual files that are stored in the module.

The path attribute of the module tells SharePoint where to find the file. So, if it is empty, where is the file? The path is actually relative to the feature or the site definition, so an empty path tells SharePoint that the file is in the root folder of the feature or the site definition. In our case that would be in [12]\TEMPLATE\SiteTemplates\MPS.

If you look at the only File in this module, default.aspx, you will see that it has a URL but no path. The rule here is that if no path is set then Url will be used as path, so if your file has a physical name that is the same as you want it to be on the site then you can skip the path attribute.

See now how SharePoint mapped the default.aspx of our site to the physical file store in the MPS root, and why editing or deleting that file (no, you shouldn’t this time either) will modify all the sites that use this definition? Pretty cool, eh?

Now, contained in the default.aspx File element you will also find a few View elements and a NavBarPage element. All of these are useful. The View elements puts webpart with views of our lists into our file. Each view element has a list, which refers to one of the lists was created in the Lists section of the configuration, a BaseViewId which states which view will be displayed for the list as well as what webpartzone should host that view. There can also be a WebPart order if you have multiple views in the same webpartzone. We will get back to how the lists and their views are defined later. Using the View elements you can thus populate your webpart page with webparts during the site creation.

The NavBarPage is also useful. NavBarPages tells SharePoint where in the navbar this page should be placed, as well as the name which should be used when linking to that page. Note that several of the navigational options available in a site definition does not behave as expected. In fact, the NavBarHome attribute of a file in a module doesn’t work at all. An exhaustive investigation is beyond the scope of this article, though, and I must leave some goodies for my book

Note that the name itself is stored in a resource file. That’s another show.

There is one more very useful thing I would like to mention regarding the File element, and that is the AllUsersWebPart element. It is not present in this module, or even in the MPS onet.xml at all, but look at the STS onet.xml, located at [12]\TEMPLATE\SiteTemplates\STS\XML\onet.xml, under the module named Default:

Ever been annoyed by the SharePoint logo that appears on every new team site? Well, there’s your culprit. Inside the AllUsersWebPart is an XML CDATA containing the straight-up webpart code to add a regular ImageWebPart webpart containing that image.

You can use this to your advantage, though, to add any webpart, not just views of lists, to your page. I will share with you some simple tricks for working with this in the last article of this series. And you know that when I ask you to wait so long it must be good.

The last thing we should explore in the onet.xml file for now is the MWSMasterPage module. It is a bit different from the default.aspx module, but there are some notable differences.

The first thing that may catch your eye is that there is a SetupPath pointing to “global”. Now, for the BasicHome module we learned that path refers to the path in the site definition, but we do not have any global folder, do we? How will we find the MWSdefault.master file in the only File element of this module?

The key here is that this is not Path, but SetupPath. Setup refers to the SharePoint template folder, otherwise known as [12]\TEMPLATE, so SetupPath is not relative to the site definition folder but rather the [12]\Template folder. If you go there now you will see a global folder, and inside there, guess what, there is a file called MWSdefault.master.

The module element also has a Url attribute with a value of _catalogs/masterpage. This simply tells SharePoint where the files in this module should be stored. However, if the folder does not exist you will not get your file provisioned. How, then, does SharePoint know how to create the _catalogs/masterpage directory? The plot thickens. More on that later.

The file for MWSdefault.master contains an attribute called Type with a value of GhostableInLibrary. This tells SharePoint that the file should be cached in a library and that you should be able to work with the file as you would any other file in a library. If you go to the masterpage gallery of a site you will notice that each masterpage is a file like any other in a library. This is because they are provisioned as GhostableInLibrary rather than just Ghostable. A Ghostable file, like default.aspx, does not reside in a library. GhostableInLibrary files have version history, created by and modified by properties, and any other column that the library provides. A simply Ghostable file one does not. A GhostableInLibrary file can be checked out, approved, deleted, and anything else a library file can. A simply Ghostable file can not. Bascially, if you want to work with a module provisioned file through the web interface, use GhostableInLibrary.

The last two sections of the onet.xml file are Components and ServerEmailFooter. The latter is self-explanatory, but the former is quite strange and potentially incredibly cool. It contains a FileDialogPostProcessor with an ID. What this actually is is a class that is used to modify the file open and save dialogs on a document library. You know, when you save a file from Office directly to a SharePoint site you get a cool web interface in the Save dialog? In the FileDialogPostProcessor you can declare a class that will modify that dialog web interface. Pretty obscure, even for this series, but I may cover it in a later article if there is sufficient interest.

Done with onet.xml, time for some patience reward again.

Lists

Before we really dive into the list template goodies I want to answer the question about where the list with type 101, the Document Library, resides.

The Document Library list type is actually a feature, located in the [12]\TEMPLATE\Features\DocumentLibrary folder. Go ahead and open that folder. The contents of that folder is the actual SharePoint feature. Open the feature.xml file at the root of the DocumentLibrary folder.

feature.xml and element manifests

Every feature that actually does something has at minimum two files, the feature definition file and one or more feature elements files. The first file, by convention called feature.xml, defines the configuration of the feature, such as the scope, ID, name, description and such.

The feature.xml does not actually do anything by itself, though, it only configures the feature and lists element files that should do the heavy lifting. In our case we have only one file, an element manifest, contained in our feature.xml. The location listed for the element manifest is relative to the root of the feature, and if you look in the root of our DocumentLibrary feature you will in fact find the file listed (ListTemplates\DocumentLibrary.xml). Open that file now and note that the documentlibrary.xml contains a ListTemplate element with a type of 101. Suddenly we now see where the list template type 101 gets created.

Still, there must be something more. I mean, where are all the columns and views and content types… We are getting closer to finding the treasure but we are not quite there yet.

Notice the name attribute of the ListTemplate element with a value of doclib. SharePoint uses the name of the template to search for an XML file called [name]\schema.xml in the root of the feature. So, it makes sense to look, in the DocumentLibrary root folder, for a folder named doclib containing a file called schema.xml. If you do there now you will find the main part of the list definition, the schema that defines almost everything about the list template. Open it now, and be prepared for the grand tour of list schemas.

schema.xml

Actually, there is not to much about the schema.xml. Sure, it looks scary because of its sheer mass, but if you break it down there are really not that many aspects to it. There is a List root element containing a MetaData element, and inside the MetaData section are only five elements that make up the entire list. Nothing scary at all.

See how tiny it is? We’ll get through that in no time at all! Actually, we will go deeper into schema.xml in the third article of this series, so for now we will just skim through to grasp the basic outline of this file.

ContentTypes

The ContentTypes section contains content types or references to content types. We will go deeper into content types defined here in the third and fourth part of the series, but for now, I want to explain the difference between ContentType and ContentTypeRef. You see the ContentTypeRef variety references a site content type while the ContentType is a content type defined in the list. I know that may sound confusing, especially since the documentation does not include anything to suggest that you can actually define a content type in a list, but you can, and the wss.xsd schema for schema.xml let’s you do so. We will come back to how this can be used to create some really powerful customization in part three.

ListForms

Next comes the Fields and the Views, but I would like to skip these for a moment and go the the Forms section. Open that now.

There are four forms in the Document Library schema.xml, and you may have heard these names before. As these are very relevant to the user experience I would like to spend a little time getting to know them. We will again come back to this in part three.

The three basic forms of a list item are DisplayForm, EditForm and NewForm, and I am going to assume you are smart enough to figure out which role each plays. What is relevant, though, is how these forms are created when we provision a list such as the document library. We will come back to that in great detail in part three, but for now, know that you can customize each of these forms just as you want. This means that you can have your default forms look and behave exactly how you want, including adding AJAX, custom field controls, visual elements, heck, you can even add a Tetris minigame half-way down the page to give your users a rest while they are editing an article.

If you look at the Form elements you find that the display and edit forms have a SetupPath attribute, as well as a Url attribute. The SetupPath works in the same way that the module SetupPath does, in that it references a file located somewhere in [12]\TEMPLATE. So, if you look in the [12]\TEMPLATE\pages directory you will find a form.aspx, again a rather plain vanilla ASPX page. This form.aspx is use to render the outline of the page used for entering, displaying and updating item data. However, note that there are no actual fields in the form.aspx file. The only thing even close to something unusual is the presence of a web part zone with an ID of Main. Strangely enough, this is also referenced in the Form element. How does all this add up?

Content types and list forms

All the forms can be configured on the list level, but what is also cool is that you can do this on the content type level as well. As I said earlier, we will explore content types in greater detail later, but the ability to connect a given form to the content type rather than where the information is stored gives you incredible control over the user experience. In fact, you have seen this in action plenty of times, but you may not have known how this actually works.

Every content type has a set of forms that matches the listforms. You may not have specified any particular form if you have written your own content types, but that only means that one is provided for you by inheritance. You see, every content type ultimately inherits from the Item content type, with an ID of 0×01. Every content type you see or create will have 0×01 in the beginning of its ID, meaning it inherits at least from the Item parent type.

The Item parent content type defines the default forms to be used for rendering the final form. By default all formtemplates are set to use a template called ListForm for rendering. I will show you where this is done later in this article.

The ListForm in turn is stored in a file called defaulttemplates.wscx, locaed in [12]\TEMPLATE\ControlTemplates. If you open that file and search for the rendering template with an ID of ListForm, you will see the actual code used to render any content type form that does not override the default forms.

Fields

Back to the fields section, and it is time to blow our minds a bit, because we are going to explore a slightly complex aspect of our list schema. Open up the fields section. You should see a lot of caml, with intermixed queries, XML, javascript, the lot.

Before you assume that this will get messy and you will never be able to create this by yourself, listen a bit longer. You see, most of the time you do not have to mess about with fields code by hand. I will show you, in part six, how to generate this code real easy. We will explore in greater depth the fields section in part three, however, you should know that you can do incredibly much with a field if you are willing to spend a little time learning the basics. In part three. And some more in part five. For now, close the entire fields section and start breathing again.

And now, for the final trick of the evening I will take ten years off your life from the shock you are about to receive. Be warned that you should notify your next of kin before reading on. Make sure you settle any scores, pay all your bills, and wear clean underwear. Behold, the most scary piece of any SharePoint list, the nightmare of many a SharePoint developer, the bane of projects small and large, I would like you to open:

The Views Section!

Still alive? No aching chest pains? No bright white light inviting you to enter?

SharePoint views are scary. Real scary. Sort of like a bunch of zombies outside your door, and all your shotgun shells are in the garage. Or, like a massive rumbling in the background when you are paddling down a river just as your only oar breaks clean off.

However, after the initial shock has resided, you will find that views are cool. And probably one of your most powerful tools for customizing the user experience. And don’t worry, we will cover a lot of the basics of views in part three. And, if you are really good, I will share with you some great techniques for creating views fast and easy in part six.

But know this, by the time we are finished exploring views you will know CAML like you know the back of your hand, or you will be in misery.

For now, close the views section. If you have loved ones, call them and let them know you are all right.

There really is only one more section of relevance in the schema.xml file, and it is not present in the document library schema, the Toolbar. However, the Toolbar element is covered to some extent in part three so we won’t go into that here.

But wait, there is more!

Ok, we have gone some depth into a site and seen how the site it built, but we haven’t by far covered everything, and a few more things must be part of our exploration.

You see, we looked at the Document Library list template that we found in our Basic Meeting Workspace, or most any other out-of-the-box site template, but what about the other list templates? It would be logical that these were also features, just like Document Library, but now matter how hard you look, you will not find a feature that defines the Master Page library, the user information list, or the site-, webpart or list template galleries. These have list types of 116, 112, 111, 113, and 114 respectively.

We know these must be provisioned from somewhere because they are lists, just like any other list, but where are they located?

Not to mention the default.master page. That seems to appear out of nowhere, as none of our out-of-the-box site templates even mentions a module containing default.master.

And how are the ‘default’ content types, such as Document and Folder actually provisioned? And the built-in fields such as Title and Modified by?

Global site definition

Well, there is one more place we have not looked yet. Actually, we were there for a short moment earlier, but we didn’t stop to see what was there. I am talking about the [12]\TEMPLATE\global directory where we found our mwsdefault.master. If you open that directory now you will indeed find something that resembles a site definition, including an XML directory containing an onet.xml file. Open that file and let your eyes feast on the secret of the remaining automatically deployed lists and files.

You will find, not only the list templates of the missing lists, but also a configuration with ID=”0″ that activates two site features with IDs of CA7BD552-10B1-4563-85B9-5ED1D39C962A and 695B6570-A48B-4A8E-8EA5-26EA7FC1D162. If you search in your [12]\TEMPLATE\features folder for these two Ids you will find that they belong to the fields and ctypes features respectively. These features in turn contain fieldswss.xml that defines all the built-in fields and ctypeswss.xml that contain the default content types.

The global site definition is applied to every site definition. So, whenever we create a new definition we get the global definition and all its goodness for free. If we were to modify that definition, every new site created from that point on would have our modifications.

But we won’t do that since that voids our warranty and supportability, right? Just thought I’d let you know.

Columns and fields

Now, the final thing I want you to see are fields and columns. The terms are often mixed up, which can lead to some confusion. Fields are basically templates for columns, with a column being the field when it is added to a list or a content type. At least that is the way I use the terms. Fields are the text, multi-line, date/time, yes/no, choice value that you can select when you add a new column to a list or a content type. Columns are instantiations of these fields, such as Title, Modified, Created by, etc.

You can think of fields in much the same way as a site or list template, and columns much in the same way as a site and list. Just as a site template, say the STS teamsite template, becomes a site that you can name almost whatever you want, a field, say Text, becomes a column that you can name almost whatever you want. The doclib, or document library list template becomes a list named Shared Documents.

The fields, even the built-in fields such as text, multi-line text, date/time, and choice, are defined through XML. This means that you can add new field types or even, if you are crazy enough, change the default types. I will show you a whole lot more on fields in part five where we will also dive into how we can create new fields that completely changes how the user enters data and thus their experience of how SharePoint works.

For now we wont go into too much detail, but I would like you to know where you can find the built-in fields. A second reason for why I will not go through this like I have done with the other files is that I would like to give you some homework. More on that in a few moments.

Wrapping your head around all this

I realize that there may be plenty of stuff here that seems overwhelming. I know, I felt the same thing when I started going deep into the SharePoint model. And to scare you a bit more, even though we have looked at a great deal in this article we have only barely scratched the surface. And even if we will dive quite deep into some of these topics in the later articles we have still only looked at the user experience. There is a lot to learn about SharePoint, in the sense that there are a lot of atoms in the universe.

I would like to offer you some advice, though, on how to cope with all this.

1. SharePoint is a platform, not a product

If you think of SharePoint more as a platform than as a finished, turnkey product it will likely be easier to understand how everything fits together. Forget the teamsite, forget the basic meeting workplace, forget the default content types, lists, and everything, and start thinking of these things as demonstrations that Microsoft has provided for you. What are they demonstrating? SharePoint as a platform. Everything you see is built on that platform, and if you start to see how they built these things, using only tools that are available to you as well, you will see how powerful SharePoint really is.

2. Get a good reference

Every good developer knows that they do not know everything. Even the most dedicated senior developers and architects cannot know every intricate detail about every attribute of every element of every schema. What you should lean, right away, is how to find information. The best developers I know are not those who know everything, but those who can find and understand information quickly. The secret tool of a good developer? Get a good reference.

The best reference for SharePoint I know is the SDK. Granted, there are a lot of missing stuff there, and some things are even plain wrong, but the majority of the SDK is good. Get the SDK today and familiarize yourself with it. You can view it online at http://msdn.microsoft.com/en-us/library/ms441339.aspx or download it from the same address. The download link is in the first section of the Community Content.

3. Learn how a feature works, don’t copy what everyone else does

There are plenty of more-or-less turnkey solutions for SharePoint out there. You can basically get most anything at least semi-done by googling and copying what someone else has already done. In my blog I intentionally write non-production code, with the notable exception of the Send Document Library file as email solution I wrote for a forum user, and I do this because I want to teach the users how something works rather than giving them something they can copy-and-paste but not understand at all.

Resist the urge to copy code. You may be productive and deliver a solution, but you wont know how or what the heck you are doing. Take the time to learn how a feature works. Why does the author add this or that, how will this be rendered to the user, where does this information go when I updated the item? In the long run you will be a far better developer and create far more stable and supportable solutions.

Homework

To prove a point, as mentioned, I would like to offer you an exercise to do before the next part of this series. Don’t worry, you wont get graded and if you skip this it won’t go on your permanent record. It is simply an exercise to help you find information and explore a bit on your own.

The built-in fields of SharePoint are located in [12]\TEMPLATE\XML, in a file called FLDTYPES.XML. Use the SDK link I showed you above and go through this file and look up the elements that make up a field. Don’t worry about the details of the rendering templates, we will get to those later. For now, understand what the elements do. We will come back to these fields in part five of this series.

Conclusion

This has been a long journey, but we have only just begun investigating how everything works. We have gone from the top down, exploring how sites are built, how lists work, how lists are rendering using information both from the list and the content type attached to that list, and a short tour by the fields and columns. Our focus has been on understanding the schemas of these elements because the schemas give us a glimpse into how a SharePoint site work.

Next week we will go into some completely new stuff when we explore techniques such as overriding rendering templates that can be used to modify the default user experience without voiding your warranty.

You can take a deep breath now. We are done. See you next time.

Developing a Custom Master Page (Master Pages and SharePoint part 3 of 6)

ggalipeau — Mon, 06 Oct 2008 10:30:55 +0000

Introduction

This is the third article in a six-part series on ASP.NET Master Pages and SharePoint.

Introduction to Master Pages.
Examining the out of the box Master Pages in SharePoint.
Developing a custom Master Page for SharePoint.
Options to deploy a Master Page for a production ready system.
Customizing the Application.master Page.
Incorporating a Master Page into a SharePoint site definition

In the previous two articles of this series we discussed master pages and how SharePoint uses them to create it’s out of the box pages. Now that we have an understanding of how master pages work and how SharePoint uses them, we can start showing how to develop custom master pages.

There are two supported scenarios for customizing master pages in SharePoint:

Edit the master page in SharePoint Designer
Create a custom master page and upload it to the master page gallery

Please notice that modifying the existing master page file is not one of the supported options. Microsoft rarely supports changing files in SharePoint unless it is done from SharePoint Designer.

In this article we are going to concentrate on the “Edit the master page in SharePoint Designer” option. This will show us how to develop a custom master page. In the next article we will learn how to deploy this custom master page for a production ready system.

UnGhosting (Customizing)

When a new site in SharePoint is created it uses the default.master for its master page, which is located at %Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\Global.

Note: This is true for WSS team sites and standard MOSS team sites (MOSS publishing sites might use a different master page to start with).

SharePoint keeps a reference to this one file no matter how many sites are created. This is a process called Ghosting, or Uncustomized. Thus, every site collection and/or site in SharePoint point to one file.

If a master page is customized in SharePoint Designer, SharePoint stores a modified version of the master page in the content database (this is a technique called “Unghosting” or “Customizing”). This process basically breaks the reference SharePoint keeps to the default.master file on the 12 hive. The reason for this is that changes will not affect the other content pages that refer to it.

SharePoint Designer can’t modify the default.master page in the 12 hive because it would modify a file that multiple site collections and/or sites use. Instead, it goes through the “UnGhosting”, or “Customizing”, process. This is the process of removing the link to the 12 hive and making a copy of the default.master in the content database.

SharePoint Designer

SharePoint Designer knows about the SharePoint architecture. Since the SharePoint architecture is a mixture of physical files (on the 12 hive) and content (from the database), a web design tool for SharePoint must know about this architecture. SharePoint Designer is the only tool currently available that knows about this architecture. SharePoint Designer knows how to render the structure of the SharePoint site and how to allow for changes using the UnGhosting, or Customizing, techniques.

To modify a master page in SharePoint Designer first open SharePoint Designer on your SharePoint box. Next open the SharePoint site by going to File – Open Site. In the Site Name field put the url to the home page of your SharePoint site, without the actual page in it (i.e.: don’t keep default.aspx in the string).

After you open a site in SharePoint Designer, Designer will create the folder structure for the SharePoint site:

Create a new master page

The master page gallery is located in the _catalogs folder. Within the master page gallery you will find the default.master page. You can modify this file directly, but it is good practice to make a copy of this file and modify the copied file. I am going to call this copied master page “customDefault.master”.

After you make a copy of the master page, the content pages will not know that this is the master page they should use. So, default.aspx is the content page. And if you open default.aspx in SharePoint Designer, you will notice this in the upper right corner:

Notice that it is still pointing to the default.master page. If you want it to point to the new customDefault.master page, then right click on customDefault.master (in the Folder List) and choose “Set as Default Master Page”. After doing this, open the default.aspx page again and notice that the master page referenced changed:

So, why does this reference pointer change, but the MasterPageFile still points to default.master (MasterPageFile=”~masterurl/default.master”). The reason is dynamic tokens. SharePoint replaces “masterurl/default.master” with the dynamic token value at run time. The reference pointer we are seeing is that dynamic token. So, when you click “Set as Default Master Page” in SharePoint Designer, you are changing the dynamic token for the SharePoint site. For more information on dynamic tokens, refer to the second article in this series – Examining SharePoint Master Pages.

Customize the customDefault.master

Open up the new customDefault.master page. If you are using MOSS, SharePoint Designer might ask you to check it out at this point. If you are in WSS, you shouldn’t have to check the file out.

SharePoint Designer has three different modes for customization:

Design – WYSIWYG editor
Code – html editor
Split – keeps the design and code modes open

I prefer to keep SharePoint Designer in split or code mode. The reason is that when you customize a SharePoint master page you have to be careful where you put customizations. If you place a customization in a ContentPlaceHolder, there is a chance the customization won’t show on the final page because the implementing content page might take care of filling in the particular ContentPlaceHolder. So, if you make changes in design mode, it is beneficial to see what is happening in the html.

So, let’s make some customizations so you can see some things that can be done.

Create a footer

Find the tag in your code view and put your cursor right before it.
Wrap the footer text in a div tag.
Set a class to the div tag. For example purposes we can use an out of the box css class from SharePoint

Save the file.

Note: SharePoint Designer should give you a popup telling you that you are about to UnGhost, or Customize, your SharePoint master page. This is your warning that you are going to break that reference to the 12 hive and make a separate master page in the content database. Click Yes.

Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
Open your site in your web browser to see the change.

Create a new style

Our footer example uses the out of the box “ms-CommentFooter” for our css class. This example will show you how to change that to one of your own custom css classes.

Change “ms-CommentFooter” to “custom-footer” in the code view

Select the “new style” link from the Apply Styles toolbar on the right

Set the properties of the style
- Selector = .custom-footer
- Font
  - Font-family = Verdana
  - Font-size = x-small
  - Font-style = italic
Click Ok on the style popup
Save the file
Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
Open your site in a web browser to see the changes

Modify a SharePoint Control

Find the top menu in the code view

ID=”TopNavigationMenu”sdgds
…

Change the Orientation to Vertical

Orientation=”Vertical”

Save the file
Optional: if you are in MOSS, you might have to check the file back in at this point. Right click on the customDefault.master in the Folder list and choose “Check In”.
Open your site in a web browser to see the changes. Your menu control should be vertical now.

(Please not the intent of the above change is to show that the out of the box SharePoint controls can be changed. I understand that the actual change we made is not user friendly).

Modify out of the box css classes

Find the text “ms-globalbreadcrumb” in the code.
Right click on it.
Click “Follow Code Hyperlink”
- a. It will take you to one of the sections for this css class
- b. The section right above it contains the code for the background color.
- c. Change the background color to #000000

.ms-globalbreadcrumb{
font-size:8pt;
text-align:right;
background-color:#000000;
padding:2px 10px 2px 5px;
}

Save the css file

Note: SharePoint Designer should give you a popup telling you that you are about to UnGhost, or Customize, your css file. This is your warning that you are going to break that reference to the 12 hive and make a separate css file in the content database. Click Yes.

Open your site in a web browser to see the changes. The top bar should be black now.

(Please not the intent of the above change is to show that the out of the box SharePoint controls can be changed. I understand that the actual change we made is not user friendly).

Be careful with your power

These are just a few examples of some customizations that can be done to the master page through SharePoint Designer. The customizations you can do are endless. However, you must be careful that you do not customize something that is required for SharePoint to work.

Some examples of controls you don’t want to remove are:

Site Actions
Search (if you want search capabilities)
Navigation menus (unless you want to replace them with your own navigation)
Etc…

Also, be careful where you make your changes. In the previous articles we talked about how making changes to content within ContentPlaceHolders might get overridden by the implementing content page. Thus, if you make a change to a ContentPlaceHolder, you might not see it on your page. My recommendation is to put SharePoint Designer into Split mode or Code mode so you can edit the html directly and you can be sure that you are not editing html within ContentPlaceHolders.

And remember; don’t remove any of the ContentPlaceHolders. The content pages in SharePoint already have references to these place holders. If you remove them the content pages might break.

Undo your Customizations

After making the change notice the default.master in the folder list on the left side. It now has a symbol next to it. If you mouse over that symbol it will tell you that the page has been customized. This is telling you that you have UnGhost, or Customized, this page at one point.

If you decide that you made a mistake by UnGhosting, or Customizing, your file – then you can undo your changes by “re-Ghosting” the file. To do this, right-click on the default.master file and choose “Reset to Site Definition”.

SharePoint Designer Pros

Easy – SharePoint designer provides an easy experience to customize SharePoint master pages. Any user with html experience should be able to use SharePoint designer to make changes to a master page. As the steps above show – you can just open your master page up, make your changes and then save your changes in SharePoint Designer.

UI experience – SharePoint designer gives you a WYSIWYG (what you see is what you get) UI experience. This means you can make changes to the website through an interface that looks like the website. The other techniques we are going to mention do not allow for this.

SharePoint Designer Cons

Unghosting/Customizing – the Unghosting, or Customizing, technique keeps all changes scoped to the respective site collection. There is no real way to point the master page to another site collection. This can hurt maintainability if you are creating multiple site collections on one SharePoint box and want to keep a consistent master page.

Not Deployable – SharePoint Designer forces you to make changes directly against a SharePoint site collection. This makes it hard to move from a development, to QA, to production environment. This also makes it so the customized master page cannot be used against multiple site collections.

Conclusion

SharePoint Designer provides us a quick way to customize master pages in SharePoint. This is a great tool to design master pages and/or customize an existing SharePoint site. However, SharePoint Designer does not provide a clear deployment path for projects using a development lifecycle. The next article in this series will show how to create custom master pages that can be uploaded to any SharePoint site for easy deployments.