Default.tbr Issues when Upgrading to XMetaL Author Enterprise 5.5

[KBenjamin]

We are in the process of upgrading from XMetaL Author Enterprise 4.5 to XMetaL Author Enterprise 5.5. Our default.tbr includes a customization to the File>New menu as well as additional submenus under the File menu. The first time XMetaL 5.5 is accessed (either from a new installation or by a new user), our customizations do not appear on the menu. Once C:Usersuser nameAppDataRoamingSoftQuadXMetaL5.5default.tbr is deleted, the next time XMetaL is accessed, the customizations do appear. Based upon this behavior, I am assuming that XMetaL scripts a default.tbr when the SoftQuadXMetaL5.5 folder is created under the user directory. Is this correct? Is there a way to force XMetaL to copy C:Program FilesXMetaL 5.5AuthorRulesdefault.tbr instead of scripting default.tbr for new installations? Or is there a better solution to have our customizations appear the first time XMetaL 5.5 is opened?

Reply

[Derek Read]

This is not new to this version of XMetaL Author (5.5). Deployment of the default.tbr file has not really ever been a supported feature for newly installed copies of the product. The first time XMetaL Author is launched after a fresh installation it figures out a number of things in memory while it is starting up (which toolbars to show, where to put them, various sub-window sizes, etc).

The first time the product is shut down all of this information is written to the Windows Registry (including any changes the user has made with regard to where things are positioned, which documents were left open and other things). It also generates the default.tbr file at this time (again, based on the current state of what it has in memory, and a user may have altered it at that time). If the product has never been launched it assumes default.tbr does not exist, and will overwrite an existing file with the same name in the user's %appdata% folder. You might think that we could change the product to simply not overwrite an existing copy but the complexity of how all of these things are set up makes that impossible (well, I guess nothing is impossible, but it would be very complex and the potential to mess things up for existing clients would be large).

Recommended Solution:
The recommended method for deploying application-level customizations that need to modify toolbars and menus is to script those modifications using the Application.CommandBars APIs and the event provided for that purpose. This is how our partners make their toolbar and menu changes to provide functionality for interacting with their CMS systems and other 3rd party software, and it is also how we customize XMetaL Author to include special menu items for XMetaL Reviewer, the CMS systems we maintain integrations with ourselves and various other things including the DITA menus for XMetaL Author Essential.

Following script example demonstrates the basics of these APIs. This example checks for the existence of a toolbar and if it is not there creates it, then adds buttons to it. A more complex version might take into account the fact that a user can modify toolbars, and might cycle through all the buttons to make sure they are all still there too, and if any are missing add them again.

Keep in mind that you can stop users from making modifications to their toolbars using the INI variable enable_toolbar_customization=false, which is another easy solution for that issue.

[code]var tbrExists = false;
for (i=1;i<=Application.CommandBars.count; i++) {
if(Application.CommandBars.item(i).name == “My Custom Toolbar”) tbrExists = true;
}
if (!tbrExists ) {
//toolbar doesn't exist, add it then add buttons
var cust_Toolbar1 = Application.CommandBars.Add(“My Custom Toolbar”); //add buttons to toolbar
var newButton = cust_Toolbar1.Controls.Add(sqcbcTypeButton);
newButton.TooltipText     = “Tooltip 1”;
newButton.OnAction        = “Name of Macro to Run 1”;
newButton.DescriptionText = “Description 1”;
newButton.FaceId          = 0; //no icon = default pink arrow var newButton = cust_Toolbar1.Controls.Add(sqcbcTypeButton);
newButton.TooltipText     = “Tooltip 2”;
newButton.OnAction        = “Name of Macro to Run 2”;
newButton.DescriptionText = “Description 2”;
newButton.FaceId          = Application.MakeFaceId(“General (Custom)”,2,10); var newButton = cust_Toolbar1.Controls.Add(sqcbcTypeButton);
newButton.TooltipText     = “Tooltip 3”;
newButton.OnAction        = “Name of Macro to Run 3”;
newButton.DescriptionText = “Description 3”;
newButton.FaceId          = Application.MakeFaceId(“General (Custom)”,2,9);
} ]]>[/code]

Untested Solutions that Might Work For You:
If you really want to try to deploy default.tbr you might try one of these untested solutions.

Update (2009/09/23 14:00 PST): I've been warned by development to say that we really recommend NOT trying the following idea (#1). In theory it could work, but this is really pushing things when we start copying bits of the registry.

The BEST option for setting up custom default toolbars really is to use the Application.CommandBars APIs as described above and documented in the Programmers Guide.

The second idea below should be safer (though it is still untested). It should be safe provided you properly automate what would actually happen if the user were to launch XMetaL Author after installing it before copying your default.tbr file over.

Idea #1:
Obtain the settings you need to make XMetaL Author think it has already been installed.
1. Install XMetaL Author Essential or Enterprise on a test machine.
2. Launch the product and shut it down. This will set up the default workspace, default.tbr and other files, including the basic xmetal55.ini file.
3. Open the Windows Registry editor and export this key to a .reg file (which should include everything below it): HKEY_CURRENT_USERSoftwareSoftQuadXMetaL 5.5

Script the following logic into your “main” installer (which might be a .bat file at the simplest).
1. Install XMetaL Author Essential or Enterprise (the setup.exe can be run silently using standard InstallShield commandline parameters).
2. “Run” the .reg file to copy the settings it contains into the registry.
3. Place your default.tbr file into %appdata%SoftQuadXMetaL5.5

One aspect of this that I am worried about is that the workspace sets up window dimensions that record the positions and sizes of different parts of the application (anything you can resize and move around). So, copying the workspace settings from one machine to another that has  a wildly different screen size might be an issue.

Idea #2:
Script the following logic into your “main” installer (which might be a .bat file at the simplest).
1. Install XMetaL Author Essential or Enterprise (the setup.exe can be run silently using standard InstallShield commandline parameters).
2. Register XMetaL Author as a COM object by running the following command at the command line: xmetal55.exe /RegServer
3. Launch the product.*
4. Shut down the product.*
5. Place your default.tbr file into %appdata%SoftQuadXMetaL5.5

* The following VBScript (saved as a .VBS file) should perform steps 3 and 4 above and it (or something similar) could be called from a .bat file or a real installer. Register XMetaL as a COM object prior to running such a script to be sure this will work (step 2):
[code]
Set xmApp = CreateObject (“XMetaL.Application”)
xmApp.Quit()
[/code]

Reply

[Author]

Posts