Tonight’s article is one based on a little trick I pulled of last year at one of my customer’s Intranet. As it turns out, there seems to be quite some people using Google Search (Live Search anyone?)
So how do we add this search scope? The trick lies in a custom page for the search scope. When creating a search scope in your site collection settings, you’re allowed to enter a custom search page.

This custom search page simply has to redirect to the google query webpage: eg.http://www.google.com/search?q=ENTER+A+WORD. Don’t forget to replace the ENTER+A+WORD content of the q variable with the k variable you find in the query string of the custom page. This is whare all the magic lies, you see. So in the end, we’re basicly rerouting the query from SharePoint to Google. Pretty simple, but very effective!

Hope you guys liked the trick. See you next time!

In a country where English is not the native tongue, localisation can be pretty important. Localisation within SharePoint is achieved by using resources and resource files. Although the use of resources is not mandatory, it’s usually good practise to use them anyway. You don’t want to hard code strings in your application, and, moreover, you never know when your application should be localized. Setting up and using these resources in SharePoint can be quite confusing. So here is a little article covering this topic.

Resources

Resources – in this case: strings – are contained within XML based .resx files. Every resource in such a file is identified by a fixed name. (quite like a HashTable) Here is a little example.

<root>
<data name="FieldManagerPageDescription">
<value>Manage the field of this application.</value>
</data>
</root>

For every new localization, you need a new .resx file with the same names as keys. You can just copy the original .resx file to achieve this quickly. In this new resource file you translate the original values within the value tag. The new resource file has to be named as follows: <original_name>.<culture>.resx.
eg. – myresource.resx
- myresource.en-US.resx
- myresource.fr-FR.resx

SharePoint & Resources

First thing you need to know, SharePoint defines two kinds of Resource files: Application resources and Provisioning resources. Application resources are resources used within the normal execution of the SharePoint application. Normal SharePoint execution include: Application Pages, Web Parts and Controls. SharePoint also makes a difference between application resources used in normal web applications and application resources used in the central administration. Don’t forget that. Provisioning resources, on the other hand, are used when provisioning elements, so you have to use them within features, site definitions and list definitions. Ok, now let’s see the practical side of it: deployment and usage.

1. Deployment

Resource files in SharePoint are located in different folders. Here is a list:

• C:\Inetpub\wwwroot\wss\VirtualDirectories\<port>\App_GlobalResources\
• <hive>\12\Resources\
• <hive>\12\CONFIG\Resources\
• <hive>\12\CONFIG\AdminResources\
• <hive>\12\TEMPLATE\FEATURES\<feature>\Resources\

So, how do you know where to put your resource files? Well, every type of resource has its own folders.

Provisioning resources

• <hive>\12\TEMPLATE\FEATURES\<feature>\Resources\Resources.<culture>.resx
• <hive>\12\TEMPLATE\FEATURES\<feature>\Resources\
• <hive>\12\Resources\

Every feature uses the resources file located in its Resources folder. You can however use another resource file or even share resources. To share resource files you have to put them in the 12\Resources\ folder. Site definitions and list definitions also get their resources from this folder.

Application resources

• <hive>\12\CONFIG\Resources\
• C:\Inetpub\wwwroot\wss\VirtualDirectories\<port>\App_GlobalResources\

Application resources are located in CONFIG\Resources folder. For a web application to use those resources, they have to be copied to their App_GlobalResources folder. (each web application has its own Global Resources folder) How is this done? At creation of the web application, the resources are initially copied to the App_GlobalResources folder. When adding new resources to the CONFIG\Resources folder, the resources have to be copied to existing web applications. You can do this manually or use the STSADM command: copyappbincontent.

Application resources: admin

• <hive>\12\CONFIG\AdminResources\
• C:\Inetpub\wwwroot\wss\VirtualDirectories\<port>\App_GlobalResources\

Application resources for the central administration work the same way as normal application resources, except that the base folder is CONFIG\AdminResources.

2. Usage

