Creating a FoxPro based Add-In

You can create two types of FoxPro based add-ins:

• PRG type which gets compiled on the fly
  
• APP/EXE type which gets loaded dynamically
  

PRG based Add-In

A PRG based add-in is a simple self contained add-in that consists of a single PRG file. This PRG file gets dynamically compiled by Help Builder and then causes the class and method specified in the add-in's configuration to be fired.

A simple class looks like this:

DEFINE CLASS ChmImport as Custom

FUNCTION Activate(loHelpForm)

*** Reference to the Help Builder Project object 
*** (Class wwHelp)
loHelp = loHelpForm.oHelp 

*** Currently active topic
loTopic = loHelp.oTopic

MESSAGEBOX("Hello from the FoxPro Addin" + CHR(13) + CHR(13) +;
           "Form Caption: " + loHelpForm.Caption + CHR(13) +;
           "Project: " + loHelp.cProjectName + CHR(13) +;
           "File: " + loHelp.cFileName + CHR(13) +;
           "Active Topic: " + loTopic.Topic)


IF !ISNULL(loTopic )
   *** Update the active topic
   loTopic.Body = TIME() + CHR(13) + loTopic.Body
   
   loHelp.SaveTopic()
   
   loHelpForm.Refresh()
ENDIF

RETURN .T.
ENDFUNC

ENDDEFINE

To specify a PRG file in the Add-in manager:

• Provide the filename to the PRG file preferably in the Addins folder of Help Builder
  
• Provide the name of the class (CHMImporter)
  
• Provide the name of the method (Activate)
  

APP/EXE based Add-in

Creating an EXE/APP based add-in allows you bit more control as you can create a fully self contained application that can combine your own set of classes and objects. For example, if you wanted to bring up forms or other UI elements that require external files you need to build your add-in as a compiled EXE or APP file.

Functionally there's not much difference between the PRG interface - the main difference is that the mainline of your APP/EXE file must load all related classes and and procedures.

*** Must load any classes that your add in might need!
*** Make sure to include the PRG/VCX that contains your addin class!!!!
SET PROCEDURE TO AddinTest ADDITIVE

*** Load any other libraries you might need
SET PROCEDURE TO wwLocaleInfo Additive

*** NOTE: These classes will load into Help Builder
***       so if you're using common West Wind classes
***       like wwAPI,wwUtils, wwConfig, wwIPStuff
***       they will already be loaded

*** TIP:  You can also use an add-in as a class loader 
***       for your templates! Any class or UDF() that
***       is loaded will also be visible in the topic
***       templates at render time!

DEFINE CLASS AddInTest as Custom

FUNCTION Activate(loHelpForm)
   MESSAGEBOX("hello from an EXE" + CHR(13) + ;
              loHelpForm.Caption)

   *** Create a class contained in your EXE
   oCustom = CREATEOBJECT("wwLocaleInfo")
   
   *** Call a form contained in your EXE
   DO FORM AddinTest
   
ENDFUNC

ENDDEFINE

To install your EXE/APP add-in the add-in manager:

• Provide the filename to the EXE or APP file preferably in the Addins folder of Help Builder
  
• Provide the name of the class (AddinTest)
  
• Provide the name of the method (Activate)
  

Called Method Interface

Both PRG and APP/EXE interfaces are passed an instance of a wwHelpForm object which is a reference to the HelpBuilder IDE, which is a FoxPro form. From this form you can get a reference to the Help Builder Object that allows you manipulate the Help Project. The current topic then is available as oTopic from the Help Builder object.

The following code demonstrates:

loHelp = loHelpForm.oHelp
loTopic = loHelpForm.oHelp.oTopic
lcTitle = loHelpForm.oHelp.oTopic.Title

Note that your addin can be called at any time, so there's no guarantee that a project is open or a topic active, so you should ensure to check for NULL on the Topic before using it and checking the project properties to get state information about the content you are currently accessing.

Help Builder's Libraries

Help Builder runs with a rather large set of classes already loaded. Specifically most of the West Wind Client Tools functionality is already loaded, so classes like wwUtils, wwAPI, wwXML, wwIPStuff, wwHTTP, wwSOAP etc. are all loaded and available to your Add-in.

In addition any of Help Builders global functions are accessible.