Wiki‎ > ‎

Developing Forms


Philologic Forms

When you load a database with Philologic3, two different forms are generated. These are installed into you web path, as specified in philologic.cfg. By default, they are given the names DNAME.form.html and DBNAME.whizbang.form.html. If these files already exist, the string new. is prepended to the name until a unique name is reached.

Three other files are checked for, and, if they don't already exist, are created in your web path. They are:

  • history.js - a JavaScript file that facilitates search history retention via cookies.
  • whizbang.js - a JavaScript file that contains functions for the WhizBang form, to show and hide search tabs, create the search summary, etc.
  • whizbang.css - a Cascading Style Sheet for the WhizBang form.

How the forms are created

The makeforms_gold.pl script is automatically run from the /lib directory of the database directory after the database is loaded. The script pieces together parts found in the /lib/forms directory of your database directory. If you want to make installation-wide changes in the forms that Philologic generates, you can do so in the /installdir/lib/forms directory of the Philologic install directory.

All form elements except most of the bibliographic fields and the div and sub-div fields are included in the final form no matter what. Some of these options may not be appropriate for a particular database, so you should manually edit the form after it is generated and arrange things to your liking. For example, it makes little sense to have an "Author" search field on a database that contains only the plays of Arthur Miller.


Bibliography, Div and Subdiv

The bibliographic, div and sub-div fields are only included if those fields exists in the data and have values in the data. Three files in the root of the database directory are examined: bibliography, divindex.raw, and subdivindex.raw. Whatever fields are found in these files are included in the form, if they have any values.


Examples

For each field that is found, a random example is chosen and included next to the field. It will probably be necessary to edit the form to change some of these examples to be shorter, clearer, or more instructive.


The Forms


The Normal Form

One of the forms that Philologic3 creates for you is a very plain vanilla form with limited formatting and complexity. This form is called DBNAME.form.html, and is emminently suitable as a starting point for most databases which lack bibliographic and structural complexity, or if you want to end up with a presentation that has all options available on the page at the same time. It may require some scrolling to get around the form, but all the options are present in one view.


Whizbang

The other form that is generated is much more complicated, with a more polished look and feel, relying heavily on JavaScript and CSS. This form is named DBNAME.whizbang.form.html. It uses the whizbang.js and whizbang.css files to create a tab-based form with most options hidden from the user until they select the appropriate tab. This cuts down on visual clutter while attempting to keep the most commonly used options readily accessible.

Another feature of the WhizBang form is the query summary section. On the right-hand side of the page, a dynamically updating area displays a summary of the query about to be run, so that there is no need to click through all the tabs to find out what has been filled in, organized by category. Clicking on a category header opens or closes the corresponding tab.


Comparison


Normal WhizBang
Browser Specs Should work in just about any reasonable browser. Query history requires JavaScript. Requires a modern browser (IE 6, NS 7, FF or Safari) with CSS and JavaScript. Should degrade to a usable but ugly view in others.
Presentation Kind of ugly and bare bones, but you can change that. More sophisticated, clean.
Ease of Use If you can edit HTML, you should have no problem taking this form and customizing it. This form is fairly complicated. You will need to read, understand and edit the whizbang.js file in order to make major strucural changes to this form. Changing the text or adding examples is still easy.