This last part will focus on how to use resources within SharePoint elements. Luckily it doesn’t really matter which kind of resource you are using. Here are the different ways:

In C#:
HttpContext.GetGlobalResourceObject("MyResource", "MyName").ToString();

In ASPX properties:
<%$Resources:MyResource, MyName%>

In ASPX as text:
<asp:literal runat="server" Text="<%$Resources:MyResource, MyName%>" />

In XML:
$Resources:MyResource, MyName

In XML features, using the default resource file:
$Resources:MyName

3. Conclusion

There you go. Everything you will ever want to know about resources in SharePoint.

Part of this article is derived from the excellent article of Mikhail Dikov. You can consider this article as some sort of extension of his article. Be sure to read it. Also, I’d like to thank Tom Verhelst for the heads up on the copyappbincontent. Thanks man!

Have a great week!

SharePoint is build upon lists. These lists contain items. So the action to retrieve items from these lists is quite common. But when you’re coding against the object model. You might run into surprises. In the previous post I already talked about internal names and display names of fields. Today I’ll talk about an issue when retrieving items from a list, and more specifially from a view.

When SharePoint is retrieving items from a list or view, SPList.GetItems is always called. This method will actually create a new collection of items. Those items will actually be retrieved by a query. To query in SharePoint we use a SPQuery object. This object is a container for SQL like queries. You select the fields you want to see, you have some conditions, a rowlimit, … And this is were a possible problem can reside. When retrieving items from a view, the query will only retrieve the fields defined in the SPView. In other words: the SPListItems you will get do not include all the data. This can be very confusing, as you expect a one-to-one relationship between the data of an object and the SPListItem. You should not forget however that the SPListItem is actually a proxy container for XML data. The object encapsulates the data for easy access and is not the actual full (logic) list item.

So how can we solve this? Well pretty easily actually. We create a real SPQuery object to retrieve our items with:

SPView view = myList.DefaultView;

SPListItemCollection myColl = myList.GetItems(query);

Pretty easy, huh. The thing to remember here: SPListItem objects encapsulate XML data and are not the actual list items! Have a great week, everyone!

When creating columns (more commonly called fields) in SharePoint through the interface, you have to enter a name for it. This name is used throughout the lists and sites, included internally. Except when you try to change the name, it’ll only reflect on the outside. Internally the old name will be kept. This is because a field has two names: an internal name and a display name. When creating a field, you set both. When renaming it, you only change the display name. (There is actually no way to change the internal name afterwards)

But why is this a concern? Well, in the object model it can become quite vague when to use the internal name and when to use the display name. Here is a short list with some common methods and the name they need.

• SPFieldCollection[name] : SPField
  name: DisplayName
  unexistent: exception
• SPFieldCollection.GetField(name) : SPField
  name: internalName, displayName or internalName and displayName from the current context
  unexistent: exception
• SPFieldCollection.GetFieldByInternalName(name) : SPField
  name: internalName
  unexistent: exception
• SPFieldCollection.ContainsField(name) : bool
  name: displayName or internalName
  unexistent: boolean
• SPListItem[name] : object
  name: internalName, displayName or internalName and displayName from the current context
  unexistent: null
• SPListItem.GetFormattedValue(name) : string
  name: internalName, displayName or internalName and displayName from the current context
  unexistent: exception

If I find more relevant functions, I will update this list. On a related note, there also exists a static name. This is a name used by the field type. This is different from the internal name, as the internal name must be unique in its list and could have changed.

Hope this clears up some confusion about field naming in SharePoint. See ya.

Back again for a SharePoint branding issue, and this time we’ll tackle the calender. More specifically its calender views: the day and the week view. Let me first show you, how the week view should look like:

As you can see, an appointment can cover multiple hours. This way you have a graphical overview of how much time appointments will take. This, however, is how it looks like on the other MOSS master pages:

