Instant Framework Manual
Instant Framework is a very simple, extraordinarily powerful markup language. Instant Framework allows a technician who knows SQL and html to rapidly create a direct web interface atop the underlying database, by cutting and pasting Instant Framework screens that work directly on these tables. Because Instant Framework screens are small and easily modified, the interface can be built very quickly. An interface can be built atop any database, including the datbase from an existing product or business system.
Web languages generally come in two flavors. Markup languages such as Cold Fusion or PHP insert their code within in special markup tags, which are then embedded in the html source pages. They suffer from the disadvantage that the page design and implementation code are both awkwardly intertwined. This can be especially troublesome when different people are maintaining the page design and its implementation code. Alternately, languages such as Java and Perl often embed the html page layout within the implementation code (a CGI script), which suffers from the reverse problem. Instant Framework, by comparison, is a template language. It separates the design and implementation code completely. Like a markup language, Instant Framework provides the designer with additional tags to insert into the html pages (_R_ tags). However, unlike markup languages, Instant Framework tags do not contain code (although some may contain SQL queries). Instead, they contain the data to be formatted. The designer can lay out the page using only _R_ tags, as if the data were present, and Instant Framework will fill in the data when the page is run.
Instant Framework tags begin with "_R_". While they are html files, Instant Framework pages are not viewed directly through the webserver. Instead, a formatting cgi, referred to as the "Instant Framework application", preprocesses the page. The application performs database queries, sets variables, and replaces variable tags in the page.
Instant Framework provides a small set of special predefined tags, and allows the page designer to freely create and use other tags.
The most basic Instant Framework tag is the replacement tag. Replacement tags consist of any simple word, prefaced with _R_ (for example, _R_USERNAME). These tags are not predefined by Instant Framework; they are defined by the page designer. As it runs, the application keeps an internal set of variables. Operations like setting variables inside _R_DEFAULT tags (discussed later) or performing SQL queries in _R_QUERY tags (also discussed later) cause Instant Framework to automatically load the data retrieved into a replacement tag. For example, this code:
_R_DEFAULT_START sort = last_name _R_DEFAULT_END
will cause Instant Framework to load the data "sort" into its internal variable set. The replacement tag "_R_SORT" appearing later in the page will retrieve it.
When html forms submit form values, those form values automatically become available through _R_ tags. This facility allows designers to chain together an application by passing data from one screen (page) to the next. For example, setting the hidden form variable "user_type" to "editor" will cause that variable to load into the application's variable set for the next page. The replacement tag _R_USER_TYPE appearing in the next page will, when processed by the Instant Framework application, appear as the string "editor".
In practice, most Instant Framework variables are set by the immediately preceeding page or by results retrieved from a SQL query. For example, this code:
_R_QUERY_START_ONE select user_id, last_name from person _R_QUERY_END
contains the special tag _R_QUERY_START, which tells Instant Framework to run a database query. After it runs the query, Instant Framework will then look for a paired _R_RESULTS_START tag and its _R_RESULTS_END tag with the same suffix the query had. The _R_RESULTS tags can be anywhere in the page being processed. For example, given the code above, Instant Framework will look for a block like this:
_R_REPEAT_START_ONE The user with last name _R_LAST_NAME has user id _R_USER_ID _R_REPEAT_END_ONE
Database programmers may recognize the _R_REPEAT_ construct as the analog of a database cursor. When it found the _R_QUERY tag, Instant Framework parsed the SQL within it and recognized select variables that it should automatically create replacement tags for. As it retrieves each result row from the database query, the Instant Framework engine will update the values accessed by _R_USER_ID and _R_LAST_NAME and rewrite the contents of the _R_REPEAT_ tag pair, replacing the _R_ variables. This facility allows the designer to lay out a report page, formatting a single row, and have Instant Framework fill in the report data from the defined query.
Instant Framework leverages its variable replacement quite extensively to allow designers to create complex applications using only a few simple tags, plus html and some SQL queries. Almost anyplace you can think to put a replacement tag, Instant Framework will recognize and process it. For example, you can use _R_ tags in the above SQL queries:
_R_QUERY_START_ONE select user_id, last_name from person order by _R_SORT _R_QUERY_END_ONE
Instant Framework will automatically SQL-escape variable replacements that appear in _R_QUERY tags. You can suppress this behavior by using the _RX_ prefix instead, which will suppress SQL-escaping:
_R_QUERY_START_ONE select learning_event_id, subject, topic, program, length, institution, presenter, format, recorded_date, completed_date from learning_event where _RX_FILTER_COL = _R_FILTER_SETTING _R_QUERY_END_ONE
In this example, _R_FILTER_SETTING will be escaped in single quotes, but _RX_FILTER_COL will not. This is often used to keep Instant Framework from replacing column names in the SQL.
You can tell Instant Framework to html-escape the variable replacement by using an _RH_ prefix instead of the normal _R_. HTML escaping will replace HTML special characters, such as & with &. URI escaping will replace these, and also characters such as spaces, suitable for including in a link.
<a href="learning?action=all_learning_events&filter_col=subject&filter_setting=_RI_SUBJECT">_RH_SUBJECT</a>
This is generally used when formatting a link, often in referring back to the application itself (in this example, to apply a filter).
The _R_OPTION tag is a special control-flow construct, similar to a "select" statement in C. If an option variable is defined, Instant Framework looks for a block with the matching option value and executes any SQL contained in it. For example, if a prior page defined the html form value "option" to be "delete", Instant Framework would execute the block below, if it were present in the page being processed:
_R_OPTION_START_DELETE delete from badnarik_person where person_id = _R_PERSON_ID _R_OPTION_END_DELETE
The OPTION tag can contain multiple sql commands separated by a semicolon; this will cause the Instant Framework to execute each command consecutively. If a command contains an insert, the tag _R_INSERT_ID will contain the row ID of the inserted row.
OPTION tags are executed before QUERY tags. Because of this, you can set an option that alters QUERY tags.
When creating forms that need data validation, Instant Framework provides two helpful features: required field tags and the _R_VALIDATE_FAIL_ACTION tag.
Any tag can be made required by using _R_REQ_ instead of simple _R_. For example, _R_REQ_FIRST_NAME. This tag will evaluate to "(*)", and is used in a form to give an indication of what fields are required. If the required field is missing, when reloaded, its _R_REQ_ tag will change to red, indicating to the user which required fields are missing.
The _R_VALIDATE_FAIL_ACTION tag indicates which page should be loaded by the application validation fails for the screen. It will override an action variable. Generally, it is used as follows: html FORM defines the Instant Framework application cgi as the html form action, and sets the a hidden form variable named "action" to tell Instant Framework which screen to show next. It also sets validate_fail_action in a _R_DEFAULT block to its own name to tell the Instant Framework application to reload the screen if validation fails.
The following is an example Instant Framework page named "enter_user_info":
<FORM action="/cgi-bin/email_application" method="POST"> <TABLE align="center" cellpadding="5"> <TR > <TD colspan=2">(*) indicates required field</TD></TR> <TR cols="2"> <TD align="right"><B>First Name _R_REQ_FIRST_NAME</B></TD> <TD align="left"> <INPUT type="text" name="first_name" size="40" maxlength="40" value="_R_FIRST_NAME"> </TD> </TR> </TABLE> <INPUT type="hidden" name="action" value="user_home_screen"> <INPUT type="hidden" name="validate_fail_action" value="enter_user_info"> </FORM>
The special variable gen_key (accessed as _R_GEN_KEY) contains a randomly generated 8-character sequence, regenerated each time a page is processed. It is intended for use as a database key or unique id.