Creating and Editing Forms

grok distinguishes databases and forms. A database is an array of unformatted data, while the form specifies the structure of the data and describes how to display it in a card. The standard user interface that comes up when grok is started deals with database presentation and modification; to edit the presentation, or to create a new database, start the form editor from the File pulldown in the main window.

The form editor is a separate window that is rather more complicated than the standard database user interface. It is basically a simple UI builder that allows the user to create and position UI elements in a card.

General Setup

The first step when creating a new database is choosing a form name. This is the name that will appear in the Database pulldown in the main window (actually, the pulldown should be called Form, but I fear that would confuse casual users). Every form references a database whose contents it presents; this name must also be chosen. Typically, both names are the same.

Both the form name and database names are also the file names the form and the database will be stored in. The form name gets the extension ``.gf'', and non-procedural databases get the extension ``.db'' tacked on if the names are not fully qualified (i.e., do not begin with ``/'' or ``~''). If the database is procedural, the database file is a script, and has no .db or any other extension. This script is executed to read or write data.

When a database or form is read, the path it was read from is stored; when the database or form is changed, it is written back to that path. When a new database is created, and its name does not begin with ``/'' or ``~'' as defined in the second line of the form editor, it is stored in the same directory as its form file. The default is always ~/.grok. The Help->Database popup shows which paths are actually used.

The database is a two-dimensional array of strings. The rows are called cards, and the columns are called fields. Rows are separated by newlines, and columns are separated by the field delimiter. The field delimiter is a colon by default, but can be changed to any character. The button accepts characters, octal constants \nnn, and the tab character \t. Any character other than \0 and newline can be chosen; grok will properly escape the character when it appears in a database string. Severe chaos may result if the delimiter character is changed when the database already contains data.

Databases can be marked read-only. A user accessing a database through a form that is has the read-only flag set will not be able to change any cards, and will not be able to write back.

A procedural database does not read a file, but calls a script that provides the data in the same format that the file would contain. If the procedural button is turned on, the referenced database name is the name of the script, not of any database file. It may contain options. When the database is read, grok appends the option "-r" (read) and the form name as shown in the Form name button (without prepending a path or appending an extension). When writing, -w is appended instead of -r. The script must print the data to stdout if -r is specified, or must accept the data from stdin if -w is specified, separating columns with the field delimiter character and separating rows with newlines. If the delimiter or newlines appear in as part of a data string, it must be escaped with a backslash.

A comment can be specified that should give the name of the author of the form, or special caveats. The comment is displayed only in the form editor window.

Creating a Card

After the general setup is done, fields can be arranged on a card ``canvas'', which has the same size and layout as the final card will have, but doesn't look as nice and shows extra information. Fields appear as blue rectangular boxes, some of which are divided in the middle (depending on the field type). The current field, whose specification is displayed in the form editor window. A field can be moved by left-clicking somewhere inside the field (but not too close to an edge) and dragging. The size can be changed by dragging one of the four edges, and the divider can also be dragged. Fields should not overlap. The card canvas can be resized; fields should not overlap the canvas window edges.

The canvas is divided in two parts by a horizontal fat line. The divider can be moved vertically by dragging the little square that initially appears near the top right corner of the canvas. Everything above the divider is the static part; everything below the divider is the card part. The card part displays one row of the database if one is selected; this information changes frequently whenever a search is performed or a row is chosen from the summary.

The static part does not normally change, it is intended for static data such as the average of all fields, a chart displaying statistics, or buttons. This part is not entirely static because entering new cards or resorting the database may change data, but it is not bound to a particular card, and it remains accessible if no card is chosen. This makes it a good place to place form switch buttons that would otherwise become unavailable when no card is displayed.

There are several types of fields. Not all of them store data in the database; some are decorative or display computed information.

Each field has a number of parameters that depend on the type. The most important is the internal field name. It must be unique, except for choice fields which are grouped by assigning common internal field names. If the field references a database string, the internal field name also names the database string. The internal field name can be used in expressions to read the database string. For example, suppose you have a database of backup tapes, you may have an Input field with an internal field name capacity, and another Input field named used. You could then add a Print field whose Input Default expression is (_capacity - _used). The Print field then displays the remaining free space on each tape, even though the database only contains total capacity and used capacity. Another Print label may have an expression (sum(_used)), which displays a running total of all tapes' contents. sum is one of a group of functions that loop over all cards rather than just referencing the current card; see the Expression Grammar chapter for details. It is also possible to reference a database field for which there is no field description in an expression; in this case, the field is referenced by number. Fields in the database are numbered left to right, beginning with 0.

The next button in the form editor is the database column. It needs to be specified only for field types that display the column and allow entry into the column. These fields are ``windows'' into the database; there is normally one field for each database column. All fields that do not reference a database column are merely decoration, no change of the database is possible through such a decorative field (although the decorative field may read the database, as Print fields do). This relation between fields and database columns also serves to give a symbolic name to database columns; these symbolic names can be used in expressions by prefixing them with an underscore. (It is also possible to use the column number in expressions, but that is less convenient).

The main window has three parts, a summary, the static area, and the card. The summary contains one line per card, while the card contains the entire card's information as defined with the form editor and the card canvas. The static part is optional and programmed in the same way as the card. The Summary column and Width in summary buttons in the form editor determine which fields also appear in the summary; this is a subset of the fields that reference a database column (decoration fields can not be put into the summary). The two buttons specify the order in database column and the width in characters. Two blanks are inserted between fields in the summary automatically. The summary has a title; it can not be specified directly but is taken from the Label text of the field.

Here is a brief summary of all buttons in the form editor that specify a field in the card:

Some of the above accept expressions. An expression begins with a parenthesis, a brace, or a dollar sign. Everything else is a literal string. Parentheses and braces are numeric and string expressions, respectively; a dollar sign followed by an environment variable is a shortcut for the same sequence enclosed in braces. The system statement should be used sparingly, because some expressions (such as the grayed-out-if expression) are evaluated frequently. See the Expression Grammar section for details.

Buttons

There is a row of buttons in the form editor for various operations:

plan Interface

grok cooperates with the calendar manager plan, which is another freeware package by the same author. See http://www.bitrot.de for more information about plan. The standard FTP archive site is ftp://ftp.fu-berlin.de/pub/unix/graphics/plan.

Version 1.6 of plan and version 1.4 of grok support a simple mode of cooperation. plan can read databases created with grok and displays the information in various way in its calendar views. Version 1.9 of plan uses the new -p option of grok to read databases, which permits the use of the Shown in calendar if mode in the form editor, which can be used to show only active and unfinished todo items from a workplan database, for example. Previous versions always show all cards.

This is useful only for databases that are time-based, which means that they have at least one field of type Time with a subtype Date+time or Date. Currently, plan's IP server options are not available for grok; this will change in a future version. At this time, plan can only display but not modify grok data.

plan needs information about a grok database to know how to interpret the data. For this purpose, the calendar interface mode was introduced in the form editor. It allows the user to specify for each field of the database how plan should interpret it. One field must be marked Date+time or Date, and one field should be marked Note or Message so the entry can meaningfully be displayed in a calendar view.

The standard workplan application that comes bundled with grok is set up to display the finish dates of jobs in calendar views, along with the job title.