This is not what we expected. Appointments now only cover a small fragment of the time to take, while the rest stays blank. It is very confusing for the user. And some appointments seem to pointlessly be in different columns. The day view experiences the same kind of problem. What is this weird voodoo? We did not change anything to the calender, now did we?
Well, no, we didn’t. But we did change the looks of it by changing how the looks are parsed. As I already mentioned in another article a couple of weeks ago, the other MOSS master pages use a (correct) doctype declaration, while the default master page does not even contain one:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

Make no mistake, this is a declaration HTML pages should contain. Otherwise, you have no clue how browsers will render the page. Internet Explorer falls back to its “quirk mode”, where everything is “kinda” allowed. Other browsers will just try to render the page. And this is what we experience in the calender views. The inner box of the appointment has a CSS property: height equals 100% to make the appointment cover the whole time slot space reserved in the table of the view. In the doctype declared version, this is only supported if all parent elements also have a CSS height equal to 100%. Of course, this is not the case for all its parents. That’s why the appointments get shortened.

Is there a solution? Well, no solutions, only workarounds, I’m afraid.

• Remove the doctype declaration from the master page. I don’t really advice it, but it can do the trick. Make sure other browsers still display the master page correctly. Future browsers can break the layout however. (this is what SharePoint did for the default.master)
• Rewrite the views. You could make the views compatible with current standards, but it’ll cost quite some time to develop.
• Have SharePoint show the default.master for the calender views. It’s an ugly workaround, as you’ll have different layouts in your site, but it works.

Once more, a very unfortunate branding issue. Aspecially, because it could have been prevented by generating correct HTML. Hopefully this kind of bugs will be resolved in future SharePoint versions. Till next time.

Today I’ll be reviewing the SharePoint SDK’s. I’m not saying they are bad, but I’ve never found any good overview about ‘em. And I guess such an overview can be usefull, especially for people starting with SharePoint.

Before we begin, let me explain what a SDK is. A SDK is a Software Development Kit. It’s a set of resources designed to help understanding a specific technology. Sometimes a SDK is necessary to allow development with such a technology. (I’m thinking about the Java SDK) So, what are those resources? Well, it depends. They can include a lot of things. But most of the time, you’ll find documentation (CHM’s and the likes), samples, tools, templates, … you name it. Really usefull stuff.

SharePoint SDK’s come in different flavours. There is the online MSDN section with all the documentation, together with links to seperate downloadable resources. Or you can directly download the SDK. This download will include the documentation, samples, etc, but is suited for offline use, as an internet connection is not required once installed.

So what are the SharePoint SDK’s? First off, there is the Windows SharePoint Services 3.0 SDK. This SDK will only cover WSS related topics. And although it’s quite usefull, the offline installer includes only a couple of files, more specifically: the actual WSS 3.0 reference and a compilation of technical articles. Both can also be found on the online version.
The Microsoft Office SharePoint Server 2007 SDK is much more interesting. It includes both WSS files, and adds much more reference on the MOSS-only technologies. Also, it features some nice samples with source code. This gives us the opportunity to catch a glimpse at how the guys at Microsoft are using SharePoint, which is quite nice if you’re starting off with SharePoint and have no idea how to begin development. The MOSS 2007 SDK also includes the Enterprise Content Management Start Kit (ECM Starter Kit). This starter kit gives some in-depth information on the new ECM features and platform in Office SharePoint Server 2007. Moreover the starter kit is the collection of some white papers and code samples.

Next is a handy overview for the SDK’s:

In short, the MOSS SDK completely covers the WSS SDK. And even if you don’t have MOSS, the MOSS SDK is still very interesting and worth the download, as the samples give a great in-depth look at coding for SharePoint. ’till next time!

This final blog post (for now) in the SharePoint Branding Issues series is one regarding web parts and their branding issues. I’m assuming most of you know what web parts are. They are like mini applications within a web page. As they are so small, you’ll often add several of them together on the same web page. In other technologies, such applications are called widgets or gadgets or whatever. But basicly, their ideology is the same. A nice example is featured on live.com.

