ossp-pkg/tabea/tabea-brainstorming
1.9
About structured editing
========================
Terminology
-----------
config - structure of the user interface configuration
template(s) - skeleton(s) of the output file(s)
data - file that contains the data chosen by the user
export(s) - file(s) actually written out by tabea.
import - legacy (manually edited) file to import data from
Files
-----
- config
Menu structure configuration of the user interface. Described in
more detail below under "Syntax".
- template(s)
Any ASCII file using lib_var syntax for variable expansion.
- data
A single file containing all data chosen by the user. Format is one
record per logical line which a name followed by an (optional)
value. A physical line be extended to a long logical line using a
trailing BACKSLASH just before the NEWLINE. Fields are separated by
SPACE.
- export(s)
One or more files being written out by tabea. It is/they are build
from template(s) by expanding the embedded variables using lib_var
and information from the data file. The output files are usually
write-only.
- import
A function may be provided to build a baseline of choices importing
a legacy file. This is typically the case when someone has
maintained such a file manually before it was taken under tabea
control.
Syntax
------
The configuration consists of one or more "blocks" which are
arbitrary collections of items.
Every block consists of one or more items describing the technical
and visible aspects of a single variable whose value is stored in
the data file. These values are also used when lib_var expands the
variables in template(s) for export.
Every item has one or more values describing the technical and
visible aspects of a user's choices to be assigned to an item.
block {
name (mandatory)
visible
description
helptext
helpurl
activate
item {
name (mandatory)
visible
description
helptext
helpurl
activate
match
verify
type
value {
name (mandatory)
visible
description
helptext
helpurl
activate
checked
selected
};
};
};
Elements common to blocks, items and values
-------------------------------------------
A name matches [a-zA-Z][0-9a-zA-Z]* and is used when reading and
writing the data file and when expanding variables in the
template(s) for export.
A visible description for humans can be specified. If omited, name
is used verbatim.
A helptext is a human readable text for the word "help". If omitted
and "helpurl" is set, it defaults to "help". If "helpurl" is omitted
no help link is shown at all.
The helpurl is the URL to a help page describing the item.
An activate condition can be specified to enable a block, item or
value. It is a little perl program and uses perl's "eval" to find
out the result
Elements used in items only
---------------------------
A match regex is used when importing a legacy file. When parts of an
imported file match the regex, $1 is used as the current value.
The verify is a regex to check if the data read or the user input is
valid. A "verify xxx" is a shortcut for "eval name =~ xxx". If used
together with eval both must match.
The eval is a little perl program and uses perl's "eval" to find out
the result. It is a more sophisticated method to check for valid
values. If used together with verify both must match.
The type field is explained below under "All types by example".
Elements used in values only
----------------------------
A name describes the default value.
The checked element is a flag to highlight the value in the menu.
The select element is a flag to highlight the value in the menu.
All types by example
--------------------
Possible types are taken from RFC1866, Section 8.1.2 - 8.1.4
8.1.2.1. Text Field: INPUT TYPE=TEXT
<p>Street Address: <input name=street><br>
Postal City code: <input name=city size=16 maxlength=16><br>
Zip Code: <input name=zip size=10 maxlength=10 value="99999-9999"><br>
item {
name street
visible "Street Address:"
type text
}
item {
name city
visible "Postal City code:"
type text[16][16]
}
item {
name zip
visible "Zip Code:"
type text[10][10]
value {
name "99999-9999"
}
}
8.1.2.2. Password Field: INPUT TYPE=PASSWORD
<p>Name: <input name=login> Password: <input type=password name=passwd>
item {
name login
visible "Name:"
type text
}
item {
name passwd
visible "Password:"
type password
}
8.1.2.3. Check Box: INPUT TYPE=CHECKBOX
<p>What flavors do you like?
<input type=checkbox name=flavor value=vanilla checked>Vanilla<br>
<input type=checkbox name=flavor value=strawberry>Strawberry<br>
<input type=checkbox name=flavor value=chocolate checked>Chocolate<br>
item {
name flavor
visible "What flavors do you like?"
type checkbox
value {
name vanilla
visible "Vanilla"
checked
}
value {
name strawberry
visible "Strawberry"
}
value {
name chocolate
visible "Chocolate"
checked
}
}
8.1.2.4. Radio Button: INPUT TYPE=RADIO
<p>Which is your favorite?
<input type=radio name=flavor value=vanilla checked>Vanilla<br>
<input type=radio name=flavor value=strawberry>Strawberry<br>
<input type=radio name=flavor value=chocolate>Chocolate<br>
item {
name flavor
visible "Which is your favorite?"
type radio
value {
name vanilla
visible "Vanilla"
checked
}
value {
name strawberry
visible "Strawberry"
}
value {
name chocolate
visible "Chocolate"
}
}
8.1.2.5. Image Pixel: INPUT TYPE=IMAGE
<input type=image name=point src=map.gif>
In a form this type allows an image to be used as a substitution
for a submit button.
<img alt=\"gif not found\" src=1.gif>
item {
name point
visible "Choose a point on the map:"
type image
value {
name "map.gif"
}
}
8.1.2.6. Hidden Field: INPUT TYPE=HIDDEN (FIXME do we really need this?)
<input type=hidden name=context value="l2k3j4l2k3j4l2k3j4lk23">
item {
name context
type hidden
value {
name "l2k3j4l2k3j4l2k3j4lk23"
}
}
8.1.2.7. Submit Button: INPUT TYPE=SUBMIT
<input type=submit name=recipient value=internal><br>
<input type=submit name=recipient value=world>
item {
name recipient
type submit
value {
name internal
}
value {
name world
}
}
8.1.2.8. Reset Button: INPUT TYPE=RESET
You may clear the form and start over at any time: <input type=reset>
item {
description "You may clear the form and start over at any time:"
type reset
}
8.1.3. Selection: SELECT
8.1.3.1. Option: OPTION
<SELECT NAME="flavor" SIZE="2">
<OPTION>Vanilla
<OPTION>Strawberry
<OPTION value="RumRasin">Rum and Raisin
<OPTION selected>Peach and Orange
</SELECT>
item {
name flavor
type select[2] //or type selectmultipe[2]
value {
name "Vanilla"
}
value {
name "Strawberry"
}
value {
name RumRasin
visible "Rum and Raisin"
}
value {
name "Peach and Orange"
selected
}
}
8.1.4. Text Area: TEXTAREA
<TEXTAREA NAME="address" ROWS=6 COLS=64>
HaL Computer Systems
1315 Dell Avenue
Campbell, California 95008
</TEXTAREA>
item {
name "address"
type textarea[64][6]
value {
name "HaL Computer Systems\n1315 Dell Avenue\nCampbell, California 95008"
}
}
Perl API
--------
$handle = new Tabea::Config ($config, $type, $prefix);
Reads $config and initializes items with default values.
Currently the only supported $type is "HTML2" which causes only
tags described in RFC1866 to be used. When a menu is rendered,
some elements may require uniqe names in a scope wider than
known by this module, i.e. when two configs are presented on one
screen or along with other information, so every item is
prefixed with $prefix.
$rc = $handle->load($data);
Reads $data and sets the value of items.
$rc = $handle->save($data);
Writes items including their values.
$rc = $handle->render($buffer);
Renders a menu and writes it into the buffer. The contents of the
buffer can be merged into a larger output. Values are verified
and invalid data is marked (FIXME how? red, reset to default,
configurable behaviour, configurable error messages ...) The
caller must finally print out the menu and when an input comes
back it must identify menu activity (i.e. by checking the
prefix) and call render again and again or execute some action.
$rc = $handle->import($legacyfile);
Reads a legacy (manually edited or previously exported) file and
tries to match out values.
$rc = $handle->export($template, $exportfile);
Applies variable substitution for a template and writes the
result out to exportfile.
$rc = $handle->destroy();
Issues:
- [rse] $type should be not on constructor, but on render() IMHO
- [ps] Agree. I think it is better to have the data in an internal
format and reformat the data at the time when the output is
produced.
- [rse] $prefix should be not on constructor, but on render() IMHO
- [ps] Perhaps I need $prefix for internal data saving.
[thl] agree on both. That came into my mind first but i thought a
switch between two types while the program is running will happen
almost never and having it fixed during the lifecycle of the
constructor might easy coding.
- [rse] if thinking about programming a CGI, it is not clear to me
how one has to process the POST data and inject it again
into the $handle object for re-rendering. I would expect
the reverse of render() for loading in the POST results.
I recommend: $rc = $handle->parse($type, $post_data);
$rc = $handle->render($type, $html_data);
- [ps] We must get the value POST data for updating the internal data
The idea of having the functions parse and render sounds good.
This way we get - load/save for internal/backend I/O
- parse/render for input-device-specific I/O
- import/export for output-device-specific I/O
[thl] agree. I was thinking about render() being a hybrid function.
Note that the main program's "outer loop" will - must - preprocess
POST data because it might contain information unrelated to render()
or parse(). But i agree there are definitly two functionalities so
it shouldn't hurt putting them in two separate functions. In fact,
it might remove some magic.
Example: Generic RAID configuration
-----------------------------------
block {
name BEGIN
visible "RAID configurator"
description "Please configure your redundant array of independent disks now"
helptext info
helpurl http://www.raid.org
activate #always
item {
name numdrives
visible "Number of drives [1...9]"
description "enter the total number of drives in the array including redundant and spare drives"
helptext ?
helpurl http://www.counting.org/basics
activate #always
type text[1]
defaultvalue 1
verify ^[123456789]$
eval $numdrives ~= ^[123456789]$
}
item {
name raidlevel
activate numdrives~=.
type radio
defaultvalue 0
value {
name 0
visible "RAID 0"
}
value {
name 1
activate numdrives~=^[2468]$ #even
}
value {
name 4
activate numdrives~=^[3456789]$ #>=3
}
value {
name 5
activate numdrives~=^[3456789]$ #>=3
}
value {
name 10
activate numdrives~=^[48]$ #multiple of 4
}
value {
name 1+HOT
activate numdrives~=^[3579]$ #odd AND >=3
}
value {
name 4+HOT
activate numdrives~=^[456789]$ #>=4
}
value {
name 5+HOT
activate numdrives~=^[456789]$ #>=4
}
}
}
block {
name END
visible "commit suicide now"
activate numdrives~=. && raidlevel~=^[0145](+HOT)?$
item {
name "Finish"
type button
}
}
Example: Jumpstart Disk and Raid Configuration
----------------------------------------------
block {
name BEGIN
visible "Disk Configuration"
description "Please configure the number of disks and the RAID"
helptext info
helpurl
activate #always
item {
name numdrives
visible "Number of drives [1...9]"
description "enter the total number of drives in the array including redundant and spare drives"
helptext ?
helpurl http://www.counting.org/basics
activate #always
type text[1]
(type popup_menu[1] )
defaultvalue 1
verify ^[12]$
}
item {
name raidlevel
activate numdrives~=.
type radio
defaultvalue 0
item
value {
name 0
visible "RAID 0"
}
value {
name 1
activate numdrives~=^[2]$ #even
}
}
item {
name sizeofdisk
}
item {
name slices
visible 'Slice definition'
item {
name slice0
visible "Definition of slice0"
item {
name size
visible "Define the size of sclice"
verify sizeofdisk - size0 - size1 ..... -size7 >= 0
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify # Depencies to other slices
}
}
item {
name slice1
visible "Definition of slice1"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify #
}
}
item {
name slice2
visible "Definition of slice2"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify #
}
}
item {
name slice3
visible "Definition of slice3"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify #
}
}
item {
name slice4
visible "Definition of slice4"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify #
}
}
item {
name slice5
visible "Definition of slice5"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify #
}
}
item {
name slice6
visible "Definition of slice6"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify #
}
}
item {
name slice7
visible "Definition of slice7"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7] # Dependencies to other slice types
verify #
}
}
}
}
block {
name pruefen
type submit
}
block {
name clean
type reset
}
block {
name END
visible "commit suicide now"
activate numdrives~=. && raidlevel~=^[0145](+HOT)?$
item {
name "Finish"
type button
}
}
