Interface Builder Customization using User Templates

 

The User Template:

 

For those with DHTML, JavaScript and VBScript knowledge, Interface Builder allows for the development and maintenance of user developed Java or VB scripts for form and data manipulation.  As of the 3.08.20 release there are two different user templates.  The user templates are never overwritten by new releases of IB and are therefore retained from one IB release to another or when generating new screens.  They are used during each generation to insert custom user-defined functions, which can greatly expand the functionality beyond what the EAD painter can provide.

 

The Client-Side:  The user template (IEWEB.USR) contains user written Java scripts called “chapters”.  Chapters are related to selected ISPEC and data fields, by using field level business rules to contain strings that invoke the generation and calls of these routines.  These routines are generated directly into the ASP/HTML form and can be invoked at various processing points: form rendering, form submission and error processing.  This provides great flexibility in implementing features by using your own knowledge of the application.  A significant advantage of the client side scripts is each routine is generated directly into the ASP/HTML form.

 

The Server-Side:  The user template (IEWEB.INC) contains user written VBScripts called “chapters”.  Chapters are related to selected ISPEC and data fields, by using field level business rules to contain strings that invoke the generation and calls of these routines.  These routines are generated into various INC files and are processed by the web server.  Various customer INC files are associated with various processing points during the building of the output ASP/HTML form. A significant advantage of the server side scripts is server scripts are deployed to the web server and filter each ASP/HTML form dynamically modifying the form, as it is processed by the web server.  This means that changes to the ASP/HTML forms can be applied without generating a new ASP form but rather by simply deploying a new INC routine.

 

How does the IEWEB.USR Client-Side template work?

Within the IB IEWEB.DAT template there are entry points which are locations where user written scripts will be inserted.  Currently those entry points are in the closing chapter (98) of IEWEB.DAT.   User scripts can be inserted in the functions: ParseErrors()-for user error handling, prescreen ()-for processing prior to rendering the form in the browser and prelinc ()- prior to submitting the form to the host and one prior to the edit checking in prelinc().        

 

Expanded Host Integration:

In addition to the entry points, users can use painted display images in LDA to invoke user chapters.  The display image’s position and sizing can be used in the user chapter to position ICONs, buttons or any other GUI object.  The capabilities of this feature are best illustrated by the following examples:

 

·        Open a calendar ICON to allow the user to point and click on the day, month and year from a calendar image.  Upon selecting the appropriate day the date string would be populated into the data entry date field painted on the form with the proper date format.

·        Documentation written and maintained using MS WORD or other word processors could be assessed and presented in the browser by adding a documentation ICON to the form that could open another window or open a pop-up window with this documentation.

·        Data sent to the browser via a list box can be rendered in the browser as lines of text.  Instead of scrolling the list box to see the list box data, the user would scroll the browser page.

·        The LINC ISPEC could open web pages or html forms developed by other departments.  Data could be selected from these new pages to be placed in one or many fields on the original LINC form.

·        Data rendered in a list box could be written into a new browser window thus making it a more PRINTER friendly form for the user to print from their own browser to their attached printer.

 

Illustrations:

The following illustrates how a user-developed script could identify and manipulate date fields.  It is common for date fields to be various lengths and date formats.  Other than the LINC attribute EDIT=D, fields that are date oriented usually cannot be determined without close examination of LINC logic.  In order to make it easier for an end-user to enter a date field correctly, it has been requested that the user be able to pop open a calendar from which they can select a specific day.  This would in turn populate a designated field in the correct date format.

 

The LINC ISPEC before painting a Display Image: 

 

A data field named “INDATE2” is defined as ED=N LE=8 and contains date information in the format of CCYYMMDD.  This example could be for any field, with any edit attributes, representing any date format.

 

A Display Image is painted next to the INDATE2 field.

The name of the image is DATEADV.USR. IB detects an image that ends in a suffix of USR.  IB will match this name against entries found in the ieweb.usr template.  When a match is found IB will generate html or java code based on the routine developed and saved in the user template.  Any ISPEC/data field can use this routine.

 

 

 

 

 

 

 

 

 

 

 

 

 

 