To get back to .NET, web parts are a new technology within ASP.NET (and unified in version 2). In previous versions of SharePoint, they used some custom made framework. And now in WSS 3.0, they are slowly migrating to the new ASP.NET 2 standard, which allows far more easy web part development. Finally to be complete, a few more statements regarding web parts. Web parts are placed within horizontal or vertical web parts zones. These zones can define the chrome style used for the web parts within. The web part chrome, for those who do not know, is a fancy word for its border decoration. Furthermore, the web parts need one single web part manager, per page, for.. well.. managing purposes. Finally, all of these concepts have a corresponding class within the System.Web.UI.WebControls.WebParts namespace. And basicly this is, in a nutshell, what web part infrastructure is all about.

Now, the thing with SharePoint. They decided to overwrite all of these classes (just as we would for a custom branding job in ASP.NET). But somewhy they made the decision to make the new classes all sealed. So basicly you can not change anything, except, of course, if you rewrite every single class… I know… And as one of my hungarian colleagues would say in such a situation: nice!

The chrome in SharePoint consists of 5 fixed chrome types (Default, None, Title and Border, Title Only and Border Only). These are implemented in an internal SPChromeHelper. What this class does, is adding the following structure as chrome:

<table>
    <tr>
        <td>
            <table>
        </td>
    </tr>
    <tr>
        <td>
            <div>
        </td>
    </tr>
</table>

Depending of the style the first row, which is the header, will be generated or not. Accordingly CSS classes are attached to the rows, the inner div and the inner table. As you can imagine, this kind of structure can be really restrictive. It is very difficult to add gimmicks, like rounded corners, to such a composition.

What can we do then? Well, basicly, applying tricks and hacking our way in. To achieve this, once again, our friend is CSS. By adding some classes to the right place and by using some specific CSS selectors, one can manage to achieve some degree of customization. A possible solution could be to add a specific CSS tag name to the declaration of the zone tag in your page. This way you can reach its inner web parts through the use of CSS selectors. In most cases you can define your own zones, so this can potentially be a solution for the problem. Another, more obvious solution, consists of simply overwriting the fixed chrome type’s CSS styles. The issue here is that every web part has to be set with the correct fixed chrome type to display your customizations. Of course, you still have the same limitations as the previous solution, as the structure of the chrome is still the same. More over, you usually cannot reach all generated HTML tags using only the fixed CSS class names.

While writing this article, I found this post written by Daniel Terborn. Daniel tackled the same problem and supplied another possible solution. He decided to create a base web part which implements all of the layout. Finally, with some CSS hooks, he manages to get really nice web parts. The problem with this solution is that it only applies to custom written web parts. In some situations this can be acceptable (by only using custom web parts), but most of the time you’ll want to use the out-of-the-box web parts too, for obvious reasons.

Conclusion? There is no clean and neat solution for web part branding within the current iteration of SharePoint products. We can only hope the sealed classes will be opened up in future versions. Until then, happy SharePointing.

Application pages are those special pages within SharePoint that share functionality accross sites. Some examples include the site settings, the list settings, each setting page within those settings, the All Site Content pages, the personal settings pages, etc. A way to directly recognize one of these pages is to look at the URL of the accessed page. If the url contains this segment “/_layouts/”, you are dealing with an application page. Why? Well, the /_layouts/ directory is a virtual directory created by IIS and is available to every created SharePoint site. You can access every page within the layouts directory by simply adding the path to your site url. For example: http://www.host.com/subsite/_layouts/settings.aspx. But where does this path redirect? The _layouts virtual directory is mapped to a fixed directory within the SharePoint hive, more specifically: C:\Program Files\Common Files\Microsoft shared\web server extensions\12\TEMPLATE\LAYOUTS\. So, every page within this directory is accessible through the special \_layouts\ directory.

Another way to recognize these pages is that, if you use a master page other than the default one, the application pages still seem to use the default master page. I write “seem”, because although the appearance seem to be the same, it is a different master page. This master page is also located within the layouts directory and is called application.master.

