Managing Custom Ribbon Tab and Buttons

Button icon requirements

A command button icon should meet the following requirements:

• Type: SVG or PNG

• Size: 32x32 pixels

SVG is recommended because PNG is automatically converted into SVG on command button creation, and the results of automatic conversion may differ from what you expect.

Images smaller or larger than the recommended size are automatically scaled up or down. Scaled icons, especially converted from PNG files, may be distorted or may not have the desired level or clarity of details.

Button script requirements

A command button script should be valid and self-sufficient.

The button script should be a .js file with JS code valid for execution in the JS runtime environment. The application verifies the file on uploading and raises an error message in the Custom Ribbon Configuration Editor pop-up dialog box if the code is invalid. In such a case, you should investigate the file in the IDE against bugs, errors, and warnings and correct the issues. For example, global await expression statements are valid in the console but invalid in the runtime environment, where they should be embedded in async functions.

If the code is valid, the Script field of the Custom Ribbon Configuration Editor dialog displays the name of the .js file. Also, a message with your script signature appears under the field. And, the Edit button becomes active in the field.

Clicking the Edit button in the Script field shows the Text Editor pop-up dialog box with the script code. You can review and edit the code if necessary.

The button script should also contain everything it needs because it runs in the JS evaluation context. If the script has external dependencies or should download external resources, such as images, multimedia, 3D models, and so on, it should be able to access these external dependencies and resources via URL. They can be stored in a dedicated folder, like assets, on the server running the application. If they are on a remote location or service, the script should have access to that location or service.

Accessing the Custom Ribbon Configuration Editor dialog

To show the Custom Ribbon Configuration Editor pop-up dialog box:

UI of the Custom Ribbon Configuration Editor dialog

The Custom Ribbon Configuration Editor pop-up dialog box includes UI elements for managing the custom ribbon tab and a given custom command button.

UI for custom command buttons

For the custom command button currently selected from the Commands list, the Custom Ribbon Configuration Editor pop-up dialog box features the following:

• Buttons to reposition the given command button on the ribbon tab.

• Fields to set, view, and edit the properties of the given command button.

• A toolbar to manage the given command button and its properties.

Buttons for moving custom command buttons

Below the Commands list, there are the following buttons to reposition the selected custom command button:

Move Up

To move the given command button to the left on the custom ribbon tab and up on the list. It is inactive for the first button on the list.

Move Down

To move the given command button to the right on the custom ribbon tab and down on the list. It is inactive for the last button on the list.

Custom command button fields

On the right side of the Custom Ribbon Configuration Editor dialog, there are the fields that represent the properties of the custom command button currently selected from the Commands list. These fields are the following:

ID

A string, the unique identifier of the given command button.

Label

A string, the name of the given command button displayed on the ribbon tab.

Icon

An .svg or .png file, the icon of the given command button displayed on the ribbon tab.

Script

A .js file, the JS code executed by clicking the given command button.

Tooltip

A string, the text displayed when hovering over the given command button on the ribbon tab.

Visible

A drop-down list of mutually exclusive options where the given command button should be visible on the ribbon tab:

• 2D: only in the document page editor. It is the default value.

• 3D: only in the 3D editor.

Enable

A drop-down list of mutually exclusive options when the given command button should be active on the ribbon tab:

• Always: regardless of how many objects or parts are selected. It is the default value.

• No selection: when no objects or parts are selected.

• Single selection: when one object or part is selected.

• Multi selection: when more than one object or part is selected.

• Any selection: when one or more objects or parts are selected.

On opening the Custom Ribbon Configuration Editor dialog, these fields are blank because no command button is selected from the Commands list by default. When you select a custom command button from the list, the fields display the properties of this button but are inactive by default.

Toolbar for managing custom command buttons

To edit the properties of the selected command button, manage this command button, and create new command buttons, there is a toolbar above the fields.

The toolbar includes the following buttons:

Edit

To enter editing the properties of a selected command button.

The Edit button becomes:

• Active when you have selected a command button from the Commands list.

• Inactive when either:

  • You are creating a new command button.

  • No existing command button is selected from the list.

On clicking this button:

• The Reset button replaces it on the toolbar.

• The Move Up, Move Down, Preview, Save, Add, and Delete buttons become inactive.

• The Commands list becomes inactive.

• The fields become editable.

  

Reset

To quit editing the properties of a selected command button without saving the changes to these properties.

This button replaces the Edit button and is active when you are editing an existing command button.

On clicking this button:

• The Edit button replaces it on the toolbar.

• The Move Up, Move Down, Preview, Add, and Delete buttons become active.