The following entry is entered in the User Template.   Indented lines indicate text that is continued from the line above.  In the Template these lines would be single lines of text.  IB will match the name of the image DATEADV against the entries found in the ieweb.usr template.  The next token in the user template is INDATE2 and it associates this image with the data item defined in the ISPEC.   The date format is included indicating that this routine will return the date string as CCYYMMDD.  ^dt^ is the user designated chapter ID that will be generated into the resulting ASP/HTML form.  The text after the last “^”  is user information that will appear as pop-up help text as the mouse is hovered over the calendar ICON. 

 

The User Generation String:

00 N^DATEADV^INDATE2^ ^ ^CCYYMMDD^dt^ ^Clicking the calendar will populate the date field according to the date format specified.  The following formats are supported:<br>MMDDYY  DDMMYY  YYMMDD  CCYYMMDD  MMDDCCYY DDMMCCYY

 

 

dt Y<img align=middle alt="Open Calendar ^VA^" src="^IM^calendar.gif"

dtiTLB /=  SPACES

dtiY  onmouseover="setPopUp('^DN^div', 'visible');" onmouseout="setPopUp('^DN^div', 'hidden');"

dtiTendtest

dt YonClick="document.IEGIspec.^DN^.value = DateConvert('^DN^','^VA^',document.IEGIspec.^DN^.value )"; style="left:^PL^; top:^PT^; width:^PW^; height:^PH^;">

dtiTLB /=  SPACES

dtiY<div id="^DN^div" style="left:^2L^; top:^2T^; visibility:hidden; z-index: 99; ">

dtiY  <table width="^2W^" height="^2H^" border="2" cellpadding="4" cellspacing="0" bordercolor="#009900" bordercolorlight="#99FF99" bordercolordark="#008000" bgcolor="#CCFFCC">

dtiN  <tr><td><span style="left:5; top:5; font-size:12px font-family:Comic Sans MS; color:#008000; background-color:#CCFFCC; ">

dtiY   ^LB^

dtiN  </span></td></tr></table>

dtiN</div>

dtiTendtest

99 N

 

The line that starts with “00” represents chapter 00 and this is the record that associates the user written scripts in chapter “dt” and the painted display image name DATEADV.USR.  Lines that start with “dt” are the date chapter.  This chapter paints an ICON with an image named “calendar.gif”, creates a pop-up only if there is text following the last “^” , and populates the INDATE2 field with the results returned from the DateConvert function.

 

Once this chapter is written other Chapter 00 lines can call this routine and be associated with any number of Ispec/data combos.

 

Generation String format:

00 N ^<ispec or function name>^<dataname>^lengthvalue^<one of the 4 entry points or blank>^<user variable>^<chapter-ID>^<language #>^<misc text>

 

“^” is the delimiter separating field information. Each delimiter ^ must be separated by a character string or at least one single space.  The generation string should never have two delimiters together (^^).

 

The generation string is retained in the IEWEB.USR template file.

·        All declared generation strings in the IEWEB.USR template must start with chapter 00. 

·        Column 3 is blank or can have the letter [c,C], which denotes this line is a comment and is not included in the processing. 

·        Column 4 must be the letter “N”. 

·        If the data item is painted in a copyfrom area, you will have to declare each item and name it according to the naming string in the html, that  means the item name would be something like DATAITEM__AT_01....etc. and you will have to declare each one.

·        an Ispec = ***** means these rules to this data item in all ispecs.

·        If a data item has an explicit ISPEC and ***** the explicit ISPEC rules is applied to the specific ispec and everywhere else the ***** applies.

·        The length parameter is a value up to 4 digits in size and is the length of the field.

 

The following formatting rules apply to the generation string regardless of where it is declared:

·        The ispec, dataname, call location will all be converted to Upper Case.  Dashes (-)  will be converted to underscores(_)

·        There must be a space or character separating each ^.. YOU can not have ^^.

·        The User Chapter is case sensitive, must start with an alpha character.

 

Illustration of building the User Generation String:

The illustration builds the generation string with an explanation of each item as it is added.

 

00 N  - All generation strings will start with this.  If a “c” is in the third column then this line is a comment and is skipped during generation.

 