If you want a complete make-over of your SharePoint site, chances are you’ll want to change the appearance of those pages. One way to do this, is to edit the application.master master page. This can be a valid solution if your whole farm uses the same master page, as all application pages of the sites on your server use this system master page. So, if you change the master page, the changes will be visible on all instances. Most of the time, however, you have different sites on your server with different branding needs. So this approach is usually out of the question.

My solution consists of altering the application pages themselves. Although this is not a recommended practice, as Microsoft is not supporting this (Service packs could overwrite the changes), sometimes it’s the only option left. Let me show you what to add:

<script runat="server">
protected override void OnPreInit(EventArgs e)
{
base.OnPreInit(e);
MasterPageFile = SPContext.Current.Web.CustomMasterUrl;
}
</script>

Basicly we’re assigning, at run time, a new master page to the application page. Application pages can use the SPContext object to find out the context in which they are called. From this object we extract the current site (a SPWeb object) and assign the CustomMasterUrl property as the application page’s master page. This will do the trick just fine.

An important note to this solution, regards the master pages themselves. Master pages for application pages need to support two extra content place holders, PlaceHolderPageDescriptionRowAttr and PlaceHolderPageDescriptionRowAttr2. As these place holders don’t seem to do much, you can just add those two tags within a hidden ASP.NET panel to your master page.

<asp:ContentPlaceHolder id="PlaceHolderPageDescriptionRowAttr2" runat="server" />
<asp:ContentPlaceHolder id="PlaceHolderPageDescriptionRowAttr" runat="server" />

If you are using this technique, be sure to add these tags to the default.master master page in the SharePoint hive and this for compatibility reasons with the other sites. Of course, do not forget to add them to your custom master page too, as this is usually the reason, in the first place, to apply this solution.

A nice extension would consist of making the Application Pages Master Page of a site selectable through the UI (in MOSS) for selecting a master page. You could then use the SPWeb property bag to save the master page url.

Untill next time, happy sharepointing..

Navigation can break or make your site, and more specifically, your site’s usability. One of the tools to achieve a good navigation experience is the breadcrumb. In opposite to a menu structure a breadcrumb is quite space saving. And this is, according to MSDN, because it displays a hierarchical path of hyperlinked page names that provides an escape up the hierarchy of pages from the current location.

Basicily, it shows the current node and all its parent nodes. For the sake of completeness, it’s also called an eyebrow. And I’m not making this stuff up.. :p All in all, I’m pretty sure you guys all know the beast. I, for one, find it pretty usefull… as long as it keeps consistency along the way.

Back to SharePoint now. A breadcrumb within ASP.NET is called a SiteMapPath. This is a control which uses an XML sitemap of your site structure to keep track of your every move. It then shows your progress in a nice little breadcrumb. To access the sitemap, we need to use a .NET object called SiteMapProvider. As this is an object in code, we can change the way such a SiteMapProvider works and feed him some custom links programmically in stead of using a XML scheme. This gives a whole lot of flexibility. And because of SharePoint’s inherent dynamic nature, this is why almost all SiteMapProviders within SharePoint are implemented this way.

WSS natively offers a couple of SiteMapProviders (SPNavigationProvider, SPSiteMapProvider, SPContentMapProvider and SPXmlContentMapProvider), each with its specific use within your site. MOSS adds about 10 more. And it’s in MOSS, the troubles begin. Say, you design your site and you have to choose the breadcrumb’s location. Done? Ok.. which SiteMapProvider will you use? The default.masterpage has two (event up to three) breadcrumbs integrated in its design, all with different SiteMapProviders. (I wonder why this design decision was made) The two providers used are:

• SPContentMapProvider: the default WSS SiteMapProvider which shows nicely all different items and lists
• CurrentNavSiteMapProviderNoEncode: a provider which parses pages, not as items in a Pages list, but as sections within the site, which is pretty clean.

My requirement was: I want both advantages: items and lists nicely shown and pages cleanly parsed. Unfortunately, the WSS SiteMapProvider does not know pages and the MOSS SiteMapProvider does not parse lists and items. So, I decided to develop my own SiteMapProvider.

