Toolbar configuration

The file user-config/toolbar-config.js now defines everything about the toolbars.

Customer admins can go in and manage this instead of modifying index.html directly: VirtualViewer code goes into this configuration file and creates a toolbar button for every configuration entry that it sees.

There are three parts to toolbar-config.js. First, we have the two big lists: imageToolbarButtons for the top toolbar and annotationToolbarButtons for the left-hand toolbar. Their names should categorically not be modified, particularly not in the final return statement in toolbar-config.js.

Take, for instance, imageToolbarButtons. It looks like this:

var imageToolbarButtons = {
  "buttonKey": {button configuration),
  "anotherButtonKey": {button configuration}
};

Each “buttonKey” is a unique, descriptive key for the toolbar button. Unique because it’s defining the button in the configuration, and also because it’s used in the HTML. It should be letters only, and it is good practice for customers to put a prefix on this key. For instance, Big Company, Inc may call a key “bcMyKey.”

This is the same structure as the annotation toolbar list of buttons. Each button key should also be unique between the two lists—don’t put “vvMyNewButton” as a key in the image toolbar configuration and in the annotation toolbar configuration.

Now we can look at the button configuration. In the curly brackets, there are a few items:

localizeKey: This is a string referring to a locale file, where the text that appears in the title–what appears in the tooltip and in the dropdowns–is stored. If a customer is creating a whole new button that doesn’t have an entry in a locale file, this field can be left blank, but the “name” field must be filled in or the button will appear blank in dropdowns.
name: This is a string with the name of a toolbar button. VirtualViewer buttons do not use this property, since they use localized strings, but customers without an entry in a locale file must put the name of their toolbar button in this field. This should be something short and descriptive.
clickHandler: This is the function that will be called when a user clicks on the toolbar button.
iconImage: This is a string representing a URL to an icon image. VirtualViewer buttons use CSS files to assign icon images, but customers can list an image here and it will be used.
addSeparatorAfter: This is a boolean value. If a group of buttons is too long, it may be necessary to add a bit of whitespace after a button to visually break up the group when the toolbar is fully expanded. If this is true, the viewer will pop some white space after the button. It is not necessary to specify “false” on this item.
groupId: This is a string, and it refers to a group key. Groups are also configured in toolbar-config.js. If a button is in group A, it will be placed in group A in the order it appears–if the Sticky Note button is before the Rubber Stamp button in the annotation toolbar list, and they both belong to group A, the Sticky Note button will appear before the Rubber Stamp button in the UI. If an item is in the annotation toolbar list, it should be assigned to an annotation toolbar group.

Additionally, this is optional–if a button has no groupId, it will essentially be in an “uncategorized” list. It will appear at the end of the toolbar and will not be included in a dropdown. (See the Layer Manager and Watermarks buttons as default examples.)

The final part of toolbar-config.js is the group configuration list, called toolbarButtonLogicalGroups. This list looks very similar to the button configuration lists. What it will do is define all the buckets that the toolbar buttons can go into. Again, each group has a unique string key followed by a configuration object:

var toolbarButtonLogicalGroups = {
  "myGroupKey": { configuration },
  "myOtherGroupKey": { configuration }
};

The configuration items are as follows:

localizeKey: This is a string referring to a locale file, where the text that appears in the tooltip of the dropdown button is stored. This can be left blank.
groupTitle: Like “name” for the buttons, this is a string with the name of the group in it. For instance, “Preferences” or “Edit” or “File.” The localize key will handle this, but a customer without a locale entry could use “groupTitle”.
iconImage: This is a string representing a URL to an icon image. VirtualViewer buttons use CSS files to assign icon images, but customers can list an image here and it will be used.
annotationToolbar: This is a boolean flag that chooses where to put the group. If true, the group is an annotation toolbar group; if false or absent, the group is in the top toolbar. Annotation toolbar buttons should only be placed in annotation groups, and similarly, image toolbar buttons should only be placed in image toolbar groups.

Toolbar button configuration

Toolbar button group configuration