• The Confirm button becomes inactive if it has been active after doing some changes.

• The Commands list becomes active.

• The given command button continues to be selected from the Commands list.

• The fields become inactive and display the values before editing. All your changes are lost.

Add

To start creating a new custom command button.

This button is inactive when you are editing an existing command button.

On clicking this button:

• The Dismiss button replaces it on the toolbar.

• The Commands list becomes inactive.

• No command button is selected from the Commands list.

• The Move Up, Move Down, Preview, Save, Edit, and Delete buttons become inactive.

• The string and file fields become editable and blank.

• The fields with drop-down lists display the default values.

  

Dismiss

To quit creating a new custom command button without saving it.

This button replaces the Add button and is active when you are creating a new command button.

On clicking this button:

• The Add button replaces it on the toolbar.

• No command button is selected from the Commands list.

• The Move Up, Move Down, Save, Edit, and Delete buttons continue to be inactive.

• The Confirm button becomes inactive if it has been active after populating all the fields.

• The Preview button becomes active.

• The fields become inactive and blank. All your input is lost.

Confirm

To prepare for saving to the staging custom ribbon tab configuration either:

• Your changes to the properties of a selected existing command button when editing them.

• A new command button that you have created.

For details on the staging configuration of the custom ribbon tab, see the Architecture and mechanism of the custom ribbon tab.

This button becomes active if you have either:

• Changed at least one value when editing the properties of a selected command button.

• Populated all the properties with valid values when creating a new command button.

  

This button becomes inactive if you have clicked it, the Reset, or Dismiss button.

On clicking this button:

• If editing an existing command button:

  • The Edit button replaces the Reset button.

  • Your changes to the custom command button properties are ready to be saved to the staging custom ribbon tab configuration in the database.

• If creating a new command button:

  • The Add button replaces the Dismiss button.

  • The newly created custom command button:

    • Appears at the bottom of the Commands list.

    • Is ready to be saved to the staging custom ribbon tab configuration in the database.

• The Commands list becomes active.

• No command button is selected from the Commands list.

• The fields become inactive and blank.

• The Move Up, Move Down, and Delete buttons continue to be inactive.

• The Deploy, Edit, and Confirm buttons become inactive.

• The Preview, Save, and Add buttons become active.

Delete

To either:

• Delete a newly created command button unsaved to the database.

• Prepare for deleting a command button existing in any configuration in the database from the staging custom ribbon tab configuration in the database. For details on the custom ribbon tab configurations, see the Architecture and mechanism of the custom ribbon tab.

This button becomes:

• Active when you have selected a command button from the Commands list.

• Inactive when either:

  • You have clicked it.

  • You are editing an existing command button.

  • You are creating a new command button.

  • No existing command button is selected from the list.

On clicking this button:

• The given command button is:

  • Removed from the Commands list.

  • Is ready to be deleted from the staging custom ribbon tab configuration in the database if it exists in any custom ribbon tab configuration.

• No command button is selected from the Commands list.

• The fields become blank.

• The Move Up, Move Down, Deploy, Edit, and Delete buttons become inactive.

• The Save button becomes active.

Custom ribbon tab architecture

Technically, the definition of the custom ribbon tab is a data object with key-value pairs in JSON format stored along with the user settings in the internal section of the application database on the backend. On loading the Canvas Envision Creator app into the browser:

• This data object is loaded into the custom_ribbon_configs table of the custom_ribbon database within the IndexedDB data on the front end.

• The app's front end renders the custom ribbon tab and buttons in the GUI from the data stored in the custom_ribbon_configs table.

Custom ribbon tab configurations

The custom_ribbon_configs table defines the configurations of the custom ribbon tab in the workspace. Each configuration represents an environment:

staging

The staging environment for software and QA engineers to develop and test custom command buttons.

deployed

The production environment for all application users to use custom command buttons.

Custom tab configurations on the ribbon

The ribbon displays each configuration (environment) in a dedicated tab within the workspace as follows:

• None: no custom tab is present on the ribbon.

• staging: a custom tab with a yellow tab label background visible not only to you but also to all Admins.

  

• deployed: a custom tab with a regular tab label background visible to all Admins and Creators.

  

• deployed and staging: two custom tabs with regular and yellow tab label backgrounds. Admins can see both tabs, while Creators can see only the deployed tab.

  

To be visible on the ribbon, the configuration should have at least one custom command button. The Visible property of the button defines where this button and the tab will be visible: in the 2D page editor or 3D scene editor. If one button should be visible at both places, the configuration should include two similar buttons with different Visible settings.

Custom tab configurations in the Custom Ribbon Configuration Editor dialog

