Form Sets, Context Parameters, and menus

The Idea

While the fundamental shape of an SQL database is a square table, a lot of data can be better represented by trees; attached to one thing are many things. While trying to write a handler for a header-detail pattern, I found I could simplify and condense it to a menu button that carried forward an attribute from the current form being edited, i.e. parameter in a context.

Available form sets are maintained from the form_set button on the form developement submenu. Each form has a drop down menu to select one of the available form sets. This is entirely optional, a simple table does not need a form set.

A menu item can contain a list of context paramers. These are attributes from the pages PostgreSQL result set whose value are added as hidden form elements to the menu button. (Each menu button is its own html form.)

How it works

The form set contains a list if attribute names. When a form is assigned to be in a form set, the attribute names become context parameters.

A QZForms handler calls the function register_form() after creating an html form, whether the form is a menu item, a submit button, or a selection of one row out of many, the form must be registered after it is created. This creates a token called the form_tag that is added to the html form. A record in a hash table kept by the session contains an id extracted from the token, the action or URI that the token allows, expire times, and a reference to a form set if a form set has been specified.

After registering the form, the handler may call the function save_context_parameters(). This should be called for the main table action on a page. It is up the the handler to do this at the right time. This must be done before menus are built.

Saving the context parameters means creating a new form set record which contains a hash table of the values for the items in the form set definition. The attributes then have values.

There may be two form sets while QZForms is building a page, the one that has just been posted and the new one being built. If they share the same form set name then values from the posted one can be carried forward to the new one. As long as a sequence of pages share a form set name then a value in one is sticky and stays with the subsequent pages.

The value of a form set attribute is not allowed to change. The http post of a form may or may not contain the attribute, but if it does it must have the same value as was saved when the attribute was first encountered.

If the "main" form on a page has a form set name and attribute list specified, then a new form set record is created for the page being built. It will contain the value of any attribute in the posted form, or if an attribute has not yet been specified, its value can be taken from the PostgreSQL result set.

A menu item can specify that it is in a form set. If the menu item's form set name matches the form set name of the "main" form, then the attributes and values, or context parameters are saved with the menu item as an html hidden element.

What it does

Form sets enable context parameters, which in turn provide a way for one or more attributes of a primary key to be carried forward from one html page to the next. It allows "drill down" logic and header-detail forms.