Using custom FoxPro code in Topic generation

The WCS file format is actually run as an interpreted Visual FoxPro 8.0 program that uses embedded ASP style syntax. You can execute any FoxPro code from within these pages. Before you jump in though realize that each template is specialized to a specific topic type and that the template is rendered and any code within it run when ever a topic of that type is rendered.

Templates are simple - they are HTML output generators and thus should generate HTML. The simplest way to extend a topic template is by embedding and expression with:

<%= Expression %>

An expression can be any valid FoxPro expression that is in scope. For example to print the the current topic title you'd use:

<%= oHelp.oTopic.Topic %>

To print the body you can use:

<%= oHelp.oTopic.Body %>

Actually to render the body you probably want to use this syntax:

<%= oHelp.FormatHTML(oHelp.oTopic.Body) %>

as this takes the literal text in the topic (what you edit) and creates proper HTML from it. You basically will want to do this for every type of topic that is more than a single line or otherwise requires special formatting.

You can also embed entire blocks of code into a template. For example, to iterate through all the child objects of the ClassHeader topic type you can use something like this:

<h1><%= oHelp.oTopic.Topic %></h1>
<%= oHelp.FormatHTML(oHelp.oTopic.Body) %>
<p>
<b>Child Topics:</b>
<% 
cCurrentPk = oHelp.oTopic.Pk
cHTML = ""
oTopics = oHelp.GetTopics("ARRAY","ParentPK = '" + oHelp.oTopic.Pk + "'",;
                          "type,uMethod","ParentPk,Pk,upper(method) as UMethod") 

FOR lnLoop = 1 To oTopics.nCount
	oHelp.LoadTopic(oTopics.aTopics[lnLoop,2])
      cHTML = cHTML + "<hr>" + oHelp.oTopic.Topic + "</hr>" + CHR(13)
ENDFOR

Response.Write( cHTML )
%>

This simplefied code shows how to display the topic title and the body and then iterate through all of the child topics to display a list of all properties and methods and events. Obviously this child list display is pretty useless, but you can for example pick up the type (property event method) and based on that show an icon and create a cross link. For an example of how this is done look at the ClassHeader.wcs template which provides this logic with a little more detail.

If you embed code blocks note that you can also do things like pop up a Wait Window, or MessageBox() - everything Visual FoxPro goes, although it may not be the greatest idea to do so necessarily.

Extending even more with external code

If you choose you can also use code stored in external files. To this all you have to do is SET PROCEDURE TO at the top of a program and then call an external UDF. At the top of the template add:

<%
SET PROCEDURE TO MyCustomPrg.Prg ADDITIVE
%>

then anywhere in your code call your custom functions like:

<%= MyCustomMethod(oHelp) %>

This is more flexible as you can work within VFP to write your code.

Debugging Templates
This process is not trivial - Templates are interpreted and as such only report errors - there's no debugging internally for templates, except for tried and true MessageBox and Wait Windows you can sprinkle through your code.

If you use external code however, you can run the Help Builder EXE from within VFP.To do this:

Set a breakpoint in your code with SET STEP ON
Start Visual FoxPro
CD <Help Builder Install Directory>
DO WWHELP.EXE

Now when you're code is firing VFP will stop into the debugger to debug your template code.

Note that there's an error handler arround this code in the form of an Error Method, so if there are errors in your code you will not easily see the error. Just make sure you check return values and make sure that the code works as expected.