contents

intro
overview
requirements
cgi basics

dyno cgi
cgi headers
cgi parameters
accessing files
pipe basics
substitution basics
more substitution
table substitution

Dyno CGI: More Substitution

This section goes into more detail about using Dyno CGI substitution to create dynamic web pages.

SubstitutionPipe

The simplest way of doing dynamic page creation with Dyno CGI is to print a file through a SubstitutionPipe. You declare a SubstitutionPipe, assign the substitutions, and then call one of the print functions, specifying a file and the pipe.

In the simple case, you construct a SubstitutionPipe with a NULL initializer. This tells it that there is no next pipe, so its output goes to standard out.

For each variable in your HTML file, you create a particular SubstitutionAction object and stick it into the appropriate SubstitutionPipe::mSubstitutions[] array. The array index 0..9 corresponds to the variable digit in the variable marker in the HTML file.

TextSubstitutionAction

The simplest SubstitutionAction subclass is a TextSubstitutionAction. You just initialize it with a string that will be substituted. (It also takes a next pipe pointer in its constructor; this is typically NULL.)

So let's take an example snippet. Suppose we are in a CGI that takes a user ID, looks up information for that user, putting the user's name in a C string called "username", and prints a template.html page where the username is variable number 5 (in the HTML file as <!--^5-->). The code would look like this:

SubstitutionPipe pipe(NULL);

pipe.mSubstitutions[5] = new TextSubstitutionAction(NULL, username);

PrintNamedFilePiped("template.html", &pipe);

FileSubstitutionAction

This SubstitutionAction subclass replaces the variable with an entire file. Presumably the file should not contain the HTML <HEAD> section or even <BODY> tags, because your template file already has them. But it is OK to have other formatting tags, links, and image tags in the file, and they'll have the desired effect (assuming that the paths are either full, or are relative to the location of the CGI).

So starting with the example above, let's suppose that you want to pull in a news article contained in the file named with a date stamp and article number, "20000218_1234.txt" (let's say this is in the C string variable called articleFileName, because you probably chose the article number dynamically) and use it to replace variable number 4 in the template file. You would simply add this line of code to the above example:

pipe.mSubstitutions[4] = new FileSubstitutionAction(NULL, articleFileName);

BodySubstitutionAction

This SubstitutionAction subclass is similar to FileSubstitutionAction, but it parses the file in question and throws away everything but what's between the <BODY> tag and the </BODY> tag. In other words, only the HTML body section is used. This is very useful if you want to use an HTML file that has a <HEAD> and <BODY>. For example, you may have created the file in an HTML editor (some editors give you an option of omitting them, in which case you would need to use FileSubstitutionAction, which would actually be faster since FileSubstitutionAction does not need to parse the file the way BodySubstitutionAction does).

So, adding to our example, let's suppose that you have an HTML file with boilerplate footer stuff, like a copyright notice and a contact link, in a file named "footer.html". You would add the following to substitute it into variable number 3:

pipe.mSubstitutions[3] = new BodySubstitutionAction(NULL, articleFileName);

FieldSubstitutionPipe

This SubstitutionPipe subclass uses a single FieldSubstitutionAction objects instead of an array of SubtitutionAction objects; and instead of using a fixed set of up to ten integer-based variable names, it uses any number of string-based variable names. The action object must decide how to replace each named variable.

The main reasons to use a FieldSubstitutionPipe instead of a SubstitutionPipe are:

  • If you have more than ten variables.
  • If you prefer using variable names to using variable numbers.
  • If you prefer using a VariableList to using individual TextSubstitutionActions.
  • If you will be using a FieldSubstitutionAction subclass such as TOCFilesTableSubstitutionAction.

In the simple case, the base class FieldSubstitutionAction does the substitution.

FieldSubstitutionAction

This SubstitutionAction subclass is constructed with a VariableList object. The variable list is essentially a list of name+value pairs. The name is a variable name; the value is a string to replace the variable when the variable appears in the pipe data. In other words, when you print a file through a FieldSubstitutionPipe, the FieldSubstitutionAction is given each variable marker in the template file, and it matches the variable name against the variable list, and prints the variable value instead of the marker.

So let's take a new example where you have two variables, <!--^zipcode--> and <!--visanumber--> and similarly named C strings which contain the dynamic data for these variables. You just need to create a VariableList, a FieldSubstitutionAction, and a FieldSubstitutionPipe, add the variables to the variable list, and then print the template file through the pipe:

VariableList            variables;
FieldSubstitutionAction action(NULL, &variables);
FieldSubstitutionPipe   pipe(NULL, &action);

variables.AddVariable(new Variable("zipcode", zipCodeString));
variables.AddVariable(new Variable("visanumber", visaNumberString));

PrintNamedFilePiped("template.html", &pipe);