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!

Dependency is one of those magic paradigms in Workflow Foundation which gives the use of the framework so much more richness, especially when using activities to break up functionality.
Dependency lets properties depend on other properties, and this in a dynamic way. In practise, if property object1.Property1 is dependent of object2.Property2 when you assign or get the Property1 of object1, you are actually modifying and retrieving Property2 of object2. The great advantage of this method and way of thinking is the avoidance of duplication of data. Also you enable activities to connect to each other.

So how does it work? There are actually two steps. The first one is the setup of the activity and its properties. The second one is the actual binding between two properties.

STEP 1 : Setup of the activity
Dependency at its core consists of two main classes: DependencyObject and DependencyProperty. The DependencyObject is the object that needs the data. It will do this by exposing properties which use DependencyProperty objects. One thing to remember is that when using dependency, the source object (the object which has the actual data) will never know that another object of objects is depending on it.
As dependency is one of the core paradigms of Workflow Foundation, it won’t come you as a shock to know that the base Activity class inherits from the DependencyObject class. The DependencyObject class exposes a number of methods to work with DependencyProperty’s. DependencyProperty’s are static values defined in the DependencyObject implementations. Those implementations (eg. Activities or Object1) are using these static values in Properties like this:

public class Object1
{
public static DependencyProperty Property1Property =
DependencyProperty.Register("Property1", typeof(string), typeof(Object1));

public string Property1
{
get { return (string)base.GetValue(Property1Property); }
set { base.SetValue(Property1Property, value); }
}
}

It is doing this as Properties should enhold actual data or link to other properties. This is why Workflow Foundation needed this alternative method with static values and internal methods. DependencyProperty’s define when a binding is chosen or when actual data is set. Actual data will be saved in an internal dictionary.

STEP 2 : Binding of properties
So how can we use these properties? There are two methods and both of them can be achieved in the visual designer as well as in code. (As you all know the visual designer is just creating code in the code behind designer class)
The first method is to use actual data. You can do this by assigning data to the property and retrieving them from the property, just like any other property. Nothing really special, actually.
The second and most interesting method is working with bindings. A new class is used to define them: the ActivityBind.

ActivityBind activityBind = new ActivityBind();
activityBind.Name = "object2";
activityBind.Path = "Property2";
this.object1.SetBinding(Object1.Property1, activitybind1);

As you see, the ActivityBind object creates a link to the object2’s Property2 property. As we are using this reference, the object2 does not actually know it is relied on by another object. Pretty simple.

In the end, it’s actually enough to remember just this one thing: if property object1.Property1 is dependent of object2.Property2 when you assign or get the Property1 of object1, you are actually modifying and retrieving Property2 of object2. Just keep to it, and you’ll be just fine. To end, here’s a quick overview. See ya.

object1..................object2
= DependencyObject.......= Plain object
= Target.................= Source
- Property1..............- Property2
...- get...=============>...- get
...- set...=============>...- set


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.

Hey guys,

Just a quick post to wish you all a happy new year. May your resolutions be fulfilled! :-p I hope I’ll achieve mine.

Sorry for the long delay for the previous article. Correlation is a very tricky technology. It’s still very vague and such. I hope I explained it clearly. Other hickups for the delay were, well, the holidays and some strange wordpress problems… which still need to be fixed, actually. :p

Anyway, Happy 2008!

Correlation is one of the key concepts in Workflow Foundation to understand when developping workflows. Most of the time people are confused about what correlation exactly is. They can’t really describe it, they can’t really explain it. Unfortunately, when you do not fully grasp this concept, it can lead to some major confusion when developping advanced scenarios and custom activities.

So what is correlation? Correlation is the machanism created to map an inbound message for a specific instance (sent from an external source) to the specific handler within the activity. There are two levels here:

• specific instance
• specific handler within the activity

Each level has his own differentiater. The specific instance (known by the external souce in the outside world) is defined by the CorrelationParameter and the specific handler within the activity (note that a workflow is an activity too) by the CorrelationToken.

But how is this implemented? Well, let’s first recap the basic objective: we are trying to establish external communication. The Workflow Foundation achieves this by using interfaces as a “channel”. The implementation of such a “channel” interface is a service which is added to the workflow runtime. This is actually the heart of correlation. As there are many instances (in the outside world) the service can work on, Workflow Foundation needs to know with which instance it must work on. This is why we need to define the CorrelationParameter in our “channel” interface. This is how an interface for external communication can look like.

[ExternalDataExchange]
[CorrelationParameter("taskId")]
public interface ITaskService
{
  [CorrelationInitializer]
  void CreateTask(string taskId, string assignee, string text);
}


