Appboard/2.5/builder/custom icons

Overview

Icons are a fundamental concept shared throughout AppBoard in many different visualizations such as lists, tables, and maps. AppBoard ships with a broad set of generic icons and this page details how to add additional icons.

Please note this page refers to icons as defined by setting a Default Icon or via Icon Filters. Status Shapes are not icons as such but automatically rendered shapes with colour tints applied. The set of shapes is defined in code and not user extensible.

Icon Chooser

When configuring a widget that supports icons the Icon Chooser is used to make a selection, as shown below. The Keyword Search can be used to search through tags associated with each icon. This will be explained in the sections below detailing how to add custom icons.

Icon Chooser dialog

The Google Map widget and Vector Map widgets have a specific set of icons only used for those widgets. The list of images that appear in the Icon Chooser will differ when editing those widgets.

Custom Icons

To make icons available to AppBoard they must be registered in the Icon Registry which is loaded on startup. The basic process for adding custom icons is:

1. Copy the icon/image files onto the AppBoard server.
2. Create an icon registry file for the custom icons, and copy this to the server.
3. Include the custom icon/image files and icon registry file in full archives.

Copying Icons to the Server

1. Create a directory for the custom icons, this has to be under the visualizer directory, but it is recommended to create a custom directory for all custom icons such as:

   [INSTALL_HOME]/server/enportal/visualizer/assets/custom/icons/

2. Copy all the icon/image files into this directory on the AppBoard server ensuring to set the correct ownership and permissions for AppBoard to access the files.

Icon Registry Files

AppBoard maintains the icon registry in the following directory: [INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/appboard/config/iconregistry. All csv files in this directory are loaded and by default the following files are included with the install - these should not be edited:

• backgrounds.csv: images used for backgrounds with the Diagrammer widget.
• base.csv: the broad set of generic icons used by most widgets.
• custom_military.csv.disabled: supplementary military focused icons, disabled by default (remove .disabled to have this loaded).
• mapBadge.csv: images used for the Vector Map iconic badges.
• mapIcon.csv: images used for the Google Map widget.
• patterns.csv: pattern images used in various chart widgets for filled areas.

To add custom icons you must:

1. Create a new registry .csv file with the correct fields and values for each of the custom icons added to the server. This should have a filename that differs from the set of shipped registry files listed above. See further down for the format of this file.
2. Copy this file into the icon registry directory, for example:

   [INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/appboard/config/iconregistry/custom_icons.csv

3. At this point the AppBoard server can be restarted and if there are no issues the new icons should be available!

Registry Format

This table describes the csv format as used by the icon registry. All fields are required and errors may result in failure to process the entire registry. A good idea is to also look at the default base.csv file as an example.

#	Field	Type	Description
1	type	string	Should always be set to base.
2	style	string	This column is optional, if included set to 3d.
3	id	string	Internal unique identifier across all icon registry files.
4	label	string	The label shown in the user interface, such as in the Icon Chooser.
5	rasterPath	string	This is the path to the icon file location relative to the visualizer directory on the server. So for example using the recommended directory from above: assets/custom/icons/office.png
6	vectorPath	string	This can be left blank in most instances unless producing vector swf icons. Otherwise it should provide a path relative to the visualizer directory as with the rasterPath.
7	width	integer	Width of the icon in pixels.
8	height	integer	Height of the icon in pixels.
9	centerX	integer	The x-axis center point. Not all images have a center in the middle of the image, so for correct placement set the image center correctly.
10	centerY	integer	As above for the y-axis center point.
11	tags	string	Set of space separated tags to allow for easy searching in the Icon Chooser when large numbers of icons are available.

Including in Backups

Finally the last step is to ensure all icon files and the custom icon registry file are included in full backups. This is to make sure that when restoring the system, or migrating from one environment to another, that the custom icons will be included.

See the Customizing the Export section on the Backup & Recovery page for more information.