00 N^DATEADV^   - The Ispec or function name has now been added.  In this case this represents the function name.  DATEADV was entered as the Display Image File name along with “.USR” in the EAD painter.  The image name is compared against the user generation string for a match and when found triggers the association of this display image with this function.

 

00 N^DATEADV^INDATE2^ - The data item named INDATE2 has now been added.  The DATEADV function will now target this data name as the field to store the result of this function.  If the ^DN^ token is used as a wild card in the chapter script it will be replaced with INDATE2.

 

00 N^DATEADV^INDATE2^ ^ ^ - The next two tokens following the data name are empty.  They are the length, which is not used in the function and entry point, which is also not used by this function.

The entry point can be one of the following values:

 

00 N^DATEADV^INDATE2^ ^ ^CCYYMMDD^ - The next token is the ^VA^ user variable.  In this date function this represents the data format of the field INDATE2.  Since this is a date routine the typical data formats that might be specified here are CCYYMMDD, MMDDCCYY, DDMMCCYY, YYMMDD, MMDDYY and DDMMYY.  This represents the 6 and 8 character US and European date formats.  The date function will use this format and return a value to be stored in INDATE2 that matches this format.

 

00 N^DATEADV^INDATE2^ ^ ^CCYYMMDD^dt^ - The next token is the user chapter “dt”.  This can be and two alpha character strings (Aa –Zz) and 0-9 as long as it begins alpha character.  This ID is case sensitive.  The chapter “AA” will be different than “aa”.

 

00 N^DATEADV^INDATE2^ ^ ^CCYYMMDD^dt^ ^ - The language slot has now been added and is empty.  Since the a Display Image is actually painted in the EAD painter, it is already associated with a specific ISPEC language version so there is no need to specify the language number again.

 

00 N^DATEADV^INDATE2^ ^ ^CCYYMMDD^dt^ ^Clicking the calendar will populate the date field according to the date format specified.  The following formats are supported:<br>MMDDYY  DDMMYY  YYMMDD  CCYYMMDD  MMDDCCYY DDMMCCYY

Finally the last part of the user generation string has been added. “Clicking the calendar…” is help text that will appear in a pop-up window as the user mouses over the ICON.  This window will automatically open and close by the movement of the mouse.

 

Chapter Naming:

The value of “dt” has no special significance other than they represent a unique chapter in the IEWEB.USR template.  If the user wishes to declare global variables or other Java functions, the chapter “gl” (GL in lower case) is required.  The “gl” chapter is for user-defined global variables and functions.  Chapter IDs must start with an ALPHA character and cannot be a chapter defined in the IEG standard template, IEWEB.DAT, or the “gl” chapter,

 

In the template IEWEB.USR:

glcN user declared global variables and Java functions

gl N<script language="JavaScript">

glcN add more variables or Java functions here

gl Nvar iegDate = new Date();

gl N</script>

99 N

 

What tokens are available?

DN – the selected data field name (FORMDATE)

FL – the define length of the field (0008)

ET – the Entry type (PL, PS, PE)

VA – a user defined value (MMDDCCYY)

LB – misc. text after the last “^”

 

What gets generated?

 

The results of this User DATEADV function:

                       

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


To handle another date field the steps are very simple and as follows:

1)      Paint the display image in EAD painter and name the image DATEADV.USR

2)      In the user template duplicate the user generation string and change INDATE2 to the name of the other field, i.e. DATEOUT

 

Once generation strings are built, generation of the ASP form will always include these additional expand integration functions.

 

 

How does the IEWEB.INC Server-Side template work?

Within the IB IEWEB.DAT template there are various ASP calls to subroutines defined in the IEGGLB.INC file.  These subroutines can be expanded to include additional user written functions.  There are currently 6 points where calls are made to IEGGLB.INC subroutines.  There is one additional place within the IEGGLB.INC template for generic Subroutine or Functions to be appended with existing INC Subroutines and Functions.  This can be dynamically expanded to as many as 30 calls. The initial seven points are listed along with their associated Tokens :

<% IEGGen_JS_Var_Section_Head %>       ^INCJSV^

<% IEGGen_JS_Function %>                      ^INCJS^

<% IEGGen_Extra_Fields %>                     ^INCEXT^

