|
Tech Tips - Part I
UnForm
Using Text-Anchors for Relative Enhancements
INTRODUCTION
A big
part of UnForm’s popularity is its dynamic page enhancement capability.
It contrasts with more “static” processing models that deal only with
“stationary” text or text elements on forms, or put another way, models that
deal only with text that is always found in exactly the same position on every
page.
Mastering
the relatively simple graphical concepts involved with UnForm’s dynamic page
enhancement features can speed up your forms development efforts, and in some
cases open up channels for additional forms development which can enhance either
the professionalism of document output or the productivity of work-flow, or
both.
BASICS
-
“Anchoring”
is a term employed for using the “relative” version of
many of UnForm’s enhancement commands, like font, box, shade, and text.
-
The
term “relative command” is used to refer to the version of
an UnForm command where a quoted text search string, also known as a
“text anchor”, is specified as the first argument.
-
The
location on the page for applied enhancements, rather than being absolute,
is relative to the position of the text search string, using it as an
anchoring point.
-
A
text anchor as the first argument after the command verb tells UnForm to use
anchoring logic for determining the position for enhancements.
-
The
pair of arguments after the text anchor give the offset points, or starting
points, for the particular enhancement being applied.
To
illustrate using examples:
“Absolute” version of commands:
font
2,2,14,1,univers,18
box 1,1,50,4
text 2,3,{“For customer”+custname$},univers,18
-
In
the absolute commands the exact page column and row starting coordinates are
given, followed by the number of columns to the right and rows down to
enhance or apply, defining the region to apply the enhancement to.
-
Pre-existing text at 2,2 is fonted, a box at 1,1 is started which is 50
columns wide and 4 rows long, and new text is added below the fonted
pre-existing text which prints a text string followed by a customer name
(which would have been captured previously by UnForm from earlier on the
page, for example).
-
The
absolute commands imply that a text label, say the text “Customer Total”,
will always be found at a known position on the page, or that anything that
is found there can be properly enhanced according to the given enhancement
rules contained in each command.
“Relative” version of commands:
font
“Customer Total”,0,0,14,1,univers,18
box “Customer Total”,-1,-1,50,4
text “Customer Total”,0,1,{”for customer”+custname$},univers,18
-
In
the relative version of the commands, denoted by the fact that a quoted text
search string is the first argument, the same enhancements are being applied
to a region which is the same size as in the absolute-version example, but
the designation of where on the page to start the enhancement region
depends on the location of the first byte of the text search string in the
incoming text stream, and depends on the offset argument pair
which follows the text string.
-
The
first two arguments following the quoted text search string, the offset
argument pair, denote not an absolute coordinate position, but an
offset distance, expressed in columns and rows, of how far to travel or
“offset” to find the starting point of the enhancement region.
-
The
0,0 offset on the relative font command means there is no
offset or distance to travel to find the starting point, meaning, the exact
column and row position where the first byte of the text search string is
found on the page is the starting point.
-
Notice that the next set of arguments, the 14,1 pair in the font
command, are the same as in the absolute version of the command, and they
indicate to apply the font for a length of 14 columns and 1 row only.
-
In
the relative box command notice the -1,-1 starting point
offset, it instructs UnForm to move LEFT 1 column and UP 1
row to start the box upper left corner.
As you
would expect, the offset argument pair for a relative-version command behaves as
follows:
-
Positive value Offset - RIGHT in columns, DOWN in rows
-
Negative value Offset - LEFT in columns, UP in rows
Which Commands Feature the Anchoring Option
Anchoring
works with the base “offset-oriented” commands box, font, shade and
text, plus others, but NOT with their “corner-oriented”
counterparts cbox, cfont and cshade.
-
“Offset-oriented”
refers to when the 3rd and 4th arguments after the
command verb ( often referred to as ncols and nrows )
establish the number of columns or rows to move from the starting point,
with the starting column or row counting as 1.
-
“Corner-oriented”
versions of the commands have the 3rd and 4th
arguments after the command verb referring to the absolute positions of the
opposite corner coordinates for a rectangular region.
“@position”
search region modifier
-
By
default when given a text anchor UnForm searches the entire incoming text
page.
-
There are times when it is necessary to narrow the region being searched,
since the particular text anchor being used may appear elsewhere on the page
in a different context.
-
This
is accomplished by appending a search region modifier with coordinates in
the format, “@left,top,right,bottom”, to the end of the search
string text, also inside of the quotation marks.
font
"Serial No@15,20,25,40",0,0,40,1,FONTH,10,italic
Other anchor text modifiers
Besides straight text and the @position modifier in
a text anchor, there are several options for modified expressions in the quoted
text string.
' ! =
' in front of the text string produce a NOT text string expression,
which could be used, for example, in a situation where the the word "continued"
at the bottom of a page indicates a multi-page document, and you want to apply
an enhancement to a final page that does not contain the text "continued" at the
bottom of the page.
' ~
' in front of the text string treats the text string as a unix-style
"match" regular expression, which has a special syntax for multiple types of
"wild-card" processing. A date-match regular expression, for example, can be in
the format [0-9][0-9]/[0-9][0-9]/[0-9][0-9], which will match
a text string that has any two numbers followed by a slash followed by any two
numbers followed by a slash followed by any two numbers. There are various
resources on the web that can give you an explanation of the extensive syntax
for regular expression matching. Just type "regular expressions" in a search
engine.
' ! ~
' in front of the text string
produces a NOT match regular expression.
box
Command Relativity Tips
-
When
anchoring with the box command, DO NOT use the ccols or
crows gridline options for absolute positioning inside of a box,
DO USE the icols or irows gridline options, which do
relative positioning from the top or left coordinates of the box.
-
Use
-1,-1 offsets to start a box with a corner directly above and to the
left of the text search string.
Embedding Anchors
-
Sometimes the nature of the incoming text stream does not present a clear
text element or phrase to anchor off of for a relative enhancement. An
example is a memo line underneath an invoice line item.
-
In
these cases it is possible to embed an appropriate text anchor into
the text stream using logic in a code block .
-
Logic placed inside a
prepage { } code block, for example, can analyze the incoming text
stream for a pattern and place an appropriate anchor or set of anchors which
UnForm can then use to apply relative enhancements. Here is an example for a
memo line starting at column 20 in an absolute row range from row 20 to row
40.
prepage {
for
row =20 to 40
text$[row]=pad(text$[row],80)
if trim(text$[row](1,19))=”” then\
if trim(text$[row](20))<>”Serial No” then text$[row](1,2)=”^ML”
next row
}
font “^ML”,20,0,60,1,univers,10,italic
erase “^ML”
prepage {
opsectop=0,opsecbtm=0,opseclen=0
for row=1 to 66
if opsectop=0 then\
if pos(“OperSeq”=text$[row])=1 then opsectop=row
if opsectop>0 then if opsecbtm=0 then\
if trim(text$[row])=”” then opsecbtm=row
next row
opseclen=opsecbtm-opsectop+1
}
font “OperSeq”,0,1,80,{opseclen},univers,10,italic
Part II - A demonstration of text anchoring
|
