NAME
prompt – web forms for data entry and editing
DESCRIPTION
prompt files are text files whose names end with ‘.prm’. ubprompt uses these files to generate data entry and edit screens.
prompt files are divided into sections. Each section commences with a capital letter and is terminated by a line starting with a ‘>’. Some sections have subsections in which case there may be more than one line starting with a ‘>’ before the end of the section.
PROMPT SECTIONS
BACKGROUND
DEFINITION
B
<Page top>
>
<Page middle>
>
<Page bottom>
>DESCRIPTION
Background Text is divided into 9 regions on the screen. Top, middle, and bottom (separated by ‘>’ lines) and left, centre and right on each line (separated by ‘#’ characters).
PROGRAMMED FUNCTION KEYS
DEFINITION
F {E} {R} <key>{<field>}<label>
{<help>}
>
<command>
>
DESCRIPTION
Execute this command script to execute when the function key is pressed or the button on an html form is clicked.
The default script language is tcl. This can be overriden by starting the script with #!<interperter>. eg #!/bin/bash
The input fields can be referred to by enclosing the field name in [ and ‘]’. The value entered in the form will be substituted in the command script.
Optional E indicates all fields on the screen are to be erased after executing the command. The current input field is reset to the first field on the screen.
Optional R indicates that the screen is to be repeated i.e. without R, command is executed and ubprompt exits. With R, command is executed and then returns to prompt screen.
Bind this command to function key <key>. This is not optional. key is in the range 1 to 8.
field is optional. If given the standard output of command is captured and placed in field.
label is the label to display on the function key labels at the bottom of the screen or in the html element with id=”functionKeys” id. Only the first 6 characters are significant for terminal sessions. html forms can have longer labels and the can be enclosed in ” to allow spaces in the label.
EXAMPLE
FR1 [user] USER
USER NAME
Use F1 to put your login name in the user field
>
#!/bin/bash
who am i | awk '{print $1}'
>HELP MESSAGES
DEFINITION
H {name)
<help>
>
DESCRIPTION
Help message for menu. See help (4) for format.
POPUP MENUS
DEFINITION
M {B} {<row> <col>{:<users/groups>{:<menu name>}}}
{<help>}
>
{<heading>}
>
{<option>}
>DESCRIPTION
Pop-up menu. See menu (4) for format details and the Checkpoint Programmers manual.
DATA ENTRY SCREEN
DEFINITION
P
{<field def>}
...
>
{<input screen>}
>DESCRIPTION
This consists of two parts (subsections). The first is the input field definition and the second is the form definition.
field def is a list of field definitions using the same format as the dictionary format (see dictionary (4)).
input screen is an input screen in the same format as a master file screen. The fields defined by field def are accessible by enclosing the field name in ‘[‘ and ‘]’.
EXAMPLE
P
#LIST USER PROCESSES
user, 8
#USER'S LOGIN ID
>
#PROCESS LIST FOR USER
-
USER LOGIN ID: [user]
>FIELD INITIALISATION
DEFINITION
S
<field> <expression>
...
>DESCRIPTION
Set input field to initial value.If field is blank or zero, copy expression into field. This is used to an initialise a value.
FORM TITLE
DEFINITION
T{1..6} <title>
DESCRIPTION
Displays a form title.
On terminals this is a highlighted bar on the top of the window.
On Web forms this is a header tag at the start of the form. The option number following the T can be used to specify h1, h2, etc.
VALIDATIONS
DEFINITION
V{1. .8X}
<expression>
<message>
...
>DESCRIPTION
All the expressions must be true before the execute script will be run. If an expression fails, message is displayed and the user is returned to the screen to correct their mistake.
WARNINGS
DEFINITION
W{1. .8X}
<expression>
<message>
...
>DESCRIPTION
All the expressions are expected to be true. If one fails, then message is displayed and the user can accept or reject the warning by selecting the “OK” or “NOT OK” function keys.
INPUT DEFINITIONS
This subsection defines all the fields and help messages to be collected on the screen.
FIELD DEFINITIONS
Each field definition is a single line of text with three fields. Each field is separated by a space(s). Refer to dictionary (4) and type (4) for format details.
HELP MESSAGES
There are two kinds of help messages in the input table. There are form help and field help. Help messages are a set of lines starting with ‘#’ where the rest of the line(s) is the help message.
VALIDATIONS AND WARNINGS
These have the same format and work the same way as validations and warnings in ubmulti.
UBPROMPT AS A WEB FORM
One of the most important uses of ubprompt is to generate web forms.
Ubprompt is comprehensive in that it includes the form, the field definitions, and the scripts in a single source file.
Some notes:
- Function keys. These are displayed in a div with the id “functionKeys”. If it exists in the html it is used, if it doesn’t exist it is created at the end of the html.
- The automatically created div “functionKeys” has a class “fkey”. The look and feel of the function key div can be skinned in the application .css using this class.
- The function keys themselves are buttons of class “ubprompt”. Again css can be used to skin the buttons.
- Function key buttons can be completely replaced by something with an id of KEY_F. There is a javascript function “submit_form” that can be used with onclick to activate the function key. e.g. <button id=”KEY_F1″ onclick=”submit_form(‘KEY_F1’);”><img src=”…” /></button> . In this case the button can be anywhere on the screen, not just in a row at the bottom.
- The output from the ubprompt scripts will normally replace the current page. However it can be directed to a new window (WINDOW= option to ubcgi) or a specific div (ID= option to ubcgi).
- The T (title) section defines the page heading (an h1 element).
The basic html structure up to and including the body tag are output by ubprompt. The closing body and html tags are also output by ubprompt.
DEPENDENT FIELDS IN WEB FORMS
In general ubprompt will create drop down lists for foreign keys in the attribute list for a form.
Sometimes the content of a drop down list is dependent on a value selected in another drop down list. ubprompt considers these to be dependent attributes or fields and provides special management functions for them.
To indicate that a drop down list has a dependent field use the special element attribute “subFields” and/or “subSelect” in the surrounding element.
subFields
The subFields attribute has a space separated list of input attributes as it’s content.
eg consider this snippet from a prompt file
P
customerId, 6 Fcustomers [name]
costCenterId, 6 FcostCenters [description]
>
<table>
<tr><td>Customer</td><td subFields="costCenterId">[customerId]</td></tr>
<tr><td>Cost Center</td><td>[costCenterId]</td></tr>
</table>
>
When this displays, the customer list will be a normal drop down list while the cost center list will be empty. When a customer is chosen the related cost centers will then become available for selection.
To get the subfield list ubprompt calls the server and runs a report called “select.<attribute>.rep”. eg select.costCenterId.rep. This report should return the content-type text/json.
The JSON format per record is
{"master":"",
"subValue":"",
"description":"",
"autofill":{
"attribute 1":"",
...
"attribute n":""
}
}
Worked example:
{"master":"[customerId]",
"subValue":"[costCenterId]",
"description":"[description:T]",
"autofill": {
"x":"[x]",
"y":"[y]"
}
}
The full example needs a few other things to make the list look correct and for the JSON to be correct – select.costCenterId.rep:
: costCenter
K customerId,description
H
\[
{"":""},
>
F
{"END OF DATA":""}
]
>
R
... as above
>
subSelect
subSelect is an array of JSON objects that does the same thing as subFields but with more control.
The report is not fixed. It is defined as one of the object attributes.
Inputs can be passed to the report which can then modify the results from the report.
eg
<tr><td>RANGE</td><td subSelect=’\[{“field”: “packId”, “report”: “select.packId”}, {“field”: “style”, “report”: “select.style_seasn”, “inputs”: \[{“input”: “season”, “value”: “$SEASON”}]}]’>[range]</td></tr>
In both cases the available options to a select element are restricted by the value entered.
In the example the value chosen for [range] will restrict the values available to packId and style.
subSelect is an array of JSON objects.
- field is the target ubprompt field. Assumed to be a SELECT.
- report is the application report that generates the option values in the same format as subFields report
- inputs (optional) is an array of input value objects for the report.
If inputs is present the report is called with the -i flag and the inputs array is passed as lines to the report in the form: <input>,<value>. eg season,$SEASON
AUTOFILL
Use autofill to populate forms with values.
Autofill is indicated by the attribute “autofill” in the td element that holds the foreign key field. eg
<td autofill>[someInput]</td>When “someInput” changes a report returning json is called. This is similar to “subFields”.
The report is called autofill.someInput.rep.
The json returned is a simple list of keys and values. The key is the id of an element while the value becomes the content of the element.
autofill first looks for an input element. ie id is INPUT_key. eg INPUT_quantity. If that can’t be found autofill looks for the plain id key.
Example report – autofill.customer_id.rep
: customer
K customer_id
H
{
>
F
}
>
R
"type": "[customer.type]",
"priceType": "[customer.type]",
"telephone": "[customer.telephone]",
"mobile": "[customer.mobile]",
"invoiceEmail": "[customer.invoiceEmail:T]"
>When the field customer_id changes the fields type, priceType, telephone, mobile, and invoiceEmail
autofill works with the set option. If you are using a form to edit a record and need headings based on a field the use S to set a value and autofill to set the headings.
Note that autofill can be used on a hidden element to give the required effect without the autofill value being displayed.
If the element id has the value “autofill hide” then instead of setting the value of the element the parent element will be hidden using style.display = “none”.
AUTOHIDE
autohide=”id1 id2 …” can be used to hide (set display to none) the listed elements when the autofill element value is “autofill hide”.
Example
P
vendorSizesId, 6 FvendorSizes
sizeRange, 3 Fsizes [description]
{#23,
US_#, 4
UK_#, 4
EU_#, 4
#}
>
<div class="prompt" id="dialog-box">
<table class="text">
<tr class="hide"><td autofill>[sizeRange]</td>{#23,<td><span id="hide_range_#"></span></td>#}</tr>
<tr class="bold"><td></td>{#23,<td><span id="range_#" autohide="US_# UK_# EU_#"></span></td>#}</tr>
<tr><td>US</td>{#23,<td>[US_#]</td>#}</tr>
<tr><td>UK</td>{#23,<td>[UK_#]</td>#}</tr>
<tr><td>EU</td>{#23,<td>[EU_#]</td>#}</tr>
</table>
</div>
>
SEE ALSO
dictionary (4)
help (4)
menu (4)
screen (4)
type (4)