<% IEGGen_PL %>                                         ^INCPL^

<% IEGGen_PS %>                                         ^INCPS^

<% IEGGen_End_Of_PS %>                           ^INCEPS^

and … the outer INC level                         ^INCOUT^

 

To start the process the client uses Notepad or WordPad to define and maintain a text file named IEWEB.INC and saves this file in the same folder where the loaded model was located.  This file will contain generation strings and user chapters which, when combined together during the IB generation process, produce custom INC files to be deployed on the web server.

 

The First Step:

The first step in implementing the custom INC routines is to define tokens for each of the seven call points.  Note that not all of the tokens have to be defined, but if a routine is desired at a given location that token must be defined.  There are two methods that can be used to define these tokens.  Each method starts by declaring a token definition record. These token definition records always start with “00 N”.

 

Defining Tokens:

The simplest way to define these tokens is to use the defaults.  Default definition records would look like the following.  Note that the spacing between ^ is not critical however each ^ must be separated by at least one space.  In the record the 4th location contains the token value as defined in the IEGGLB.INC.

METHOD ONE

01aN Sub IEGGen_JS_Var_Section_Head

01aN%>

01aY^INCJSV^

01aN<%

01aN End Sub
 

Code found in IEGGLB.INC.TPL

 

   Corresponding “TOKEN” value

 

 

 

            Record position:             1 2 3 4       5 6 7 8

Contents of IEWEB.INC:               00 N^ ^ ^ ^INCPS  ^ ^ ^ ^

00 N^ ^ ^ ^INCPL  ^ ^ ^ ^

00 N^ ^ ^ ^INCJSV ^ ^ ^ ^

00 N^ ^ ^ ^INCEXT ^ ^ ^ ^

00 N^ ^ ^ ^INCJS  ^ ^ ^ ^

00 N^ ^ ^ ^INCOUT ^ ^ ^ ^

00 N^ ^ ^ ^INCEPS ^ ^ ^ ^

The result will be code generated into iegglb.inc of: …

<!-- #INCLUDE FILE="INCJSV.inc" -->

… and the creation of a file named INCJSV.INC deployed in the same folder as IEGGLB.INC .

 

METHOD TWO

This method permits the explicit declaration of file names and INC strings as desired and defined by the client.  The IEWEB.inc file would contain:

                      1 2         3 4       5                                  6 7 8

       00cN^ ^MyJSV.inc^ ^INCJSV^<!-- #INCLUDE FILE="MyJSV.inc" -->^ ^ ^

 

Record position:

1=empty

2=name of the external file to be created. This must match the value in position 5

3=empty

4=the token identifier. One of the seven tokens

5=the INC string used to replace the token found in iegglb.inc.

6=empty

7=empty

8=empty

The result will be code generated into iegglb.inc of: …

<!-- #INCLUDE FILE="MyJSV.inc" -->

… and the creation of a file named MYJSV.INC deployed in the same folder as IEGGLB.INC .

 

It is possible that the ieweb.inc file would contain nothing more than the token definition records.  The result would be generating IEGGLB.inc with custom INCLUDE strings.  A knowledgeable VBScript developer could do the creation and maintenance of the actual custom INC files manually.

 

Letting IB generate the contents of each custom INC file:

Creating custom INC files will be illustrated with the following example ASP forms.  The purpose
of the customization is to change the
style of selected buttons on the form to
look more like WEB Links instead of a
standard push button. 

 

The image to the right illustrates the form
before generating and deploying new
INC files. 

 

Two approaches will be discussed on
how this change was made.  The
purpose of this illustration is simply to
show by example how the server side
INC files can produce the desire form
changes.

 

 

The next image shows the same form
after the new INC files were deployed
on the web server.

 

Illustration A:

The initial form was generated using the
CSS style sheets. So the initial planning
step would be to examine the generated
ASP source to determine which CLASS
  is associated with the menu buttons. 
That class was determined to be
“IEGPBUTTON0002”. 

 

The task now will be to build custom
INC files to modify the CLASS
IEGPBUTTON0002 style attributes
to a web look and feel.  The first
approach will be to insert a CLASS
definition with the desired style attributes to make all buttons associated with IEGPBUTTON0002 to look like a web link. 

 

