Using resources in SharePoint projects and CAML files

This article is an excerpt from my book “Building the SharePoint User Experience”. If you like to get more excerpts like this you can, just check out this post on the SharePoint book blog.

While not strictly a feature-specific technology, resources are very useful for creating dynamic user experiences using features. You may already have seen resources in action, whenever you happen upon a string that looks like $Resources:wss,fldedit_changesitecolumn you see how resources can be used.

What are SharePoint Resources?

Resources are just XML files that contain a key and value mapping, just like a hashtable. As the XML files are separate from the feature or solution you can change the resource file and thus change which values the keys represent. Very useful for creating language packs or any other scenario where you want to have dynamic values.

There are two types of resources; run-time resources, which are just normal ASP.net resources, and provisioning resources, used in CAML when provisioning sites, pages, lists, and anything else you would provision outside of ASP.net. Resource management in ASP.net is outside the scope of this book, but I would like to explain at least the basics of provisioning resources.

To make sure anyone who does not read all the text will be utterly confused I will from here on refer to provisioning resources only as resources.

Resources, despite being seldomly used, are actually quite simple. The format of a resource file is just very simple XML. You have a data element with a name attribute and a child value element. In addition you can have a child comment element to ease understanding. All this is stored in a root element, conveniently named root. Here is a simple resource file:



MyValue

Note As resource files are very well explained in various ASP.net books and documentation I will skip explaining all the various authoring steps.

Features can use such files by referencing the resource file and the key directly in the feature CAML code. Remember that $Resources:wss,fldedit_changesitecolumn string we looked at earlier? This string reference has three parts. $Resources states that we will be using a resource reference rather than a regular string. wss is the first part of the resource file name, such as wss in wss.resx. fldedit_changesitecolumn is the key name to use.

If you have defined a default resource file you need not include the file name part of the resource reference, so you can just use $Resources:keyname in your CAML file.

Placing resources is also important. You can place resources either in the feature itself or in the [12]\Resources folder. If you place your resources in the feature folder, as we will do in a short exercise in a moment, name the resource file Resources.resx and set the DefaultResourceFile to _Res to be able to omit the file name part of the resource name.

The true beauty of resources is perhaps in the automatic handling of multiple language localizations. By adding .resx files with the culture between the filename and .resx SharePoint will automatically use the localized version of the resource file. For instance if you want to have localized strings for US English and the two Norwegian languages Bokmål and Nynorsk you could add the following resource files to your feature:

File name Culture Description
Resources.resx None/default Default file used if no culture defined
Resources.en-US.resx en-US US English
Resources.nb-no.resx nb-no Norwegian Bokmål
Resources.nn-no.resx nn-no Norwegian Nynorsk

Note Yeah, Norway has two languages. Actually, we have four. That is almost one language per person. In addition everyone learns at least two foreign languages and understands every Scandinavian language. Chances are, if you are in Norway and speak your native tongue, people will understand.

Creating your first SharePoint resource file

To test all this, follow this procedure:

  1. Create a blank feature, as explained in the first section of this chapter.
  2. In your MyFeature folder, create a folder called Resources, and in that folder create a new XML file called Resources.resx.
  3. Open your Resource.resx in Visual Studio or your favorite developer tool and add two keys and values:
  4. Key Value
    featuredescription Description from resource
    featuretitle Title from resource

    UXi0301

  5. In your feature.xml file, modify the Description attribute to $Resources:featuredescription; and your Title attribute to $Resources:featuretitle;. Modify your DefaultResourceFile attribute to _Res. Your feature element should now look like this:
  6. Build and deploy your feature. If you followed the recipe in the beginning of this chapter, this should be as easy as hitting Build in Visual Studio.
  7. Verify in Site features of a site that your feature now retrieves its title and description from the resource file.

    UXi0302

Using resources to provision your string is highly recommended. Besides allowing easy localization of text you can also very easily upgrade resource files and update names and values without modifying the CAML files. The extra overhead of creating resource files repays itself after the first upgrade of your solution.

Strong buy!

Tip Never take stock tips from me.

This article is an excerpt from my book “Building the SharePoint User Experience”. If you like to get more excerpts like this you can, just check out this post on the SharePoint book blog.

.b

Found this article valuable? Want to show your appreciation? Here are some options:

a) Click on the banners anywhere on the site to visit my blog's sponsors. They are all hand-picked and are selected based on providing great products and services to the SharePoint community.

b) Donate Bitcoins! I love Bitcoins, and you can donate if you'd like by clicking the button below.

c) Spread the word! Below, you should find links to sharing this article on your favorite social media sites. I'm an attention junkie, so sharing is caring in my book!

Pin It

Published by

Bjørn Furuknap

I previously did SharePoint. These days, I try new things to see where I can find the passion. If you have great ideas, cool projects, or is in general an awesome person, get in touch and we might find out together.

Leave a Reply

Your email address will not be published.