Add-In Architecture

Help Builder's Add-in architecture is meant to allow you to extend Help Builder in place. The architecture is fairly simple and requires implementation of an object in .NET, Visual FoxPro or COM. This object is then called by Help Builder which passes an instance to the Help Builder IDE as a parameter. From this instance the add-in can retrieve information about the environment, the current Help Builder project and the currently active topic.

.NET Assemblies

.NET Assemblies are called via COM Interop from Help Builder. Help Builder uses the wwReflection.dll interface to dynamically invoke any .NET components specified. The component is loaded into new AppDomain and the specified method is called with an object parameter of the IDE instance (a COM reference). A .NET component is referenced is referenced by the following:

A full path to the DLL/EXE assembly file
A fully qualified class name (ie. NameSpace.Classname)
The name of a method that can accept a single Westwind.wwHelp.HelpForm parameter

Visual FoxPro PRG/EXE/APP

Visual FoxPro supports two modes of operation using either a single PRG file that is compiled dynamically by help builder, or via self contained EXE/APP file. The difference for the APP/EXE files is that Help Builder will first execute the EXE/APP file's mainline code which should contain all the code necessary to load class libraries or other dependencies such as setting paths necessary to load the class.

Help Builder then invokes the specified class and method by instantiating the class specified and calling the method with a single parameter that is a reference to the Help Builder IDE (a Fox object).

A full path to the PRG/EXE/APP file
A name of a class to instantiate. In the PRG this class must exist in the PRG
In an EXE/APP the class library must be loaded via the startup code (see examples).
A name of a method that can accept a single parameter

Add-in Configuration Storage

Internally add-ins are internally stored in the add-ins table in the Help Builder install directory. This table does not exist by default and is created when Help Builder is run for the fist time with the table not there.

This table contains information about the name and location of the add-in and how to activate the add-in. It contains the following fields:
Pk
C (10)
A Unique Id for the add-in which is used for selecting and executing that add-in.

Name
C (80)
The title name for the add-in

Descript
C (254)
The long description for this add-in

Type
C (3)
The type of add-in:
NET
FOX
COM

Filename
C (254)
The filename that houses the add-in

Objname
C (80)
The name of the object that is to be invoked.

Objmethod
C (80)
The name of the method that is to be invoked. The method must receive a single parameter of type Object that is the Help Builder main form. The method should return .T. or .F. depending on whether it succeeded or not.

Any record added to this table will show in the list of add-ins. Preferrably you should use the Add-in Manager option on the tools menu to manage your addins. It's recommended you install add-ins into the AddIn folder, but this is optional. By convention Addins should start with a filename of hbaddin_<yourname>.ext as this will be the default listing mechanism for addins from the Add-in Manager.

Add-in Configuration File

Once you've created an add-in you might want to share it with others or install it on other machines. Help Builder facilitates the installation process by providing the option to create an add-in Configuration file from which an add-in can be loaded. This file contains the name of the class and method to call so anybody using the class doesn't have to remember this information. The Add-in manager contains options to import and export add-in information to and from these configuration files.

The configuration file can be exported from the Addin Manager and is stored as .hbaddin file. This file is an XML file that hold configuration data and looks like this:

<?xml version="1.0"?>
<helpbuilder>
<addin type="object" class="empty">
<descript>This sample is a very basic example of how to manipulate the active topic in Help Builder.</descript>
<filename>helpbuilder_addin.dll</filename>
<name>.NET 2.0 Addin</name>
<objmethod>Activate</objmethod>
<objname>HelpBuilder_Addin.SampleAddin</objname>
<pk>_3190ORUZG</pk>
<type>.NET</type>
</addin>
</helpbuilder>

These settings match