An ieweb.inc file with the following contents will produce the above results.  Some lines may be wrapped for readability.

 

00 N^   ^incEXT.inc  ^  ^INCEXT  ^<!-- #INCLUDE FILE="incEXT.inc" -->^  ^  ^

 

00 N^*****^globalitems ^  ^INCEXT   ^ ^GL  ^  ^

00 N^*****^IEGPBUTTON0002 ^  ^INCEXT   ^ ^nc  ^  ^

 

nccN  another way to manipulate CLASSes

nc N

nc N<%

nc Yif (IspecName = "^IS^") or ("^IS^" = "*****") then

nc Yif (IEGLang = "" ) or ("" = "^LB^") or (IEGLang = "^LB^") then

nccN Condition the response write with the correct ISPEC and LANGUAGE

nc N  response.write("<style>   " & vbcrlf)

nc Y  response.write(".^DN^ {font-family:VERDANA; font-size:9; color:#0000FF; background-color:transparent; text-decoration:underline; border:0; cursor:hand;}  " & vbcrlf)

nc N  response.write("</style>   " & vbcrlf)

nc Nend if

nc Nend if

nc N%>  

99 N

 

GLcN  defining dims

GL N<%

GL Ndim IEGLang

GL Ndim LocalLangs

GL Ndim IspecName

GL Ndim i

GL NLocalLangs = Session("LangNames")

GL NIEGLang = Trim(UCase(objCurrentIspec.getFieldValue("IEGVIEW")))

GL NIf IEGLang = "" then IEGLang = LocalLangs(0)  ' where we want to go '16

GL NIspecName = trim(objCurrentIspec.getName())

GL N%>

99 N

 

 
A

 


B

 

C

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

D

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Explanation:

The “A” record is the token definition record.  IB will use the INCEXT location within the IEGGLB.INC and will insert the INCLUDE statement to include the file named INCEXT.INC.  (Note the case of the file name does not matter).

 

The “B” records define what is to be generated and with what parameters. A global chapter is requested as defined by the “GL” chapter.  The first 00 record (globalitems) causes IB to generate, into the INCEXT file, some global variables (dim) which are set by the ASP code to define the ISPEC and Language being processed by the web server.  The second 00 record inserts the user chapter “nc” which is the routine that modifies the form and inserts a new CLASS definition for the IEGPBUTTON0002 with the desired style attributes.  By locally defining this CLASS in the ASP form, the local style attributes override those declared in the CSS file.

 

The results:

The iegglb.inc will have the following code generated:

 

Sub IEGGen_Extra_fields

          ' Example to tell external app where user was in form:

          response.write "<input type='hidden' name='XFOCUS' value=''>" & vbcrlf

%>

<!-- #INCLUDE FILE="incEXT.inc" -->

<%

  End Sub

 

 
 

 

 

 

 

 

 

 

 


The INCEXT.INC file will have the following code.

<%

dim IEGLang

dim LocalLangs

dim IspecName

dim i

LocalLangs = Session("LangNames")

IEGLang = Trim(UCase(objCurrentIspec.getFieldValue("IEGVIEW")))

If IEGLang = "" then IEGLang = LocalLangs(0)  ' where we want to go '16

IspecName = trim(objCurrentIspec.getName())

%>

 

<%

if (IspecName = "*****") or ("*****" = "*****") then

if (IEGLang = "" ) or ("" = "") or (IEGLang = "") then

    response.write("<style>   " & vbcrlf)

   response.write(".IEGPBUTTON0002 {font-family:VERDANA; font-size:9; color:#00aa00; background-color:transparent; text-decoration:underline; border:0; cursor:hand; IEGtype:52;}  " & vbcrlf)

    response.write("</style>   " & vbcrlf)

end if

end if

%>

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The web server will dynamically insert the following line in the ASP/HTML form. (Note line 2 is broke into 2 lines for readability.)

 

<style>

.IEGPBUTTON0002 {font-family:VERDANA; font-size:9; color:#0000FF; background-color:transparent;
text-decoration:underline; border:0; cursor:hand;}

</style>

 

 

Illustration B:

