Adding a form to webmark

Webmark is my slightly hacked-together system for producing PDFs from a Web Form. As it was intended to be entirely stateless, single-use, and to require no connection between input and output, except for some fields, it was never designed to hold schema information or metadata, so there’s a little duplication of effort in adding a form to the system. Still, it was designed so that this task could be done with zero code modification.

On a checked out copy of webmark (branch apacheconf), on a configured server (#include <dice/options/webmark-server.h>), the requirements for a new form are:

  • A formgroup configuration file
  • An HTML form snippet, to POST the form data
  • A LaTeX template

configuration

A form group consists of a subdirectory of the forms data directory, containing a configuration file, config.ini. Constructing a configuration file is beyond the scope of the blog, but a fully-documented template can be found in the file config.ini.template, and examples in existing formgroups.

To add a new HTML form to webmark, locate your formgroup’s configuration file, and modify the [group] section with the name of your new form (which will correspond to a .php file in the form subdirectory):

[group]
 name = "Form Group Title"
 forms "form1 form2 newform"

each HTML form produces a number of LaTeX files. These are defined in the [form_formname] section of the configuration file. To add a new LaTeX output from an existing form, simply add the its name (corresponding of course to a .tex file in the form subdirectory):

[form_form2]
 tex = output1 output2 newoutput

It’s also necessary to define at least one required field; the sample configuration demonstrates this.

the HTML

This takes the form of a named .php file in the form subdirectory. You need only provide valid input fields, which will be placed in an HTML form.

You do not need to provide submit or other form niceties, only the relevant inputs and their name attributes. These can be in any form you like, though you are free to use some of the convenience PHP functions provided.

A simple example:

<fieldset><legend>Personal Details</legend>
 <label for="firstname">First Name: </label><input id="firstname" name="firstname"/>

 <label for="lastname">Last Name: </label><input id="lastname" name="lastname"/>
 [ ... ]
 </fieldset>

All POST inputs are checked for safety and, with certain reserved exceptions, translated into fields for inclusion each of the latex files you named in the configuration.

the LaTeX

This (the TeX itself excepted, naturally) is very simple indeed. Webmark performs a simple substitution to insert a number of fields into a copy of a named .tex file in the form directory; these will be of the form fieldname and will expand to the exact (filtered) text from the form.

If you do not require a field (i.e. it is not listed in the configuration file as a required field), your LaTeX file must be able to cope without that field. The easiest way to do this is to insert a set of statements which define the field only if it does not exist, for example providecommand{fieldname}{}.

The simplest template document, then:

% LaTeX template for Webmark document.

 % This line is essential:
 % Webmark will insert all POSTed fields in the line below.
 %!variables!

 % here, all undefined optional field defaults are provided.
 providecommand{optionaltext}{}
 providecommand{yesnofield}{No}

 % now define the document as you wish.
 documentclass{article}
 usepackage{a4wide}

 begin{document}
 section*{Sample Form}

Name:                   textbf{firstname lastname}

Happy with webmark?:    textbf{yesnofield}

Comment:                textbf{optionaltext}

end{document}

That’s it; commit the files and Webmark will do the rest.

2 thoughts on “Adding a form to webmark

  1. gdutton Post author

    It’s worth noting that, quite soon, Webmark’s configuration will have been augmented to include various new ways of creating and controlling output, including per-form access controls and eventually custom output formats. As this post becomes less relevant, remember that the canonical “webmark modification document” will be the configuration template file. Seek this out before making a new Webmark form.

  2. gdutton Post author

    Some time in January, this post disappeared from the blog, for no reason I could ascertain. Only thanks to Google’s cache did I spot its absence and manage to restore it!

Leave a Reply

Your email address will not be published. Required fields are marked *