Rebranding Workbench and WbProfiles

Rebranding Workbench and WbProfiles

Why would you want to brand or customize Workbench? If you're an OEM partner, then you'll need to add your own logos and text in order to brand the Niagara product as your own. If you're a developer, scroll down to WbProfiles where we discuss customizing workbench to modify its appearance and behavior.

Basic Branding

The basic brand information for workbench is contained in the lib\brand.properties file. This file controls Workbench's Icon and Title as well as the splash screen title and image.

These are modified by changing (or adding) the following entries in the brand.properties file: workbench.title=Niagara Workbench

workbench.icon=module://icons/x16/workbench.png
workbench.splash=module://workbench/com/tridium/workbench/media/splash_wpp.png

The images below show where each of these properties are used in the Workbench Frame and the About/Splash screen.

The Splash Screen also contains the project and owner from the license file (if installed) and the version of the 'workbench.jar' module that is being used.

This should be enough to get your feet wet with branding Workbench. In the next section, we'll look at custom WbProfiles.

WbProfiles

Now that we have the basics under control, it's time to start adding more customization to workbench. We're going to have to get our hands dirty here and write some code.

There are two classes that we need to look at in the workbench module

javax.baja.workbench.BWbProfile
javax.baja.workbench.web.BWbWebProfile.

Let's start with BWbProfile. BWbProfile is the base class for all workbench customizations. To create our customized workbench, we'll want to extend this class with our own custom profile.

Overriding BWbProfile's various methods allows you to turn on and off and customized many UI elements. These methods include:

hasSideBar()
hasTools() 
makeStatusBar() 
makeLocatorBar() 
makeToolBar()  
makeMenuBar()

Returning false for the has…() methods and null for the make…() methods will turn off/hide the given UI element. To customize the menu or bar the following code snippet provides the general approach:

public BMenuBar makeMenuBar()
{
  //get the base menu bar
  BMenuBar original = super.makeMenuBar();
  //remove the edit menu
  original.remove("edit");
  //add a custom menu
  original.add("custom", new BMenu("Custom"));
  return original;
}

Suppose we don't want our customized Workbench to show the Wire Sheet View. We can override the hasView(BObject target, AgentInfo agentInfo) method to return false if the agentInfo.getAgentType().is(BWireSheet.TYPE). If we want to hide the Wire Sheet only on a BFolder, we could check the Type of the passed in target BObject. Similarly, if we want to disallow a certain Tool in the Tools menu, we would override the hasTool(TypeInfo typeInfo) method.

Let's talk about ords. We can define three different BOrds in our profile: NavRootOrd, HomeOrd and StartOrd. NavRootOrd is the root of all navigation (eg. cannot navigate up the tree from this BOrd). HomeOrd is the result of clicking the Home Tool Bar Button. StartOrd is the BOrd loaded when WB is started

BWbWebProfile is the base class for all Workbench (applet) web profiles. It extends BWbProfile and has a few key differences. It removes a number of menus and menu items from the menu bar. It removes the status bar, allows only the nav and palette sidebars and does not allow any Workbench tools. Additionally, the NavRoot is the BOrd in the browser's URL.

Distributing our Changes

Now that we've branded and customized our Workbench, how do we distribute it to our customers? We need to customize the installer. If all we're doing is branding, there are just two files in the Niagara Install Zip file that need to be modified.

While we could write an entire blog post on customizing the installer via the install-data\install.properties, we're only going to focus on the entries that have to do with branding. These entries are listed below and should be changed to match your brand.

window.title=Niagara Install
welcome.message=Welcome to the Niagara Installation Program!
welcome.message2=This program will install the NiagaraAX Runtime         Environment onto your computer:
welcome.message3=
install.dist=This instance of Workbench will be used as an         installation tool
finish.message=Niagara installation is complete!
finish.launchMessage=Would you like to?
finish.wb=Launch Workbench
finish.daemon=Install and Start Platform Daemon
default.folder=C:\\Niagara 
startMenu.folder=START_MENU_FOLDER
uninstall.window.title=Niagara Uninstall
uninstall.welcome.title=Welcome to Niagara Uninstall
uninstall.welcome.message=Welcome to the Niagara Uninstall Program!
uninstall.finish.message=Niagara uninstall is complete!

Shortcuts: Each shortcut is in the format shortcut.<number>.<property>. The numbers must be indexed starting with 0 and be sequential.

shortcut.X.bin          //path to executable - if not defined, no     shortcut created
shortcut.X.args         //additional arguments to pass to executable file
shortcut.X.lnk          //shortcut name - defaults to ShortcutX
shortcut.X.start        //normal or min - defaults to normal
shortcut.X.description  //description for mouseovers - defaults to ""
shortcut.X.startmenu    //display shortcut on start menu - defaults to true
shortcut.X.desktop      //display shortcut on desktop - defaults to true
shortcut.X.asuser       //default false, unless args is installdaemon, then always true
shortcut.X.iconLocation //path to file containing the alternate icon for the shortcut
shortcut.X.iconIndex    //index of icon in file - defaults to 0

The two images that the installer uses are in the following files. These should be replaced with files of the same name containing your custom images.

sidebarImage.bmp 95x255
titleImage.bmp 500x70

The other file that we need to modify is 'overlay\lib\brand.properties' which is where you should place your modified brand.properties file. The default brand.properties is contained in the setup.exe, so the overlay directory allows us to replace the default version.

If we have custom code to include with our installation (including but not limited to a customized BWbProfile), we'll need to add those modules to the modules directory.

Your Sales Support Channel can provide more information on this process.

 

Posted by Blake Puhak | 02-Dec-11 3:19 PM UTC

Add Feedback