Why do you need mappings
First things first: let me explain, why do you need to use mappings at all.
With some accuracy it can be said, that a Choice field in SharePoint represents a DropDownList control. And in the ASP.Net DropDownList control, each item (ListItem, to be precise) has two essential properties: Text and Value. Obviously, Value property acts as an identifier for the corresponding Text property.
This is very convenient, because you can use some display values, separated from actual values which you can bind to enums, or store somewhere, etc. Thus, if a customer wants to change how a certain item is displayed, developer is able to change the display value safely, nothing else in the code gets involved.
The purpose of mappings is absolutely the same, essentially they intend to bring analogue for the Value property to Choice fields.
Particularily, mappings are useful in multilanguage environments, to disengage from localized display values.
Hope it's clear now, and now let me show how you can deal with SharePoint Choice field mappings.
How to use mappings
Unfortunately, SharePoint is able to store only display values in the database, while mappings seem like a late attempt to add the missed Value property to Choice fields.
Even worse, while you can create and store mappings, there is no existing functionality for retrieving them, and honestly I can't imagine any reasons for that: the implementation doesn't seem to be complicated.
I think the following syntax for retrieving values from mappings could be quite convenient:
Guid fieldGuid = new Guid("put-your-field-guid-here");
SPListItem listItem = // get the list item from somewhere
var mappedValue = listItem.Fields[fieldGuid].GetMappedValue(listItem[fieldGuid]);
, there GetMappedValue method is a custom extension method.
This could be implemented using the following code:
public static class SPExtensions
{
public static string GetMappedValue(this SPFieldMultiChoice field, object value)
{
return GetValueFromMapping(field.Mappings, Convert.ToString(value));
}
internal static string GetValueFromMapping(string mappingsXml, string fieldMultiValue)
{
var result = String.Empty;
foreach (var value in fieldMultiValue.Split(new string[] { ";#" }, StringSplitOptions.RemoveEmptyEntries))
{
XDocument document = XDocument.Parse(mappingsXml);
var mapping = document.Element("MAPPINGS").Elements("MAPPING").FirstOrDefault(m => LocalizedEqual(m.Value, value));
if (mapping != null)
result += ";#" + mapping.Attribute("Value").Value;
}
return result.TrimStart(';', '#');
}
private static bool LocalizedEqual(string mappingValue, string value)
{
if (mappingValue.TrimStart().StartsWith("$"))
mappingValue = SPUtility.GetLocalizedString(mappingValue, "core", (uint)Thread.CurrentThread.CurrentUICulture.LCID);
return mappingValue.Equals(value);
}
}
GetValueFromMapping method is separated from the rest of the code for testing purposes.
The testing result:
So, as you could have noticed from the screenshot, "Completed" display value was successfully resolved to "3".
