Form Design: Using Repeat Tags

When designing forms, you’ll often encounter repeating data.  Repeating data can be found in the Example form shown earlier in this document.  A discussion of the use of tabs and rulers to model repeating data can be found earlier in this document.

Repeat Tags

Repeat tags allow you to declare that a section of your OpenOffice document should repeat based on the number of rows of repeating data.  An obvious application of this feature is to create a table row that is declared to repeat for as many rows of transaction data that are sent from the host.

Using tables instead of tabs and rulers to model repeating data gives a great deal of control and flexibility to the forms designer.  We have designed our repeat tags with the goal of allowing the programmer on the MultiValue host to be able to send data to a template without concern about how it will be formatted.  Our goal is to embed all formatting rules and directives into the document template and have none of the rules in the MultiValue server applications.

By keeping data separated from presentation, programmers can freely send data to the Blue Prairie Forms engine without concern about how that data will be formatted, paginated or styled.  The forms designer, using standard OpenOffice, can embed elements into the form template to control the presentation and styling of the data.

Syntax of a repeat tag

{repeat=<element>;block=<blockname>;increment=<number>}

Example

{repeat=tr;block=det;increment=12}

Example within a OpenOffice Table Row

Qty

UOM     

Shipped 

Line

Part Number

Desc     

%d.amt  

{repeat=tr;block=det;increment=12}%d.qty%

                       

%d.uom%

                       

%d.qtyShipped%

                       

%d.line%

                       

%d.partNo%

%d.partNo2%

                       

%d.desc%

%d.desc2%

                       

%d.amt%

                       

 The data being sent from the application for each %tag% in each cell, is as associated multivalue array.  The application generating the mutlivalue arrays declared that the group together would be called ‘det’ (for detail).  You’ll see this name in the block= directive in the first data column of the above table. 

Breaking down the example in the first column

Note: elements are separated by semicolon (;)

Element

Purpose/Function

repeat=

Tells Blue Prairie Forms the odt document element to repeat.  In the example above, the value tr is assigned. The value tr means ‘table row’.  When tr  is specified Blue Prairie Forms will duplicate (repeat) everything from the table row start tag  that precedes the {} declaration to the table row ending tag that follows the {} declaration.  The number of rows created is equal to the number of mulivalues in the first tag associated with the block ‘det’ unless the number of repeats is overridden using the optional ‘increment’ parameter described below.

block=

Tells Blue Prairie Forms the block that will be associated with this repeat.  A block is a name given to a collection of tags to declared them associated together.  In the example above, each of the tags found in the table row to be repeated have been declared to be part of the ‘det’ (detail) block.  When using the Blue Prairie Forms API, you’ll pass a tag name and a value associated with that tag.  You’ll also pass the block-name you wish to have associated with the tag and its value (see bpi.form.tagval2() subroutine in the API.

increment=

This parameter is optional but if used, must be numeric.  Without it, Blue Prairie Forms will repeat the repeated odt document element for precisely the number of multivalues counted in the first tag/value of the declared block.  If increment is specified and it is a number greater than 1, then the number rows generated will be the next higher multiple of increment greater than the actual number of multivalues in the first tag of the block.  For example, if you always want 12 rows on every page of your table, then set increment to 12.  If 20 the first tag/val set in the block hold 20 multivalues, then 24 rows (the last 4 being blank) will be generated.  If 42 multivalues and increment is 12, then 48 rows will be generated with the last 6 being blank.  This capability allows you to create forms with a fixed number of table rows (a grid) that will be consistent across all pages of the document including the last page.  Without this, the last page would contain only the number of rows required to finish the actual data rows leaving non-grid white space below the table (this is the default behavior).