Access SharePoint ribbon controls in JavaScript.
Ribbon Designer events

Ribbon Designer
for Microsoft® SharePoint® and Office 365

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

Ribbon Designer programmability

Localization

The Ribbon Designer supports localization by providing the Language and Localizable properties: click the designer surface and look at the Properties window. See also Localizing SharePoint solutions.

Accessing ribbon controls in JavaScript

If you have a text box with its ID set to "AdxspRibbonTextBox1", then you can write the code below in the OnClick event of a Ribbon button:


			SPRibbonProject.SPRibbon.prototype.AdxspRibbonButton2OnClick_EventHandler = 
			    function (sender) {
				var textBox = this.FindControl("AdxspRibbonTextBox1");
				var isOk = false;
				if (textBox != null) {
					var text = textBox.Text;
					if (text != null && text != "") {
						isOk = true;
						alert(text);
					}
				}
				if (!isOk) alert("Something went wrong or no text was supplied");
				sender.AllowPostBack = false;
			}
			

That is, in the event handler above, you find the text box using the FindControl method; it accepts the ID of a control to find. Then the text is extracted and an alert is shown.

When testing the method above, you'll find that FindControl() returns the previous value of the text box unless you press {Enter} when entering text. Alas, this is how the Ribbon text box works and you can do nothing about this.

Creating ribbon controls dynamically

For Ribbon controls containing a menu (e.g. ADXSPRibbonSplitButton), you use the property PopulateDynamically to populate the menu dynamically. Setting this property to True generats the OnMenuCreate event on the corresponding JavaScript object. You handle this event to create Ribbon controls on the client side.

Creating Ribbon controls on the client side

In the screenshot above, the split button is created at design time as described in Creating a custom SharePoint ribbon tab. The controls residing on the menu part of the split button are created with this code:

			
			SPRibbonProject.SPRibbon.prototype.CreateMenu = function (sender) {
				// Section 1
				var menuSection = sender.AddMenuSection("MySection1ID");
				menuSection.Caption = "Section 1 Caption";
			//    menuSection.DisplayMode = "Image16AndCaption";

				// Button 1
				var button = menuSection.AddControl("MyButton1ID", "Button");
				button.Description = "My Button 1 Description.";
				button.Caption = "My Button 1 Caption";
			//    button.Alt = "My Button 1 Alt.";
			//    button.Enabled = true;
			//    button.ToolTipTitle = "My Button 1 Tooltip Title";
			//    button.ToolTipDescription = "My Button 1 Tooltip Description";
			//    button.ToolTipHelpKeyWord = "My Button 1";
			//    button.ToolTipShortcutKey = "Ctrl+Shift+Z";
				button.OnClickEventName = "ShowId";

				var popup = menuSection.AddControl("MyPopup1ID", "FlyoutAnchor");
				popup.PopulateDynamically = false;
				popup.Caption = "My Popup 1 Caption";
			//    popup.OnMenuCreateEventName = "OnPopulate_DynamicHandler";

				var menuSection2 = popup.AddMenuSection("MySection2ID ");
				menuSection2.Caption = "Section 2 Caption";

				var button2 = menuSection2.AddControl("MyButton2ID", "Button");
				button2.Description = "My Button 2 Description.";
				button2.Caption = "My Button 2 Caption";
				button2.Alt = "My Button 2 Alt";
				button2.OnClickEventName = "ShowId";
			}

			SPRibbonProject.SPRibbon.prototype.ShowId = function (sender) {
				alert(sender.getId());
			}
			

Preserving the state of ribbon controls

All components representing Ribbon controls allow retaining the controls' state. Both ADXSPRibbon and ADXSPPageRibbon classes have the AutoSaveMode property that you can set to Local, Session (default) or None. All Ribbon components provide the AutoSaveState property accepting True (default) or False. You can specify whether to preserve the state of a given Ribbon control at runtime: just set the AutoSave property to False in the JavaScript event OnBeforeSaveState that every Ribbon component provides.

Ribbon Designer events

The ADXSPRibbon class provides events listed below.

Event name

Event description

OnAction

Occurs when the designer class is invoked via the Submit method of the Ribbon Designer client object model. Allows handling custom actions and passing data to them. A sample of use is given in Client-side events. Not supported in sandboxed solutions.

OnBeforeRibbonLoad

Occurs before the Ribbon XML is supplied to the Server Ribbon. Allows customizing the Ribbon XML at run-time. Not supported in sandboxed solutions.

OnBeforeScriptLoad

Occurs before the Ribbon Designer client library is registered for the Server Ribbon. Allows customizing the Ribbon Designer script at run-time. Not supported in sandboxed solutions.

OnDeploymentAction

Occurs when the designer feature is installed, uninstalled, activated, deactivated, or upgraded.

OnInitialize

JavaScript. Occurs when the Ribbon Designer client library is loaded by the browser. You can use this event to initialize the state of Ribbon controls. A sample of use is given in Server-side events.

OnLoad

Occurs when the Ribbon Designer is loaded into the Page object. Not supported in sandboxed solutions.

OnRibbonReady

JavaScript. Occurs when the ribbon control is constructed. You can use this event to activate a Ribbon tab (SelectTabById) or check if a tab is available (IsTabAvailable).

OnScriptLoaded

JavaScript. Occurs when the Ribbon Designer script is loaded into the Page. You can use this event to perform actions depending on whether your script is loaded.

OnSubmit

JavaScript. Occurs when the FORM is about to be submitted.

Ribbon controls in detail <<

>> Dealing with built-in ribbon controls