DLL and Shared Library Implementation

In the DLL and shared library implementation, the component expand ( ) method is passed opaque pointers to dictionary and string objects and a pointer to an array of functions for accessing and manipulating them. You must include the file “webbot.h” to obtain definitions for these types.

The Expand method’s interface is as follows:

void Shortname_Expand (
   WebBotString* retString,
   WebBotDict*   botAttributes,

   WebBotDict*   cgiEnvironment,
   WebBotDict*   formData,
   WebBotFuncs*  funcs )

The file “webbot.h” defines two in-line C++ classes, CWebBotDict and CWebBotString, for easy access to WebBotDict and WebBotString parameters:

class CWebBotDict
{
CWebBotDict(WebBotDict* dict,const WebBotFuncs* funcs);
   // Constructs a new CWebBotDict from a WebBotDict.

long NumValues(const char* key);
   // Returns number of values for this key.

const char* GetValue(const char* key);
   // Returns a string value for a particular key.

const char* GetValueN(const char* key, short ValueNum);
   // Returns the nth value of a multi-valued key
   (or the only value of a single-valued key).

const char* NextKey();
   // Returns the next key in the dictionary.
   // Returns 0 when the end is reached.

void SetValue(const char* key, const char* value)
   // Sets the string value for a particular key.  If the key

   // has more than one value, it sets the first (0th ) value.

void SetValueN(const char* key, const char* value, short valueNum)
   // Sets the valueNum’th string value for a particular key.

void RemoveKey(const char* key)
   // Removes the key, + all associated values, from the

   // dictionary

void Reset();
   // Resets the iterator to the beginning.
}

class CWebBotString
{
CWebBotString(WebBotString *string, WebBotFuncs *funcs);
   // Constructs a new CWebBotString from a WebBotString.

void Clear();
   // Resets the string so it is empty.

void Append(const char* stringToAppend);
   // Appends a C string to the string.

const char* GetContents(WebBotString* string);
   // Gets the contents of the string as a C string
}

There can be more than one value for a given key. Use the DictGetValueN and DictSetValueN methods to take advantage of this. Note, however, that there is no guarantee that the order of the entries for a given key will remain the same between calls to the Edit or Expand methods of a FrontPage component DLL. That is, what used to be the first value of a key could get swapped with the second value for the key between calls to the FrontPage component DLL.

The file “webbot.h” defines a pair of macros, BeginWebBotExpand and EndWebBotExpand, that simplify the process of defining an Expand method. BeginWebBotExpand takes five names as arguments:

The shortname of the component (as in botname_Expand)
The name of a CWebBotString variable where you will append your HTML
The name of a CWebBotDict variable holding the component attributes
The name of a CWebBotDict variable holding the CGI environment
The name of a CWebBotDict variable holding the form variables (if any)

A very simple “hello” WebBot component can be implemented in C++ as follows:

#include “stdio.h”
#include “../webbot.h”

BeginWebBotExpand(hello,ret,bot,cgi,form)
{
   ret.Append(“<H1>Hello, WebBot World!</H1>”);
}
EndWebBotExpand

For a C language component implementation, you can manipulate the strings and dictionaries using syntax like funcs->MethodName.

The methods provided by the WebBotFuncs structure are as follows:

long DictNumValues(WebBotDict* dict, const char* key);

const char* DictGetValue(WebBotDict* dict, const char* key);

const char* DictGetValueN(WebBotDict* dict, const char* key, short valueNum);

void DictReset(WebBotDict* dict);

const char* DictNextKey(WebBotDict* dict);

void StringClear(WebBotString* string);

void StringAppendTo(WebBotString* string, const char* stringToAppend);

const char* StringGetContents(WebBotString* string);

void DictSetValue(WebBotDict* dict, const char* key, const char* value);

void DictSetValueN(WebBotDict* dict, const char* key, const char* value, short valueNum);

void DictRemoveKey(WebBotDict* dict, const char* key);

The FrontPage component API also supports components that can execute on the client side. If the .inf file describes the component as having clientbinding=DLL, then the clientmodule is a DLL that will be downloaded to the client and executed. FrontPage displays a dialog warning that a download is about to occur and giving the user an opportunity to cancel. If the user tries to edit a component that is not defined for the current web, or if FrontPage is not running or has no current web open, then FrontPage will use the generic FrontPage Component Properties dialog instead of the custom dialog.

The client-side interface is similar to the server-side interface. A set of opaque pointers is used to pass information from FrontPage to the FrontPage component. You must include the file “webbot.h” to obtain definitions for these types.

The Edit method’s interface is as follows:

int Shortname_Edit(
WebBotDict*      botAttributes,
WebBotFuncs*   funcs
)

The botAttributes argument is a dictionary of all of the component attributes. This will be empty if the user is inserting a component, but will contain the attributes that were previously added to the dictionary by the component if the user is editing a component that was already inserted. The Edit function should return zero if the user hits cancel, and non-zero otherwise.

The CWebBotDict class, defined in webbot.h and described earlier in this section, may be used in the Edit method as well as the Expand method. The file “webbot.h” defines another pair of macros, BeginWebBotEdit and EndWebBotEdit, that simplify the process of defining the Edit method. BeginWebBotEdit takes two names as arguments:

The shortname of the component (as in botname_Edit)
The name of a CWebBotDict variable holding the component’s attributes

For a C language implementation, you can manipulate the strings and dictionaries using syntax like funcs->MethodName. The same functions are available through the WebBotFuncs structure as described in the Expand method.

When a FrontPage component is first instantiated, either from the Insert: FrontPage Component dialog or the Form Properties dialog, its attribute dictionary is empty.

Because there is no BTL file for client-side DLL components, the component must add any required attributes, including PREVIEW and TAG keys, to the botAttributes dictionary when the Edit method is called for the first time. The purpose of these keys is described earlier, in the documentation for the BTL file format. The only difference is that the PREVIEW string does not need to have <, >, and & characters escaped in the Edit method. An easy test to find out if the component is being created for the first time, rather than modified, is to see if botAttributes.NextKey returns NULL at the start of the Edit method. This test will fail once you have added some attributes to the component.

A very simple “hello” component can be implemented in C++ as follows:

#include "../webbot.h"

BeginWebBotEdit(hello, botAttributes)
{
   botAttributes.SetValue("PREVIEW", "<H2>Hello World!</H2>");
   botAttributes.SetValue("TAG", "H2");
   return 1;
}
EndWebBotEdit

The major advantage to using client-side DLLs for FrontPage components is that the component can implement any kind of property-editing dialog box it requires. This means you’re not just limited to the generic FrontPage Component Properties dialog. You get much greater flexibility on the client side to perform selection actions, such as browsing the local hard drive for files, or displaying a custom color selection dialog box. Another advantage is that the PREVIEW key is generated at run-time, allowing a component to create a much better approximation of the final output. Note that the same DLL file may be used for the client- and server-side routines.