A SiteMapProvider consists of two things. A class containing the logic and an entry in the web.config enabling the SiteMapProvider’s use in a masterpage. Let’s first start with the logic.
As this is a MOSS problem only, I created a class inheriting from a MOSS SiteMapProvider: CombinedNavSiteMapProvider. This one will show nice complete breadcrumbs, except of course for lists and items. The SiteMapPath control uses one particular property from the SiteMapProvider: CurrentNode. So this is the one to override. This is the code I came up with:

public override SiteMapNode CurrentNode
{
  get
  {
    SiteMapNode node = base.CurrentNode;
    SPListItem listItem = SPContext.Current.ListItem;
    string url = HttpContext.Current.Request.Url.AbsolutePath;
    bool isItemSelf = listItem != null && url.EndsWith(listItem.Url);
    if (!isItemSelf)
      node = SiteMap.Providers["SPContentMapProvider"].CurrentNode;
    return node;
  }
}

Two things to notice. I check if the url is a page by comparing the requested url with the current item’s url. If they both match, it’s a Page alright. Second thing, to parse with the default WSS provider, one can find the correct provider in the static property Providers from the type SiteMap.
The last piece of the puzzel is the entry in the web.config. This is pretty straight forward. Go to configuration.system.web.siteMap.providers and duplicate the entry of the provider you inherited from. Change the assembly details and you have yourself a working SiteMapProvider.

All in all, this was quite a challenging change to find a solution for and to implement it. But once up, it works like a charm and seems so easy. See you next time!

When searching in MOSS, your results are shown in the search center. This is a special site you can create within your MOSS site collection. When using the default master pages, everything looks nice. The search box is in some blue area, while results get listed on the page. So far, no problem.

Say you want to develop a new master page. You take your basic place holders and arrange them on your page, the way it best fits your design. One of those placeholders is called PlaceHolderTitleBreadcrumb. What does this place holder contain? You might have guessed it, it should contain the breadcrumb of the page. And this is very crucial. Master pages are a technology which rely on “design by contract“. This is a special way of designing based on trust. In our master page we add content place holders to enhold specific parts of page. We give them specific locations and identifiers and we expect the correct functionality in it. Sadly, this is not always the case.

The search center is one of those areas not respecting the content place holders. Let’s look what will happen, when changing the master page of our site. (And once again, I’m just switching to a MOSS master page)

As you can see, the layout of the pages is somewhat disturbed? Why? The page layouts, which are used in those pages, give another meaning to our PlaceHolderTitleBreadcrumb place holder. They have the complete search box logic in it. A valid question here would be: why? Well, my guess is: the search looks nice when used in the default master page. They wanted to distinguish the search box area from the results. So they added the search box in the PlaceHolderTitleBreadcrumb. Now, for people who have moved this place holder (to the top, for example) within their custom master page, this can be a serious problem.

The solution, per se, is not that complicated, nor hard to apply. You just open up the two page layouts (SearchMain.aspx and SearchResults.aspx in your site collection’s masterpage catalog) move the search boxes from the PlaceHolderTitleBreadcrumb to the PlaceHolderMain. And you’re done, quite simple. But this is not where the problem resides. What to do with your other search centers in your farm? … Let me think… How about altering the files directly on the disk in the 12 Hive? This way, when provisioning, the search centers will have a nice layout in all master pages? Ok, but what if your distributing the thing? Well, in this case, one could provide some altered page layouts to use, and dynamically switch the old ones to the new ones in a feature receiver. And so on, and so on…

I hope most of you will realize these practices are mere patching up work. They are not giving a real solution. Sadly, most of the times, this is what we have to do to get things done. The true solution consists of conventions, and keeping them applied. Unfortunately, in a team as big as the development team of Office, this can be quite cumbersome. Hopefully they’ll keep that in mind for next iterations, and try to be more consistent. Until next time!