In this example we define a CorrelationParameter “taskId” that will help us differentiate tasks – the instances – in the outside world. This name will stand for the correlation paramater throughout the whole interface. So when you use this name in a member (eg. CreateTask) as a parameter, Workflow Foundation considers the parameter as a correlation parameter for that member. Note that a correlation parameter can be a guid, int or whatever.
You also see a CorrelationInitializer attribute in there, which decorates the CreateTask member. When calling a member with this attribute, Workflow Foundation will know that the correlation parameter is initialized with this member. It will then reset internal pointers.

Now that the channel is defined, you can use it within your activity. You can use the channel directly by querying the runtime for the correct service. Workflow Foundation however gives you another possibility to ease working with different instances and handlers for those instances WITHIN your activity. This is where Correlation Tokens come into play. A correlation token encapsulates the correlation parameter and a value, together as a correlation property. For our task example, we could create a correlation token named “taskToken” which encapsulates the correlation property of property parameter “taskId” with the value 25. In other words this correlation token will hold the reference to the task 25.
Workflow Foundation also provides two activities that use this correlation token: CallExternalMethodActivity and HandleExternalEventActivity. A common way to use these activities consists of overriding their methods when developping custom activities (most sharepoint activities are implemented this way). Another method is to use them directly by setting the correct service, member name and parameters. As you probably already figured out, the first activity is able to call external methods. The HandleExternalEventActivity, on the other hand, will wait and listen for a specified event (after which it can trigger methods). Both of those activities use the correlation token to determine which instance they have to work with. It, however, makes most sense with the HandleExternalEventActivity, as an event cannot handle parameters, while the method called from a CallExternalMethodActivity specifies which instance to work on by one of the parameters.
To resume, here is a little schema of how to look at correlation tokens:

I hope this article helped you guys understand correlation a bit more. Untill next time..

This week I am starting a new series of articles to give you guys more insight in the Windows Workflow Foundation framework. The Windows Workflow Foundation (WF) is a framework which was released last year as part of the .NET Framework 3.0 alongside the Windows Presentation Foundation (WPF) and the Windows Communication Foundation (WCF). It allows you to model workflows: flows of logical (and easy-to-understand) work units. Here’s a basic example.

The units are represented by blocks, so-called “activities”, you can use by dragging them on your workflow designer. And right there, you get the main advantage of workflows. This methodology of creating a process by assembling logic building blocks together is pretty powerful. Especially when you envision a developer sitting down next to a business guy and interactively building the workflow together with him in just a couple of hours. And this without loosing track of the objective as they are working with small logical blocks.
For example, you can use a Send Email activity without having to know how it is actually sent or which methods you have to use. You just fill in a couple of properties and off you go. The big hick-up, unfortunately, is that there aren’t many blocks to choose from. So, we have to create them ourselves. And this is where the frustration begins. Most of the time the business has these complex rules set up and wants them translated to workflow technology. Creating all of these abstractions of the inner workings to the actual logic they’re producing, can be quite hard and sometimes just plain impossible. Why? Well, we have this framework we have to work around, which has very specific rules and complex, new logic to get code to run. And I’m not yet talking about parallel execution of our blocks.

Another great advantage is its pluggable system of services. When we want to run a workflow, the Workflow Foundation can add services to extend its possibilities. One of the most interesting services already developed, is persistency. It gives us the possibility to have the workflow, its whole instance, being interrupted and saved on a data storage. This way, lengthy processes that are waiting on some user interaction can be cleared from main memory and brought back to execution only when needed!

All in all, Windows Workflow Foundation is quite a nice technology, which can be very powerful. Unfortunately, development is proofing to be quite challenging. This is why I decided to give this series a try to get things cleared up and help you guys with some hints and tips. Hope you’ll like the series. Stay tuned!

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.

The ASP.NET page life cycle, control or web part life cycle for that matter, is an important concept to know and to understand in ASP.NET web development. ASP.NET, the successor of ASP, introduced the concept of object oriented development. The complete page and its controls are now objects which behave in a child-parent relationship and go through a complete life cycle of their state. It’s pretty crucial to know what stages they go through and which events are called as the web is a stateless medium and we are trying to make a statefull environment out of it.

The key concept is the view state. This is an object, stored within the page, which enholds the states of all current objects. It is loaded, processed and saved during the life cycle. More specifically, it will load all data into the controls right before entering the load event. From this event on, you’ll have controls which are loaded with all previous data. You can manipulate those just until the PreRenderComplete event. Once this event has passed, the viewstate will once again be saved into a hidden control on the page. So things you change during the render event will not be taken into account.

Here is a graphical overview:

Couple of remarks with this diagram:

• The dark gray events are only available for the page object.
• The green area indicates events where the viewstate is loaded and avilable in the controls. Once changed the controls will be saved back to the viewstate.

As I said, the viewstate is a pretty important concept to grasp. So, please take time to fully understand it. It’s crucial to know when and where you can interact with it or you’ll be in a whole world of pain when creating interactive web parts or pages. Untill next time, take care!

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!