Monday, May 23, 2011

RFO Ribbon Addin

I recently uploaded the initial release of the RFO Ribbon Addin (thanks to Martijn for all the ground work). You can download it here: http://revitforum.org/showthread.php/1793-RFO-Ribbon-Add-In-Downloads.

The following explains the folder structure and files associated with the addin and how to add new commands to it.

Folder Structure
The addin is structured such that the individual commands that appear on the ribbon are separate dll files (each separate command could be added to Revit as a stand alone addin with its own addin manifest file if you didn't want to use the RFO Ribbon Addin) this allows new commands to be added and commands to be updated easily without the need to recompile the core addin.

The root folder contains the following files:

FileDescription
Addins FolderContains "Vendor" subfolders.
RFO_Addins.xmlThis xml stores a list of all addins and whether or not they are "Enabled".
RibbonAddins.dllThis is the main app that creates the ribbon tab and loads individual addins.
Various ImagesThe thumbnails used on the ribbon.

RFO_Addins.xml
This file lists all available addins and whether each one is displayed on the ribbon not. The xml is divided into section by "Vendor". I use "Vendor" to represent individual contributers, I used the term "Vendor" as this matches what Autodesk uses in their addin manifest files.

The xml contains multiple "Vendor" tags which have a single attribute "Id". The "Id" attribute is equal to the "VendorId" attribute found in the Autodesk addin manifest files. You can obtain a Vendor Id from: http://www.autodesk.com/symbreg/startreg.htm. The "Id" attribute is used to identify each contributor and the folder containing their addins must have the same name as their "Id", additionally the xml file containing the information about their addins must also have the same name. For example; Contributor "ABCD" would have an xml file named "ABCD.xml" contianed within the "Addins/ABCD" subfolder.

Each "Vendor" tag contains one or more "Command" tags with two attributes; "Id" and "Enabled". The "Id" attribute is a GUID which is equal to the "AddInId" attribute found in the Autodesk addin manifest files. The "Id" must match the corresponding "Id" in the contributors xml file.The "Enabled" attribute tells the program whether or not to display this command on the ribbon, it can have a value of "True" or "False".

Individual Commands
Each command on the RFO Ribbon is loaded by a separate dll file and is located within a subfolder named after the contributors unique Id (or "VendorId"). For example; if a vendor with Id "ABCD" contributes a command "My Command" then the dll file would be located within a folder named "ABCD" within the "Addins" folder mentioned in the table above.

Each contributor also must provide an xml file named after their unique Id. The xml file also must reside in the subfolder named after their unique Id.

The xml file has one "Vendor" tag which has three attributes; "Id" is the contributors unique Id, "Name" is the name of the contributor and will appear on the ribbon panel containing their command(s), "Description" is a short description of the contributor and can contain contact information.

The "Vendor" tag contains one or more "Command" tags. Each "Command" tag has one attribute; "Id" is a GUID and should match the "Id" used in the main "RFO_Ribbon.xml" file.

Each "Command" tag contains seven tags describing the command:

  1. "Name" The name of the command, this name is not seen by the user but is used internally by Revit.
  2. "Assembly" The filename of the dll file associated with this command.
  3. "FullClassName" The fully qualified entry point to the command, usually this is the namespace and class name separated by periods.
  4. "Text" The text that appears on the command button.
  5. "Description" The basic tooltip for the command.
  6. "LongDescription" The extended tooltip that appears when hovering over the command for more than two seconds.
  7. "LargeImage" The thumbnail image that appears on the command button. This should be 32x32 pixels.


Add New Command
To add a new command is a two step process:

  1. Extract/copy the command files (including the contributor's xml file) into a subfolder of RFO Ribbon's "Addin" folder", the subfolder should have the same name as the contributor's Id.
  2. Update the RFO_Ribbon.xml to include the new "Vendor" tag and "Command" tags.


A future release of the ribbon app will automate the process of adding a new command.

No comments:

Post a Comment