Archive

Posts Tagged ‘Ribbon’

SharePoint 2010 : White Page when clicking buttons on the ribbon.

November 17, 2009 Leave a comment

If you are getting white pages when clicking on buttons on the Ribbons you should add your SharePoint 2010 site to your trusted sites. It has to do with certain javascript functions that cannot be called which gives that effect (happens mostly if you are testing it on a server)

Advertisements
Categories: Ribbon Tags:

HOWTO: Add a button to the ribbon in SharePoint 2010

November 5, 2009 7 comments

This post is intended for BETA1. It will work on BETA2 as well, just remove the … for

After a few hours of messing around in XML, we (Jopx and I) figured out how to put a button on the Ribbon. First of all, how does it work? There is some XML (located in the 14 hive/templates/global/xml) in a file called CMDGui.XML. This contains the entire Ribbon XML that is used to render the ribbon. To get that XML into a Ribbon, there are two javascript files that translate that data into a workeable ribbon (CUI.js and SP.Ribbon.js). What do we need to do to create our custom button? It’s quite simple, you just create some XML, push it to the SharePoint environment by making use of an empty element, add some stuff to the templates/xml folder and you’re set. That is once you figured it all out 🙂

First of all, create a new Empty SharePoint project in Visual Studio. (no screenshots after this as my laptop here can’t run SP2010)

image

  • Rename your project to MyCoolButton
  • Add an empty Element.
  • In that element, paste the following xml:
<?xml version="1.0" encoding="utf-8" ?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
  <CustomAction Id="MeSoCool" Location="CommandUI.Ribbon.Documents.New.Controls._children">
    <CommandUIExtension>
      <CommandUIDefinitions>
        <CommandUIDefinition Location="CommandUI.Ribbon.Documents.New.Controls._children">
          <Button Id="Ribbon.Documents.New.Controls.MyCoolButton"
                  Image16by16="/_layouts/images/edit.gif"
                  Image32by32="/_layouts/images/placeholder32x32.png"
                  Description="MyDescription"
                  Command="MyCoolButton"
                  LabelText="Banzai"
                  Sequence="60"
                  TemplateAlias="o1" />
        </CommandUIDefinition>
      </CommandUIDefinitions>
    </CommandUIExtension>
  </CustomAction>
</Elements>

What does all this XML mean?

First of all we will be adding a CustomAction, and the most important attribute there is the Location. This location attribute will define where the button is going to appear. Notice that the same attribute is also defined in the CustomUIDefinition which is the location where it will need to be defined in Beta2. So in Beta1 apply the Location to the CustomAction, in Beta2 only apply the location to the CommandUIDefinition. Notice the _children in the end, you need to add it to be able to add buttons to that Control collection.

Where does this location come from? In the CMDGui.XML file that location is defined in a group. This group is part of a group collection called Ribbon.Documents.Groups which is part of the Tab called Ribbon.Documents.  This tab is the ribbon we will see when we are working with documents. Important to notice is the Template the group is using. If the Template used is Ribbon.Templates.Flexible2 you can add buttons to that group. If it isn’t a flexible template (like Ribbon.Templates.ThreeRowsSixAlignedControls2) then you can’t add buttons as those are fixed templates. As an example I added the xml for the Ribbon.Documents.New group.

<Group
            Id="Ribbon.Documents.New"
            Sequence="10"
            Command="DocumentNewGroup"
            Description=""
            Title="$Resources:core,cui_GrpNew;"
            Image32by32Popup="/_layouts/images/placeholder32x32.png"
            Template="Ribbon.Templates.Flexible2"
          >

 

Ok, on to the next item in our XML, the CommandUIExtensions. They contain the CommandUIDefinitions who are defining the element that you are showing (a Button in our case). The name of the second element escapes me and I can’t check SP2010 at the moment, but the other element within the CommandUIExtensions defines the action of the button (what happens if you click on it) Our little post is only focused on making it appear. Now back to our Button Control.

<Button Id="Ribbon.Documents.New.Controls.MyCoolButton
             Image16by16="/_layouts/images/edit.gif"

             Image32by32="/_layouts/images/placeholder32x32.png"

             Description="MyDescription"

             Command="MyCoolButton"

             LabelText="Banzai"

             Sequence="60"

            TemplateAlias="o1" />

The Id needs to start with Ribbon.Documents.New.Controls. After that you can put whatever you want. The image attributes are used and the images are shown depending on what is defined in the GroupTemplates. What does that mean? In the GroupTemplates (also defined in the CMDGui.xml) it is defined how a button in the ribbon should behave when the page gets resized. Should it hide itself, should it change it’s template (for instance instead of 3 large buttons next to eachother 3 small buttons above eachother)That way we can control how our Ribbon is behaving when the page gets resized. Description is quite easy to understand what it does, Command links to the command that you can define afterwards (you can deploy without having implemented the command), the LabelText is used in the template and shown on the ribbon, the Sequence defines where the button needs to be places and the TemplateAlias links to the template that you are using for that button.

Ok, now that we have that XML we just need to do one more thing:

Add a SharePoint mapped folder to your project and link it to the templates/xml folder. It should automatically create a MyCoolButton folder under the XML folder, but if it doesn’t make sure you do. Add an xml file to it callee MyCoolButton.xml. In that file we will define our link to the javascript files.

<script OnDemandKey="ribbon">
  <File></File>
  <File>SP.Ribbon.js</File>
</script>


Now we are set to go. Rightclick your project, select deploy. Go to a document library, on the ribbon select Documents and you should see a new button next to the New Folder button. (More images will follow as soon as I get home, but we were so excited when it finally worked that I at least had to put it online, but I’m sure Joris will do the same very soon 🙂 )

Should I have missed something, let me know, but this should do the trick for you 🙂

Categories: 2010, Development, Ribbon Tags: