Creating custom ribbon contextual groups
for SharePoint 2010 and SharePoint 2013

Ribbon Designer
for Microsoft® SharePoint® and and Office 365

Add-in Express Home > Ribbon Designer for SharePoint and Office 365 > Online Guide > Ribbon controls in detail

Ribbon controls in detail

Creating and showing ribbon contextual groups

In the Add-in Express toolbox (see Ribbon Designer basics), click the corresponding tool button to add an ADXSPRibbonContextualGroup component onto the designer surface.

Adding an ADXSPRibbonContextualGroup component onto the designer surface

You bind a Ribbon tab to a given contextual group using the tab's Context property as shown in the screenshot.

Binding a Ribbon tab to a given contextual group

To bind a contextual group to your Visual Web Part, you modify the CreateChildControls method so that it calls the ShowContextualGroup method. This is a static (Shared in VB.NET) method. We demonstrate how to use it in the code below: 


			Protected Overrides Sub CreateChildControls()
				Dim control As Control = Page.LoadControl(_ascxPath)
				Controls.Add(control)
				SPRibbon.ShowContextualGroup(Me.Page, GetType(SPRibbonProject.SPRibbon), _
					"AdxspRibbonContextualGroup1")
			End Sub

In the code above, the ShowContextualGroup method specifies that the contextual group with the ID equal to "AdxspRibbonContextualGroup1" is shown for the web part.

Ribbon control visibility rules

For a custom Ribbon control to be visible on a page, all the conditions below must be met:

  • The Visible property of the control is true and the ItemType and Ribbons properties of the control correspond to the current context.
  • If the direct parent of the control is a built-in control (see Dealing with built-in Ribbon controls), the control's DisplayModeMsp property must be set to a valid value (see How your control is displayed).
  • All container controls (including the group and tab controls) in the hierarchy of which the control is located are visible; in other words, the visibility and context matching requirement above apply to the container controls, too.
  • If the ribbon tab to which the control belongs is bound to a contextual group (see Creating and showing ribbon contextual groups), then the group must be visible, too; if the group is bound to a web part, then the web part must be added to the current page.

How your control is displayed

For a custom control located on a custom container control (such as custom group), you use the DisplayMode property. Say, for a custom Ribbon button, you set the DisplayMode property to one of the following values:

  • Image16Only - a 16x16 image (.PNG, .ICO or .BMP)
  • Image16AndCaption - a 16x16 image (.PNG, .ICO or .BMP) plus caption
  • Image32AndCaption - a 32x32 image (.PNG, .ICO or .BMP) plus caption

Using any of these values implies that you also specify an image using the Image and ImageList properties.

If, however, the custom control is located on a built-in container control, you must set the DisplayModeMsp property of the custom control; the property editor suggests values appropriate for the built-in container. If you don't set a value to this property, your custom control located on a built-in container control will not show up, pay attention to Ribbon control visibility rules and Dealing with built-in Ribbon controls.

Creating a custom SharePoint ribbon tab <<

>> Ribbon Designer programmability
See Also