Sunday, December 18, 2011

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):
RegistrationTypeListList ItemLibraryLibrary 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.

25 comments:

  1. Good summary of the options - thanks!

    ReplyDelete
  2. I'm glad to hear it's helpful - I've tried my best to research this subject. The best driver for my work are my readers. :) Share it!

    ReplyDelete
  3. Thanks for the information it makes altering the Ribbon a lot easier

    ReplyDelete
  4. Perfect, where did you read all this info in such transparent / understendable form / way ?
    Thank you

    ReplyDelete
    Replies
    1. I'm glad you like it. I didn't read it in such form anywhere (in general there are too much unclear topics in the SP world!) and it was the reason for me to do this little research and to write the most understandable, consistent and clear post as the result as I can. :)

      Delete
    2. Thanks Alex, I have learned alot from your blog!!!

      Delete
    3. @Akisha Anthony: Thanks, I'm glad you like it - this is my favorite post and it was hard to do the required research and to compose the results in such an understandable and systematic way. :)

      Delete
  5. Hi Alex, great post! I am having an issue with regisrationtype=contenttype and page library. It works perfectly on document libraries (edit/view forms), but not on publishing pages. Have you an encountered this behavior.

    ReplyDelete
    Replies
    1. Hi! Sorry but I hadn't any experience with such combination.

      Delete
  6. Hi Alex, is there any way that I can get the "RegistrationID" value from a SharePoint list? I have multiple environments and content type id changes in all these environments and I have to change the value in elements.xml everytime i have to deploy to different environment. I was thinking may be store the value in a SharePoint list and have this list in all the environments and i dont have to change the elements file. i am trying using javascript but the custom action is missing with this approach. Any suggestions?

    ReplyDelete
    Replies
    1. Hi Ricky!

      If I understand your question right, you are trying to target RegistrationId for some "external" value. Unfortunately, I think it isn't possible. If you are trying to target some specific content type and want it to have the same ID between several SharePoint instances you should deploy your content type with CAML because there you are able to configure specific predefined content type ID. Thus, you will be able to target the single content type ID across several Sharepoint environments.

      Delete
    2. Thanks Alex. The issue is that the content types are already deployed at the customer sites and i was trying to find an easier solution to update the custom actions for those content types.

      Delete
    3. In that case I can recommend programmatic customization instead of declarative one.

      Delete
  7. Can you please point me to some direction on how to achieve this programatically?

    ReplyDelete
    Replies
    1. Here's an example: http://msdn.microsoft.com/en-us/library/office/ff407578%28v=office.14%29.aspx

      Delete
  8. Hi

    I use this article to make code completion in the reSP ReSharper plugin
    http://docs.subpointsolutions.com/wp-content/uploads/2015/03/customaction_registrationtype.gif

    Thank you very much
    See more about reSP here http://www.subpointsolutions.com/resp/

    ReplyDelete
    Replies
    1. Hi! Excellent solution! I'm glad my favorite article had helped you to create such a useful tool!

      Delete
  9. I would like to add custom button on ribbon for Pages.

    for Ex: site/Pages/Forms/AllItems.aspx In this particular page area wants to add button.

    Can you please help me with custom Action for this?

    Thanks,
    Heena

    ReplyDelete
    Replies
    1. Hi i have same issue , did you manage to find it ?

      Delete

  10. Termite Control

    Lake delivers professional, reliable professional and home pest control services and products, garden and ornamental, and insect solutions in Central and North Lake Country Lakewood ranch, including Eustis, Fruitland Area, Leesburg, Support Etika, Sorrento, Tavares, The Locations, and Umatilla. Alternatively, numerous methods of biological control can be used which includes sterilisation programmes. Alert #1 Termite & Pest Control is The Local Pest Management Specialist. Always deal with a qualified and certified pest management company that is a member of national, condition or local pest administration associations. (11) A yard worker when applying a pesticide to the lawn or ornamental vegetation of your individual residential home owner using pesticides owned or operated and supplied by the individual residential property owner, supplied the yard worker will not advertise for or solicit pest control business and does not hold herself or him self out to the general public as being engaged in infestations control.شركة رش مبيدات بالقصيم
    شركة رش مبيدات بعنيزة
    شركة رش مبيدات بالرس


    After our initial inspection phase, we will customise an effective strategy from our arsenal of pest management solutions. A common day at work would involve turning up at a potential customers home or business to confirm what the problem is usually eg bedbugs, cockroaches, rodents, rats, wasps. A Advion Anava Bait Gel and MaxForce FC Ant Bait Serum are on a rather even keel with every single other. A brief set of pests we have effectively managed in the previous includes bed bugs, rats, ants, roaches, wasps, raccoons, skunks, and bats.شركة رش مبيدات ببريدة
    شركة رش مبيدات بتبوك
    شركة مكافحة حشرات ببريدة


    All Houston , Inc, a locally and family run pest control company, has become Protecting.. A snake-safe” program, this provides periphery coverage against intrusions from many of these reptiles. A internet marketing pest control business possesses the potential to provide you with you with a healthier income, but going the freelance route takes determination and marketing know-how. - A reputable pest control organization will always charge you a considerable sum of money but the investment is worth it.
    شركة مكافحه حشرات بالرس
    شركة مكافحة حشرات بالقصيم

    ReplyDelete
  11. In 샌즈 카지노 addition, many casinos issue free spins to rejoice the discharge of recent slots. In this situation, the casino will credit your account with free spins to play the slot on release day. No-deposit bonus codes are a few of the the} most sought-after promo codes among on-line gamblers. This is outcome of|as a end result of} they don’t require you to make any type of a monetary deposit to gain a bonus from them.

    ReplyDelete