The initial form was generated WITHOUT using the CSS style sheets. So the initial planning step would be to identify the field, which is painted as push buttons.  That field name is NEXTPAGE.

 

The task now will be to build custom INC files to modify the style attributes for the field NEXTPAGE to a web look and feel.  This approach will be to insert a JavaScript to change style attributes for all push buttons generated for the NEXTPAGE object.

 

The IEWEB.INC will contain the following token definition records:

00 N^ ^incOUT.inc    ^  ^INCOUT  ^<!-- #INCLUDE FILE="incOUT.inc" -->^  ^  ^

00 N^ ^end_of_ps.inc ^  ^INCEPS  ^<!-- #INCLUDE FILE="end_of_ps.inc" -->^  ^  ^

 

 
 

 

 

 

 

This approach will generate iegglb.inc and two additional INC files:  INCOUT.INC and END_OF_PS.INC.  Next we add three additional “00” records to define what will be generated:  chapters GL, x1 in END_OF_PS.INC and chapter CS in INCOUT.INC.

 

00 N^pg000^globalitems ^  ^INCEPS   ^ ^GL  ^  ^

00 N^pg000^NEXTPAGE    ^  ^INCEPS   ^ ^x1  ^  ^

00 N^pg000^NEXTPAGE    ^  ^INCOUT   ^ ^CS  ^  ^

 

 
 

 

 

 

 


Finally the iweb.inc file will contain the customized chapter to complete the objective of turning a specified field (NEXTPAGE) from  a push button style to a look and feel of a web link.

x1cN When we have the correct form, generate a call to a ChangeStyle routine in INCOUT.inc

x1 N<%

x1 Yif (IspecName = "^IS^") or ("^IS^" = "*****") then

x1 Yif (IEGLang = "" ) or ("" = "^LB^") or (IEGLang = "^LB^") then

x1cN I have now condition the response write with the correct ISPEC and LANGUAGE

x1 Y   ChangeStyle ("^DN^")

x1 Nend if

x1 Nend if

x1 N%>  

99 N

 

GLcN  defining a few dims to set ISPEC name and Language of this form

GL N<%

GL Ndim IEGLang

GL Ndim LocalLangs

GL Ndim IspecName

GL Ndim i

GL NLocalLangs = Session("LangNames")

GL NIEGLang = Trim(UCase(objCurrentIspec.getFieldValue("IEGVIEW")))

GL NIf IEGLang = "" then IEGLang = LocalLangs(0) 

GL NIspecName = trim(objCurrentIspec.getName())

GL N%>

99 N

 

CScN generate ChangeStyle subroutine in INCOUT.INC and pass the field name into the subroutine.  Check for number of push buttons and change style for each push button associated with the targeted field.

CS N<%

CS Ndim MyTarget

CS NSub ChangeStyle (MyTarget)

CS Yresponse.write("var MyTarget = '" & MyTarget & "';" & vbcrlf)

CS Yresponse.write("for (x=0; x<document.all.tags('input').length;x++) { //  from INC" & objLINC.GetLanguage() & vbcrlf)

CS Yresponse.write("if ( (document.all.tags('input').item(x).type=='button')  && (MyTarget == document.all.tags('input').item(x).name.substr(0,MyTarget.length) ) ) {" & vbcrlf)

CS Nresponse.write("  document.all.tags('input').item(x).style.fontFamily='VERDANA';" & vbcrlf)

CS Nresponse.write("  document.all.tags('input').item(x).style.fontSize='9';" & vbcrlf)

CS Nresponse.write("  document.all.tags('input').item(x).style.color='#0000FF';" & vbcrlf)

CS Nresponse.write("  document.all.tags('input').item(x).style.backgroundColor='transparent';" & vbcrlf)

CS Nresponse.write("  document.all.tags('input').item(x).style.textDecoration='underline';" & vbcrlf)

CS Nresponse.write("  document.all.tags('input').item(x).style.border='0';" & vbcrlf)

CS Nresponse.write("  document.all.tags('input').item(x).style.cursor='hand';" & vbcrlf)

CS Nresponse.write("    }  //  if" & vbcrlf)

CS Nresponse.write(" }  // for" & vbcrlf)

CS Nend Sub

CS N%> 

99 N