The Custom Ribbon Configuration Editor dialog implicitly displays data and behaves as described below depending on:

• Which configurations exist in the database.

• Whether your input in the discussed dialog is saved to the database.

No configuration + no unsaved data

• The Tab Label field should be set to the default Custom value.

• The Commands list is empty.

• The Deploy button is inactive.

• The Save button is inactive.

staging + no unsaved data

• The Tab Label field displays the tab name shown in the staging configuration.

• The Commands list includes the custom command buttons saved in the staging configuration.

• The Deploy button is active to move the name set in the Tab Label field and custom command buttons given in the Commands list to the deployed configuration.

• The Save button is inactive.

  

deployed + no unsaved data

• The Tab Label field displays the tab name shown in the deployed configuration.

• The Commands list includes the custom command buttons saved in the deployed configuration.

• The Deploy button is inactive.

• The Save button is inactive.

  

staging + deployed + no unsaved data

• The Tab Label field displays the tab name shown in the staging configuration.

• The Commands list includes the custom command buttons saved in the staging configuration.

• The Deploy button is active to move the name set in the Tab Label field and custom command buttons given in the Commands list to the deployed configuration.

• The Save button is inactive.

  

Any configuration + unsaved data

• The Tab Label field displays the tab name that will be saved to the staging configuration on clicking the Save button.

• The Commands list includes the custom command buttons that will be saved to the staging configuration on clicking the Save button.

• The Deploy button is inactive.

• The Save button is active to save the name set in the Tab Label field and custom command buttons given in the Commands list to the staging configuration.

  

Workflow for managing the custom tab configurations

You always save any changes to the custom tab definition you have made in the Custom Ribbon Configuration Editor dialog to the staging configuration first and then move the tab definition with the saved changes from staging to deployed in another dialog session. Saving any changes to the deployed configuration directly is not allowed.

Thus, the workflow for managing the custom ribbon tab and command buttons on it is the following:

1. Create a button icon and script file and save them in a dedicated directory on your machine or the cloud.

2. Add the custom tab to the ribbon by creating a custom button and saving it to the staging configuration.

3. Test the custom button in the staging configuration.

4. If there are issues with the custom button, fix them and save the changes to the staging configuration.

5. Once it is certain that the custom button works as expected, does not break anything, and does not introduce security risks, move the custom tab definition from staging to deployed to let Creators in the workspace use the custom button.

6. If it is necessary to update the deployed configuration, such as to add a new button, update or remove an existing button, rename or delete the custom tab, save the current tab configuration in backup files, including the icons and scripts.

7. Make the necessary changes to the custom tab and save them to staging configuration.

8. Test the changes in the staging configuration.

9. If necessary to fix issues with the changes, save the fixes to the staging configuration.

10. If necessary to dismiss the changes and restore the old deployed configuration, save the old definition from the backup files to the staging configuration.

11. If the changes are OK or the old definition is restored, move the custom tab definition from staging to deployed.

Creating the custom ribbon tab

On installing the Canvas Envision Creator web application, the ribbon of the document page editor and the 3D editor does not include the custom tab.

To create the custom ribbon tab for Creators in the workspace to use it in the document page editor or the 3D editor:

Renaming the custom ribbon tab

On the first creation of the custom ribbon tab after installing the Canvas Envision Creator web application, the name of the custom ribbon tab is Custom by default.

To rename the custom ribbon tab:

Removing the custom ribbon tab

To remove the custom ribbon tab from the document page editor or the 3D editor so that Creators and Admins in the workspace will not be able to use this tab:

Deploying custom ribbon tab

To move the custom ribbon tab definition from the staging configuration to the deployed configuration and let Creators in the workspace view and work with that tab definition:

Creating custom ribbon tab buttons

To create a new command button on the custom ribbon tab so that Creators and Admins in the workspace will be able to use this new command button:

Moving buttons on the custom ribbon tab

The order of custom command buttons is the following:

• From top to bottom on the Commands list.

  

• From left to right on the custom ribbon tab.

  

• From the start to the end in the array of custom command buttons in the database.

On creating a new custom command button in the Custom Ribbon Configuration Editor pop-up dialog box, it is appended to the Commands list as the last one.

To move a command button on the custom ribbon tab so that Creators and Admins in the workspace will be able to view and use this command button at the new position:

Updating custom ribbon tab button properties

To update a command button existing on the custom ribbon tab so that Creators and Admins in the workspace will be able to use the updated command button:

Deleting custom ribbon tab buttons

To delete a command button from the custom ribbon tab so that Creators and Admins in the workspace will not be able to use this command button: