How to add to ribbon

Adding the function callbacks

To be able to add a tab to the ribbon you need to have a callback to the Site Manager framework that adds your tab. In this case, we will need three callbacks, one for each component of the ribbon (ribbon tab page, ribbon category and ribbon category items). 

Open your PluginOperations.cs class and see if the following functions exist. If not then add them to your PluginOperations class:

internal static void AddRibbonPages(object sender, RibbonPageArguments args) {}
internal static void AddRibbonPageCategories(object sender, RibbonPageCategoryArguments args) {}
internal static void AddRibbonPageCategoryItems(object sender, RibbonPageCategoryItemArguments args) {}

Now open your class that implements the IPlugin interface (usually called PluginEntry), and in the Init function, add the following code, if it does not already exist:

frameworkCallbacks.AddRibbonPageConstructionHandler(
			new RibbonPageEventHandler(PluginOperations.AddRibbonPages));
frameworkCallbacks.AddRibbonPageCategoryConstructionHandler(
			new RibbonPageCategoryEventHandler(PluginOperations.AddRibbonPageCategories));
frameworkCallbacks.AddRibbonPageCategoryItemConstructionHandler(
			new RibbonPageCategoryItemEventHandler(PluginOperations.AddRibbonPageCategoryItems));

Create the text to be used on the ribbon

When we add a tab, a tab category and a category item we need to create resourced strings to display on the tab page, category and category item. For example, if we want to add a Customers category to the Customers tab page that contains a New customer category item inside the category, we need to add three resourced strings called Customers, NewCustomer and NewCustomerDescription. The first one will be used for the tab page category, the second one for the category item and the last one for the tooltip that appears for the category item.

Open the Resources.resx file for your plugin project.

In here we will add a resourced string called Customers which contains the text “Customers”. Also, we will add another string called NewCustomer which contains the text “New”. Finally add a string called NewCustomerDescription that contains “Create a new customer”.

Finding the correct priority keys for the tab, category and category item

Tab pages, categories and category items in the Site Manager are displayed in a specific order which is controlled by a priority key. When adding a new tab, category or category item we must specify where we wish the Site Manager to put our new operation by giving the Site Manager the correct priority key value.

You can find all defined priority key values in the Site Manager in Priority keys. In our case we are interested in adding the Customers category item to the Customers category on the Customers tab page. In our case, we need to look at the priority keys for the Customers tab page (500) and the Customers (100) category values. We want our new tab page category Customers to be located at the beginning of the tab page so we need to choose a value that is lower than all other priority keys in this page. If for example, you want to place the category between two existing categories, you will need to choose a key that is between those two categories. The same procedure is applied for the category items.

Creating the ribbon tab

Navigate to the function AddRibbonPages in the PluginOperations.cs class. We add a statement that adds the Hello world tab page. We need to perform this step in case the Hello world tab page has not been created at the time that the Site Manager framework calls our function callbacks. Add the following code to the AddRibbonPages function to add the Hello world ribbon page:

internal static void AddRibbonPages(object sender, RibbonPageArguments args)
{
	args.Add(new Page(Properties.Resources.HelloWorldTab, "HelloWorld"), 1100);
}

Example of adding to an existing tab:

You will need to add the ribbon tab in your plugin even though it already exists in another plugin. For an example if you want to add a new operation to the Customer tab you will need to create the ribbon tab from your plugin

internal static void AddRibbonPages(object sender, RibbonPageArguments args)
{
	args.Add(new Page(Properties.Resources.Customer, "Customer"), 500);
}

Creating the ribbon category

To add our a category to the Hello world tab page, we need to add code to the AddRibbonPageCategories function to add our category.

The final code for the AddRibbonPageCategories looks like this:

internal static void AddRibbonPageCategories(object sender, RibbonPageCategoryArguments args)
{
	if (args.PageKey == "HelloWorld")
	{
		args.Add(new PageCategory(Properties.Resources.HelloWorld, "Customers"), 100);
	}
}

Now we can go through the code step by step. First we add an if-statement that checks for the tab page that the category belongs to. Optionally we can check if the user has some permission required to view the category, then we add the page category to the tab.

