RegistrationType & RegistrationId in SharePoint 2010 declarative Ribbon customizations

Back to the contents of the series.

Required Foreword
This post is a part of the upcoming series about SharePoint 2010 and related technologies. I'm an enthusiast of SharePoint platform (especially of 2010 version) and I like very much to explain things I know to others. These articles is my attempt to systematize my own knowledge of platform and to help others to understand it. I'd like to hear from you if there are any mistakes or things on the subject of the given article that are not covered. You can write your comments here or on my email - mail@alexboev.com.
I will update any article as my knowledge will improve. And sorry for my English - it's not quite good now but I'm learning. :) Fill free to point me on any mistakes.

RegistrationType and RegistrationId attributes of <CustomAction> element are being used in the declarative SharePoint 2010 user interface customizations when they target any list/library related Ribbon UI.
RegistrationType and RegistrationId attributes works in pair only. They form a combination where RegistrationType is a type of criterion for applying customization and RegistrationId is a value of this criterion to compare with content.

What is “content”?
What is “content” with respect to declarative SharePoint Ribbon customization? It’s a list/library or a single list item. Where does SharePoint assess that current declarative Ribbon customization is applicable to content? It does it on any page where there is at least one of the standard list view web parts (ListViewWebPart, DataViewWebPart etc.) or list item web parts (ListFormWebPart, DataFormWebpart etc.). It’s true for all standard (i.e. generated by SharePoint) list view forms and new/edit/display list item forms because they contain one of such web parts. It also works for any page where such web part is added manually.
For the list view web parts SharePoint analyzes the list itself and its content types but ignores items in this list. In case of single list item web part SharePoint analyzes the list, the content type of list item and a file if the list item is document library item.

Unsupported content
There are some types of content where SharePoint doesn’t apply any SharePoint Ribbon declarative customizations for some unknown reasons. One of such types is “Picture Library” (base list template 109). The picture library exception is hardcoded in SharePoint code. So you can apply your customization to image files in general document library by file extension (see the FileType section below) or by content type but you can’t apply customizations if image files stored in picture library.

RegistrationType
RegistrationType can have one of four hardcoded values – “List”, “ContentType”, “FileType” and “ProgId” with exact letter case. The applicability of these values depends on context – is current content list or library or a single list item or a single library item (i.e. item with file):

RegistrationType	List	List Item	Library	Library Item
List	+	+	+	+
ContentType	+	+	+	+
FileType				+
ProgId				+

RegistrationId
RegistrationId is a string which format depends on the chosen RegistrationType.

"List"
Despite the “List” name you can’t use this type of registration with list unique identifier, title, URL or any other list property. RegistrationId for the “List” RegistrationType must correspond to the base list template identifier of the list where customization should appear. This identifier is always an integer from the hardcoded range. So this type of registration allows limiting of declarative Ribbon customization to some class of lists but not to specific list instances.

What if you need to apply customization to a single list instance?
You can use other types of registration. For example you can create an unique content type for your list and apply customization to this content type (see the ContentType section below). Another way is to customize Ribbon programmatically.

While applying Ribbon customization on pages with standard list view webparts and list item web parts (see the “What is “Content” section above) SharePoint compares RegistrationId value in “List” registrations to a base value of Microsoft.SharePoint.SPListTemplateType enumeration member which is stored in Microsoft.SharePoint.SPList.BaseTemplate property of the list being assessed.

According to some information there is additional range of identifiers not included in SPListTemplateType enumeration. These identifiers don’t used in Ribbon customization for standard webparts and it’s unclear how and where they are used.

The most complete known list of base template identifiers including non standard (i.e. not included in SPListTemplateType enumeration) is listed here.
Here is an example of registration (please note that in current example and in following examples other required attributes of <CustomAction> element ommited for simplicity):

<CustomAction RegistrationType=”List” RegistrationId=”101”>

"ContentType"
RegistrationId for this type of registration must correspond to content type identifier of the content where customization is required. Content type identifier is a string of specific format and looks like «0x0100A33D9AD9805788419BDAAC2CCB37509F». While applying customization in the context of a single list item SharePoint gets this identifier from SPListItem.ContentTypeId property. In the list context Sharepoint gets it from the content type collection of current list (SPListItem.ContentTypes). The case is important. The value of RegistrationId must be equal to the whole target content type id or at least to the beginning of it. Content type identifiers have a recursive structure and always contain identifiers of all parents. So this type of registration is always applied not only to target content type itself but also to all its descendants.

In the list context the customization will appear if there is at least one content type covered by specified RegistrationId. Existing items in the list context are not analyzed – only content types of the list matter.

In the context of single list item the customization will appear only if the content type of current item is right.

Here is an example:

<CustomAction RegistrationType=”ContentType” RegistrationId=”0x0100A33D9AD9805788419BDAAC2CCB37509F”>

"FileType"
For this type of registration RegistrationId must be an extension of the file for current list item. Because a file of current list item is analyzed this type of registration available in the context of single library item (i.e. item with file) only. The case is ignored and the leading dot is not needed before extension:

<CustomAction RegistrationType=”FileType” RegistrationId=”docx”>

"ProgId"
For this type of registration RegistrationId must be an identifier of application where the content of the library item file created. SharePoint extracts this application identifier from list item file and saves in system field with name “HTML_x0020_File_x0020_Type”. So similar to FileType registration ProgId registration is available only in context of single library item. The case is not important.

Which files can be targeted? You can target files of XML or HTML based formats. An example of XML-based format is MS Word document saved as “Word XML-document”. It contains ProgId in the beginning of the body in the following tag:

<?mso-application progid="Word.Document"?>

An example of HTML-based format is MS Word document saved as “HTML-page” – the ProgId in this case will be saved in such tag:

<meta name=ProgId content=Word.Document>

You can test if SharePoint could extract ProgId from the given file by getting it from list item programmatically:

string ProgID = (string)listItem[SPBuiltInFieldId.HTML_x0020_File_x0020_Type];

or

string ProgID = (string)listItem[“HTML_x0020_File_x0020_Type”];

Then you can use obtained value in your customization:

<CustomAction RegistrationType=”ProgId” RegistrationId=”Word.Document”>

Back to the contents of the series.