This section is maintained in alphabetical order of all tags, attributes and options. These are cross-referenced by HTML links. The possible options for each attribute are given immediately underneath the attribute name. There may be several notes about the particular reference, and finally there is an example of common usage in a very minimal document fragment highlighting the reference. Please note that there may be more than one entry in this section with the same name, but with different context.
0|1-xxx
When a two-dimensional grid is being displayed, an extra column can be automatically generated with a sequential list of numbers beginning with 1. "autoRowNumber" needs to be set to the maximum number of rows to display. If "autoRowNumber" is set to "0", pabulumba will look for sub-elements named row, and use y-axis titles set by the user in the "display" attribute.
In the example, a maximum of twelve rows will be displayed.
<doc>
<form ...
<element name="anothergrid" type="grid" label="Updateable table" autoRowNumber="12" mandatory="y" source="user" permission="wwwr">
</form>
</doc>
A character may be any of a-z or A-Z.
A checkbox will be generated by pabulumba if given as the value in "type". Apart from the type, it requires few other attributes.
<doc> <form ... <element name="flew" type="checkbox" label="Flew: " mandatory="y" permission="wwwh"/> </form> </doc>
1-xxx
When a textarea is displayed on the page, "cols" represents the number of text characters wide visible.
<doc> <form ... <element name="comments" type="textarea" validate="sentence" label="Comments: " rows="5" cols="50" mandatory="n" maxSize="1000" permission="wwwr"/> </form> </doc>
A record of who did what when can be maintained using "keepHistory" and "showHistory". It might not always be desirable to record every single time the page is saved, but, in the case of a time-logging form, it may be. Setting "contiguousHistory" to "y" will allow records (either text, select lists, or text areas) to be recorded, even if the current setting/text is the same as the previous setting/text.
A date is checked for validity and the correct date-part separator as set in Settings
<doc> <form ... <element name="dateOfAction" type="input" validate="date" label="Date of action: " mandatory="n" maxSize="100" permission="wwwr"/> </form> </doc>
A decimal number is any combination of numbers 0-9 with or without a decimal point at any position except the first (i.e., use a leading zero if number less than 1).
<doc> <form ... <element name="cost" type="input" validate="decimal" label="Cost of item: " mandatory="n" maxSize="10" permission="wwwr"/> </form> </doc>
A default value can be given to any text input fields, including date fields. A date default may be either "00/00/0000", which is acceptable to MySQL, or the macro, "CURRENT_DATE").
It may also be set for any radio buttons or select list, but the value to be given here is the value in the "id" column of the relevant table in the database.
<doc> <form ... <element name="cost" type="input" validate="decimal" label="Cost of item: " default="0.00" mandatory="n" maxSize="10" permission="wwwr"/> <element name="date_ordered" type="input" validate="date" label="Date ordered: " default="CURRENT_DATE" mandatory="n" maxSize="10" permission="wwwr"/> <element name="date_required" type="input" validate="date" label="Date required: " default="00/00/0000" mandatory="n" maxSize="10" permission="wwwr"/> </form> </doc>
Name of database column to be selected
When a select or radio button list is chosen as the "type", it gets its source data from a database table. The "display" attribute tells pabulumba which column values to show in the output on the screen.
<doc> <form ... <element name="bird" type="select" label="Bird name: " mandatory="y" source="bird" display="birdName" filterKey="birdgroup" keepHistory="n" showHistory="n" permission="wwwr"/> </form> </doc>
When a two-dimensional grid is displayed, the choice can be made to use autoRowNumber or provide a list of row labels to use. The number of rows displayed is automatically limited to the number of row display headings provided. These are supplied within the "element" element:
<doc> <form ... <element name="grid" type="grid" label="Updateable table" autoRowNumber="0" source="user" selectCriteria=" and id > 0" mandatory="y" permission="wwwr"> <field name="username" display="User name" validate="sentence" maxSize="20"/> <field name="fullname" display="Full name" validate="sentence" maxSize="20"/> <field name="email" display="Email address" validate="email" maxSize="40"/> <row display="UserOne"/> <row display="UserTwo"/> <row display="UserThree"/> <row display="UserFour"/> </element> </form> </doc>
The doc tag name is short for document, and is the base element for pabulumba's XML configuration files. It must be present as the opening tag in the document, and as the closing tag. It never has any attributes, but can have several children:
It does not matter what order these are put onto the page; pabulumba will place them onto the web page according to the XSL file processing instructions. The default order is page, menu, form, switches, links.
<doc> <page heading="Accounts payable entry screen"> ... <menu ... </doc>
It has been suggested that it was stupid to have an element of the form called element. Nevertheless, that's just the way it is. It has lots of attributes, and they change, depending upon user choice. It requires:
If type is select, it may also require the following attributes:
If type is radio, it may also require the following attributes:
If type is textarea, it may also require the following attributes:
If type is input, it may also require the following attributes:
If type is grid, it may also require the following attributes:
... and it will require the following sub-elements:
A simple email address can be validated against to attempt some checking of input in this field.
<doc> <form ... <element name="emailaddress" type="input" validate="email" label="Email address: " mandatory="y" maxSize="10" permission="wwwr"/> </form> </doc>
A two-dimensional grid needs to be instructed which fields to fetch and display from the database. The attribute "maxSize" of sub-element "field" can override the "maxSize" in the source form to assist in fitting the data across the page.
<doc> <form ... <element name="grid" type="grid" label="Updateable table" autoRowNumber="0" source="user" selectCriteria=" and id > 0" mandatory="y" permission="wwwr"> <field maxSize="20"/> <field maxSize="20"/> <field maxSize="40"/> <row display="UserOne"/> <row display="UserTwo"/> <row display="UserThree"/> <row display="UserFour"/> </element> </form> </doc>
pabulumba will turn this type into a textbox showing/allowing the name of an uploadable/downloadable file and a Browse button, which will allow the user to browse their own file system to select a file to upload.
A setting will also toggle whether icons will be displayed for common file types.
y|n
If your application is available to a lot of users, perhaps spread across multiple organisations, all of whom enter extremely similar information, and you would like them to enter the information into the same table, yet not see each other's records, filterByUser must be turned on. It relies upon some further functionality in the system. The table to be filtered by the user must contain a select list called for example supplier, then a table containing the following fields must be created (in the normal way one would create an pabulumba table)
Users must then be allocated to a particular supplier via an pabulumba form. Once this is done, users will be restricted to viewing and creating records only for that supplier. This restriction also holds true for the automatically-generated reports, but not the custom reports (which are sufficiently flexible to cater for this in any event).
Where filterSelectOptions has been given as an argument to the javascript in Element A, the element on the page (Element B) that is controlled by Element A needs a column in its database table with the name of the argument given to "filterKey". In this example, "birdgroup" controls the contents of "bird", so the "bird" table must have a column called "birdgroup", and this column must represent which birdgroup each bird belongs to. TODO give screenshot of database and Maintenance screen.
<doc> <form ... <element name="birdgroup" type="select" label="Bird group: " mandatory="y" source="birdgroup" filterByUser="y" display="birdGroupName" javascript="filterSelectOptions(this, "bird");" keepHistory="n" showHistory="n" permission="wwwr"/> <element name="bird" type="select" label="Bird name: " mandatory="y" source="bird" display="birdName" filterKey="birdgroup" keepHistory="n" showHistory="n" permission="wwwr"/> </form> </doc>
A select list (Element A) can control the content of one or more select list(s) (Element B, Element ...). There is a small amount of additional setup, and a choice to be made whether the relationship between Element A and B, ... is set up in a key in Element B's table (see filterKey), or in a special table (see filterTable) with a many-to-many relationship, named A_B (substitute names of tables for A and B).
<doc> <form ... <element name="birdgroup" type="select" label="Bird group: " mandatory="y" source="birdgroup" filterByUser="y" display="birdGroupName" javascript="filterSelectOptions(this, 'bird');" keepHistory="n" showHistory="n" permission="wwwr"/> <element name="bird" type="select" label="Bird name: " mandatory="y" source="bird" display="birdName" filterKey="birdgroup" keepHistory="n" showHistory="n" permission="wwwr"/> </form> </doc>
As above in "filterKey", but a specific table may be set up to control the relationship between birdgroup and bird; in the above example, this table should be named "birdgroup_bird", i.e. the table should be named with the controlling element name followed by an underscore followed by the name of the controlled element.
The form element represents a single database table. It is the container for fields (named in pabulumba as elements) in a web form:
<doc>
...
<form name="sighting" showId="y" showNavButtons="y" ... >
...
</doc>
It also has several attributes:
A two-dimensional grid can be displayed with the ability to directly modify the contents instead of having to go to the Maintenance screen to do so. It can only display and manipulate text contents at this stage, but it makes for a convenient way to manually change more than one record at a time. If the permissions are set to read-only for the current user, the presentation of the grid will change from input boxes to straight text output. It is the only element which has sub-elements as well as attributes:
A heading is the text drawn by pabulumba immediately underneath the menu, immediately above all other elements, and should describe the form / database table / purpose of the page.
<doc> <page heading="Accounts payable entry screen"> ... <menu ... </doc>
min|max|new
When a form is first selected, it can be directed to move directly to one of the first record, the last record, or a new record respectively.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>
The use of input will construct a rectangle into which text can be entered and then saved. This is probably the most common element on a form.
An integer is any combination of numbers 0-9 up to the size set in maxSize
Javascript is required to make the browser do some tricks without having to go back to the server to change something on the page. At this stage, the only argument for javascript is:
A record of who did what when can be maintained if this attribute is set to "y". These records can be kept as an audit trail in the database, or can be displayed next to each field with the attribute showHistory.
A label is the text displayed to the left of an input element inside a form. The font size can be modified by changing the XSL file in pabulumba. If the element has been made compulsory using the mandatory attribute, an asterisk will appear at the right-most extremity of the label text.
A link is designed to access other web pages or other parts of pabulumba. It has two attributes
<doc> <page heading="Accounts payable entry screen"> ... <menu ... <links> <link label="Google" value="http://www.google.com.au" /> </links> </doc>
A links tag (which is just a container) can have only one child:
<doc> <page heading="Accounts payable entry screen"> ... <menu ... <links> <link ... </links> </doc>
y|n
If set to "y", specifies that a field is required to be completed. If left blank, the validation process will catch this before it attempts to write to the database, and the user will be prompted to complete the field. It can also be specified for fields that cannot be validated, such as select or checkbox fields, but in these cases can only act as a visual clue to remind the user it is an important field.
{User_supplied_integer}
This attribute sets the maximum length of an input field OR the number of bytes which can be uploaded as a file.
A menu tag (which is just a container) can have only one child:
<doc> ... <menu> <menuItem xml="switchboard" xsl="entryForm5" permission="wwww">Main</menuItem> <menuItem xml="sightingEntryForm" xsl="entryForm5" selectCriteria="" permission="wwww">Sightings</menuItem> <menuItem xml="reports" xsl="entryForm5" permission="wwwr">Reports</menuItem> <menuItem xml="maintenance" xsl="entryForm5" permission="wwwr">Maintenance</menuItem> <menuItem xml="help" xsl="entryForm5" permission="wwww">Help</menuItem> </menu> ... </doc>
A menuItem is the tag name for an element which produces a clickable button to take the user to another page / menu / location. There are three attributes of a mennuItem:
<doc> ... <menu> <menuItem xml="switchboard" xsl="entryForm5" permission="wwww">Main</menuItem> <menuItem xml="sightingEntryForm" xsl="entryForm5" selectCriteria="" permission="wwww">Sightings</menuItem> <menuItem xml="reports" xsl="entryForm5" permission="wwwr">Reports</menuItem> <menuItem xml="maintenance" xsl="entryForm5" permission="wwwr">Maintenance</menuItem> <menuItem xml="help" xsl="entryForm5" permission="wwww">Help</menuItem> </menu> ... </doc>
This name should always match the name of the database field it represents.
<doc>
...
<form name="sighting" showId="y" showNavButtons="y" ... >
...
</doc>
Use this validation type only when testing.
The argument given to this attribute is a MySQL sub-clause beginning with a space i.e.: " order by [column name(s)] [ASC|DESC]".
A page tag can have two attributes
<doc> <page heading="Accounts payable entry screen" permission="wwrrhh"/> ... <menu ... </doc>
It could be successfully argued that "page" should be a container for everything else, rather than just a stand-alone tag. The argument for it being stand-alone is that it makes the path to the form - the most referenced object - one element shorter.
The permission string is simultaneously the most flexible of pabulumba's elements and the most annoying. In order for every element within pabulumba to be tested against the current user's role's access level, every element requires a permission string. If a user's role's permission level changes, it is necessary to change every permission string throughout the application. The moral of this lecture is: plan permissions carefully!
There are a number of system tables (which should never be removed from pabulumba) which assist with security:
A user must be assigned a role; a role is assigned a role reference number, which is the numerical position within the permission string (starting count at 1). An example would be user John Doe, who is given System Administrator rights. System Administrators have the role SysAdmin, which has a role reference number of 1, which means that in a permission string of "wrrrrhhhhh", they are the only users with permission to read and write the element with that permission string. Users with a role with a role reference number of 2-5 may only read the data, and role reference numbers 6-10 cannot see that element at all.
The permission levels are:
Note that permission levels can create some complications. If a form has an element hidden for some users who nevertheless have to create a new record, it must have a default value to be written to the database. If a form has a read-only element, the user should not be able to create a new record, as this would imply a value can be set for this field. The permission settings for the page element override those of each element; this is so that a form can be quickly taken off-line if necessary, or levels of permissions changed without having to make the individual changes to every element's permission string.
<doc>
<page heading="Accounts payable entry screen" permission="wwrrhhhhhhhhhhhh">
...
<menu ...
</doc>
y|n
If set to "y", pabulumba will create a text box which enables the user to pass an argument through to a parameter in a process. An example of this would be the process JumpToIdNumber, which allows the user to jump directly to the id they enter into the text box.
<doc> <switches> <switch xml="projectEntryForm" xsl="entryForm5" action="processJumpToJobIdNumberFromProject" processParam1="y" useCurrentId="y" permission="wwwr">Search for Job ID number</switch> </switches> </doc>
This will create a radio button.
The most left hand column of a grid will show the values of the attribute "display" for each row sub-element. This works in conjunction with field.
<doc> <form ... <element name="grid" type="grid" label="Updateable table" autoRowNumber="0" source="user" selectCriteria=" and id > 0" mandatory="y" permission="wwwr"> <field maxSize="20"/> <field maxSize="20"/> <field maxSize="40"/> <row display="UserOne"/> <row display="UserTwo"/> <row display="UserThree"/> <row display="UserFour"/> </element> </form> </doc>
Specifies the number of rows visible in the textarea presented to the user. This works in conjunction with cols
If decimal is used as a validation type, then the scale can also be set (e.g. scale="4"). The precision comes from the maxSize parameter. If scale is not set, the default is 2.
Creates a select list (drop down list) on the page.
When present, this will filter the output presented to the user. It should be a MySQL clause preceded with a space. i.e. " and username like "%office%". The "where" clause already exists.
The macro "CURRENT_USER" may be added into the select criteria, and will be replaced with " and id = {the id of the current user}".
Any characters available on a US keyboard can be entered into an input area validated against sentence.
y|n
If set to "y", the Delete button will be enabled. Clicking Delete attempts first to delete the current record, but if the record has been used anywhere as a lookup value (perhaps for select or radio types), it will only logically delete the record - i.e. tick the Deleted checkbox for that record. That record, although remaining visible in existing references, will no longer be available for new records.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>"
y|n
If set to "y", the current record will be copied to the end of the record set. A setting TODO supply name of setting - governs whether the new record becomes the current record, or the current record stays the duplicated one.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>
y|n
This works in conjunction with the attribute keepHistory. If this attribute is set to "y", the audit records for each change made to the contents of this elements will be displayed immediately prior to the element itself.
y|n
If set to "y", the automatically generated record number in the database will be displayed. This number can be useful when wishing to jump randomly between records.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>
y|n
If set to "y", the navigation buttons <<, <, >, >> will be displayed. These are used respectively to directly access the first, previous, next, and last records in the current set of records.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>
y|n
y|n
If set to "y", the New button will be enabled. Clicking New creates a new blank record.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>
y|n
If set to "y", the Save button will be enabled, and the current record will be committed (if without error) to the database.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>
y|n
If set to "y", the current record number is displayed against the total number in the recordset. These numbers will change depending upon the user's access to all/partial records.
<doc> ... <form name="sighting" showId="y" showNavButtons="y" showSaveButton="y" showNewButton="y" showDeleteButton="y" showDuplicateButton="y" showXofXX="y" initialId="max"> ... </doc>
The name of the table that is the source of the data used in a select list or radio listing.
It can also be a comma-separated list of items to be selected from that will never change, or only ever be added to, and not rearranged, such as "Yes, No" or "1,2,3,4". It is the position in the comma-separated list which is stored in the database, not the actual value, so if the position changes, the output will be different.
In the first example, the element with the name of "birdgroup" has a type of "select", so it is going to display a select list, or drop down list. It gets its data from the table referred to in the attribute "source" - also named "birdgroup". The display field tells pabulumba which column's data to display from the table named "source".
<doc> ... <element name="birdgroup" type="select" label="Bird group: " mandatory="y" source="birdgroup" display="birdGroupName" permission="wwwr"/> ... </doc>
In the second example, common options are displayed without having to resort to building a table. This should only be used for options which are never going to change, or can be appended to; they should never be changed around. Note that there is no longer any need for a "display" attribute.
<doc>
...
<element name="birdgroup" type="select" label="Bird group: " mandatory="y" source="Parrot,Finch,Bird of prey" permission="wwwr"/>
...
</doc>
The name of the table which is the source of the data displayed in a two-dimensional grid.
<doc> <form ... <element name="grid" type="grid" label="Updateable table" autoRowNumber="0" source="user" selectCriteria=" and id > 0" mandatory="y" permission="wwwr"> </form> </doc>
A switch is similar to a menuItem in that clicking it will take you to the target specified in the switch.
<doc> ... <switches> <switch xml="sightingEntryForm" xsl="entryForm5" action="display" selectCriteria=" where id < 40" permission="wwww">Enter sightingsswitch> </switches> ... </doc>
A switches tag (which is just a container) can have only one child: switch
<doc> ... <switches> <switch xml="sightingEntryForm" xsl="entryForm5" action="display" selectCriteria=" where id " permission="wwww">Enter sightings<switch> </switches> ... </doc>
This will create a textarea on the page with the following attributes:
<doc> <form ... <element name="comments" type="textarea" validate="sentence" label="Comments: " rows="5" cols="50" mandatory="n" maxSize="1000" permission="wwwr"/> </form> </doc>
select|radio|input|grid|textarea|file|url|checkbox
A type specifies the nature of the element drawn on the page. Each element may be one of type:
<doc> ... <element name="observeddate" type="input" ... /> ... </doc>
y|n
If set to "y", the SQL which generates the database automatically is instructed to make this field unique across every record, similar to an index. Once the SQL has generated the database framework, this setting cannot be turned off; the database must be manipulated directly with SQL.
pabulumba will turn this type into a textbox showing/allowing the name of an uploadable URL. A single record may have multiple URL attached.
A setting will also toggle whether icons will be displayed for common file types.
y|n
If set to "y", pabulumba will pass the id of the record in the current form into the destination form identified in the xml attribute. An example of this would be a process where the current record, just "data" at this stage, is turned into a printable invoice.
<doc> <switches> <switch xml="projectEntryForm" xsl="entryForm5" action="processJumpToJobIdNumberFromProject" processParam1="y" useCurrentId="y" permission="wwwr">Search for Job ID number</switch> </switches> </doc>
none|sentence|integer|decimal|character|date|email
Input text fields (of type input and textarea) can be validated against the following validation styles:
{User-supplied name followed by "EntryForm"}
When a user creates a new XML configuration file e.g. for an invoice or a payment, it should be named "invoiceEntryForm.xml" or "paymentEntryForm.xml", and should have no spaces in it. The parameter given to "xml" should be the name of the file without the ".xml" at the end. This file is located in the root directory wherever pabulumba is installed.
{Name of .xsl file which can be modified by the user}
The current name of the default .xsl file in pabulumba is "entryForm5.xsl". This file may be modified by a user who has some knowledge of HTML and XSL, and is the most convenient way to create an individual look and feel for the current application. This file is located in the root directory wherever pabulumba is installed.