If you run the Site Manager at this stage we will not see our new category appear since it does not have any category items yet, but after the next step we will see all of the previous steps come together.

Adding a category item to a ribbon category

Now we are ready to add a "Hello World" category item to the Hello world ribbon category. Navigate to the function AddRibbonPageCategoryItems (see previous section Creating a ribbon category)

1. Before an category item can be added, we need to have a function to perform our operation when the user clicks the category item in the Site Manager. In the Hello World plugin functions for opening each of the included views already exists in the PluginOperation.cs:

   public static void ShowHelloWorldView(object sender, EventArgs args)
   {
   	PluginEntry.Framework.ViewController.Add(new Views.HelloWorldView());
   }

   Another example would be calling an operation to create a new Customer:

   public static void NewCustomer(object sender, EventArgs args)
   {
   	NewCustomer();
   }

 

In the AddRibbonPageCategory item we first add a check to make sure that we are adding to the correct tab page and category:

if (args.PageKey == "HelloWorld" && args.CategoryKey == "HelloWorldCategory")
{
					
}

Then we add a check to see if the user has permission to view the category item we are about to add:

if (PluginEntry.DataModel.HasPermission(Permission.xxx))
{
				
}

Now we can finally add the category item for Hello world:

 args.Add(new CategoryItem(
	Properties.Resources.HelloWorldView,
	Properties.Resources.HelloWorldTooltipTitle,
	Properties.Resources.HelloWorldTooltipText,
	CategoryItem.CategoryItemFlags.Button,
	null,
	Properties.Resources.HelloWorldIcon32,
	new EventHandler(ShowSimpleView),
	"HelloWorldView"), 10);

If we look at the constructor for CategoryItem and examine each parameter the constructor has a few overloads, but in this instance we have the following parameters:

• The description on the category item which is displayed to the user
• The title text on the tooltip that is displayed to the user
• The description text on the tooltip
• The type of CategoryItem we are adding, look at the CategoryItemFlags enum to see what kind of items are available. In this instance we want a button.
• Small image, set as null because we will use a large image on the next parameter
• Large image
• An event handler pointing to the function we want to run when the user presses the category item.
• The key for this item, this works like the key for the tab page and the tab category.
• Priority key

Now when you start the Site Manager and select the Customers tab on the ribbon, you should see the Customers category, New Customer category item and the Tooltip for the Category item if you hover over it.

Category item types

The CategoryItem class allows multiple types of items to be added to the ribbon:

• Item with text
• Item with text and event handler
• Item with text and tooltip
• Item with text, tooltip and event handler
• Item with text and small image
• Item with text and large image
• Item with text, tooltip, small image and event handler
• Item with text, tooltip, large image and event handler

Each CategoryItem constructor contains a parameter of type CategoryItemFlags which specifies the behaviour of the item, for example Button or DropDown.

Adding items to a dropdown category item

To add items to a dropdown category item, first you need to open your class that implements the IPlugin interface (usually called PluginEntry), and in the Init function, add the following code, if it does not already exist:

frameworkCallbacks.AddMenuConstructionConstructionHandler(ConstructMenus);

Then we need to need to implement a method that will add items to our dropdown, in our case the ConstructMenus function:

private void ConstructMenus(object sender, MenuConstructionArguments args)
{
	if(args.Key == "RibbonBarCodes")
	{
		if(PluginEntry.DataModel.HasPermission(Permission.ManageBarcodeSetup))
		{
			args.AddMenu(new ExtendedMenuItem(Properties.Resources.BarCodeSetup, 10, 
				new EventHandler(PluginOperations.ShowBarCodeSetup)));
		}

		if(PluginEntry.DataModel.HasPermission(Permission.ManageBarcodesMasks))
		{
			args.AddMenu(new ExtendedMenuItem(Properties.Resources.BarCodeMaskSetup, 20, 
				new EventHandler(PluginOperations.ShowBarCodeMaskSetup)));
		}
	}
}

In this example, we are checking if the item key belongs to the desired item, then we add items to the dropdown, if the user has the necessary permission.