Templates

Template Files

All JumpStart template files reside in directory /www/[Instance Name]/jumpstart.  For the default instance name of PROFOUNDUI, the JumpStart template directory is /www/profoundui/jumpstart.

Rich Display File and Universal Display File¹ templates have the .json extension. Application code templates will have the extension .rpgle, .php, or .js depending on the language. HTML templates for Node.js have the .html extension. JumpStart ships with the following templates:

• GridDataURL (PHP)

• Input Capable Subfile (RPG)

• Mobile (RPG)

• Standard Node (Node.js)

• Standard HTML (Node.js)

• Standard (RPG)

• TinyMVC (PHP)

• Webservice to do Autocomplete (RPG UDF)

• Webservice to load Chart Data JSON (RPG UDF)

• Webservice to load Chart Data XML (RPG UDF)

• Webservice to load Dropdown Data (RPG UDF)

• Webservice to load Grid Data (RPG UDF)

• Webservice to perform file maintenance (RPG UDF)

• PJS Webservice to do Autocomplete (Node.js)

• PJS Webservice to load Grid Data (Node.js)

You should never modify these files directly. If you wish to create your own template, you may copy the files and give them your own name.

To have your Rich Display template appear as a selection in the JumpStart interface, you need only copy or create a .json file.  Creating an application code template (.rpgle or .php) file is optional.  If a corresponding application code template does not exist for your .json file, the file Standard.rpgle or Standard.php will be used, depending on the language selected.

So, if you wish to add your own logo to the interface portion of the template, but leave the code generation portion as is, simply make a copy of the .json file.  However, if you also wish to modify the code generation templates, you will have to make a copy of the .rpgle and/or .php file as well.

You should use the Profound UI Visual Designer to open and modify the .json Rich Display File templates.  However, you can use any standard editor to modify the application code templates.

Note that you should generally use the standard Visual Designer, not the View Designer for PHP.  This will retain all parts of the template, rather than just the parts relevant to PHP.

¹Support for Universal Display File templates is available with Profound UI Version 5, Fix Pack 10.0 and later.

Template Syntax

All special directives, commands, comments and variables in JumpStart begin with a # symbol.  Directives, commands, and variables are case sensitive. When editing a .json template using the Visual Designer, you can provide these special directives or variables as properties on a widget or a record format.  This is specified either in the Properties Window or in the Binding Dialog within the Visual Designer.

For example, you can specify the “value” property for an output field widget as #description.  At generation time, this will be populated with an actual field description.  For another output field widget, you may wish to bind the “value” property, and in the Binding Dialog specify the field name as #field.  At generation time, this will bind the property to an actual field name.

Comments

To specify a template comment, use ## followed by the comment.  Template comments are only stored in the template and will not be inserted into the generated code. 

Example:

In order for PHP and RPGLE editors, such as RDi, to recognize the line as a comment, an alternate syntax can also be used as follows:

This combines the RPGLE/PHP style comment syntax with the JumpStart comment syntax.

New File Directive

A template can be used to generate multiple code files.  This is useful for creating a modular application.  Within the template, this can be accomplished with the #newfile directive followed by a name. (The format of the name depends on the code type.)

PHP Example

For PHP templates, the filename should be an IFS filename, optionally preceded by a relative path:

If the above template is used, and the Main PHP script file name specified in JumpStart is /www/profoundui/htdocs/profoundui/userdata/php/myapp/index.php, then the following files will be created:

• /www/profoundui/htdocs/profoundui/userdata/php/myapp/index.php (this will contain the Main file template code)

• /www/profoundui/htdocs/profoundui/userdata/php/myapp/.htaccess (this will contain the .htaccess template code)

• /www/profoundui/htdocs/profoundui/userdata/php/myapp/relative/path/config.php (this will contain the relative/path/config.php template code.¹)

¹ If the relative/ or relative/path/ IFS directories did not exist, then they are created automatically. The path to these directories is relative to the directory specified for index.php (e.g. /www/profoundui/htdocs/profoundui/userdata/php/myapp/).

RPG Example

For RPG templates, the filename should be a 10-character source member name, optionally preceded by a physical file name² and a comma:

If the above template is used, the specified Library is EXAMPLES, the Program Source File is QRPGLESRC, and the main RPG program name is JMPSTR001R, then the following source members will be generated:

• EXAMPLES/QRPGLESRC,JMPSTR001R (this will contain code from the main template)

• EXAMPLES/QRPGLESRC,HELPER1R (this will contain code from the first #newline directive up to the next)

• EXAMPLES/QRPGSPSRC,CGIPROGR (this contains code from the second #newline directive up to the end) ²

Support for the #newfile directive with RPG code is available with Profound UI Versions 5, Fix Pack 7.0 and later.

 ² If the physical file did not exist, then JumpStart will display an error and stop.

Variables

JumpStart provides a set of global and field-specific variables, which are replaced at generation time with actual values selected in the JumpStart interface.  The variables can also be used in conditional expressions.  Boolean variables either have the value true or false.  The following is a list of global variables available in JumpStart:

• #title – The title of the application specified by the developer

• #file – The database file selected

• #filexxxxx – The database file padded to 10 characters; this can be used on a fixed format F specification in RPG

• #fullFile – The full file path, including the library, if it was provided in the JumpStart interface

• #fileDescription – The 50-character text description of the database file.

• #longFile – The long SQL file name or Alias name; if the file doesn't have a long name, this variable will return the same value as #file, or the standard/short file name.

• #fieldCount – The number of fields in that were output in the Field Selection section of the interface. When one file is chosen, this is the number of fields in that file. Includes fields not chosen for use.

• #keyCount - The number of fields marked as Unique Keys in the Field Selection section.² Certain applications need keys, including Lookup and the Input-Capable Subfile.

• #gridCount - The number of fields chosen to appear in the grid. Applies only to Subfile application type.

• #searchCount - The number of fields chosen to be search fields. Applies only to Subfile application type.

• #viewCount - The number of fields chosen to appear in the View Screen. Applies only to Subfile application type. If the subfile application uses combined screens, this is the number of detail fields chosen.

• #editCount - The number of fields chosen to appear in the Edit Screen. Applies only to Subfile application type. If the subfile application uses combined screens, this is the number of detail fields chosen.

• #detailCount - The number of fields chosen to appear in the Detail Screen. Applies only to Subfile application type. If the subfile application uses separate screens, this is 0.

• #addCount - The number of fields chosen to appear in the Add Screen. Applies only to Subfile application type. If the subfile application uses combined screens, this is 0.

• #appType – The application type selected; possible values are subfile, data entry, or lookup

• #subfileType – The subfile type selected; possible values are loadall or paging

• #language – The language selected; possible values are "rpg free", "rpg free with fixed", "php", or "nodejs".

• #fixed (boolean) – Set to true if the language selected is rpg free with fixed

• #view (boolean) – View checkbox selected

• #edit (boolean) – Edit checkbox selected

• #add (boolean) – Add checkbox selected

• #delete (boolean) – Delete checkbox selected

• #combined (boolean) – Set to true when One Combined Screen option is selected for View/Edit/Add

• #library – The library name of the database file, if provided

• #programSourceFile – The source file of the generated program; for example: QRPGLESRC

• #program – The generated program name for RPG templates. For Node.js, this is the Proxy program name.

• #displaySourceFile – The source file of the generated Rich Display; for example; QDDSSRC

• #dspf – Display file name

• #dspfxxxxxx – Display file name padded to 10 characters; this can be used on a fixed format F specification in RPG

• #pageSize – The page size as defined the Rich Display File .json template

• #phpFile - The filename only of the generated PHP file.

• #phpFullPath – The full path to the generated PHP file

• #phpFullDir - The full directory containing the generated PHP file

• #jsonFile - The filename of the generated Rich Display JSON file excluding directories, when used for PHP.

• #jsonFullPath – The full path to the generated Rich Display JSON file, when used for PHP

• #jsonFullDir - The full directory containing the generated Rich Display JSON file, when used for PHP

• #phpRelativePath – The path relative to the document root of the generated PHP file

• #phpRelativeDir -  The directory relative to the document root that contains the generated PHP file

• #jsonRelativePath - The path relative to the document root of the generated Rich Display JSON file

• #jsonRelativeDir - The directory relative to the document root that contains the generated Rich Display JSON file

• #php (boolean) – Set to true when PHP is selected as the language

• #rpg (boolean) – Set to true when RPGLE is selected as the language

• #documentRoot - The HTTP server document root directory -- i.e. /www/profoundui/htdocs

• #serverRoot - The HTTP server root directory -- i.e. /www/profoundui

• #osRelease - The OS Release in upper case. For example V7R1M0.

• #fileCount - The number of files chosen, including the main file and all extra files, including files not joined to main.¹

• #nodejsFile - The IFS filename chosen for the Node.js program.¹

• #nodejsFullPath - The full path and filename chosen for the Node.js program.¹

• #nodejsFullDir - The directory name without the filename, chosen for the Node.js program.¹

• #nodejs (boolean) - Set to true when ProfoundJS is selected as the language.¹

• #htmlFile - The filename of the generated Node.js display when HTML is chosen as the display type.

• #userrn - (boolean) - Set to true when no keys are selected but the program needs keys–delete, edit, view were selected in a subfile application.³

• #correlOrFile - A string set the same as the correlation for the main file; or same as #file if a correlation is not specified.³

In addition to global variables, JumpStart also provides field-specific variables that are used in loops that iterate through fields. The following is a list of field-specific variables:

• #field – Field name. If a file's field has a long alias, then the Jumpstart UI fills the input box in "Field Selection" with the long field name. The Jumpstart user may specify an alternate name in the Field Selection interface, in which case, #field is not the same as the database field name.

• #fieldxxxxx – Same as #field, but padded with spaces to 11 characters if the value of #field has fewer than 11 characters. If the value of #field has more than 11 characters, then #fieldxxxxx is a the value of #field truncated to 11 characters. #fieldxxxxx can be used on a fixed format D specification in RPG if #field has 11 or fewer characters.

• #fieldLC – Same as #field, except all characters are lowercase.²

• #dbfield - The database field name. Often the same as #field, unless the user chose a different field name¹, or unless the database field name has a long alias. #dbfield is never the long name alias–it is always the shorter name.

• #dbfieldxx - The database field name padded with spaces to 10 characters. If the field name has a long alias, this is the short database name. Useful for fixed form RPG.

• #dbfieldLC – Same as #dbfield, except all characters are lowercase.²

• #description – Field description as specified by the user (initially retrieved from the database)

• #type – Field type; for example: A for alphanumeric

• #varlenind – Variable field length indicator: 1 if the field has a variable length, 0 otherwise.⁴

• #length – Field length

• #decimals – Field decimal positions

• #key (boolean) – Set to true if selected as a unique key field in the JumpStart interface

• #grid (boolean) – Set to true if selected as a grid field in the JumpStart interface

• #search (boolean) – Set to true if selected as a search field in the JumpStart interface

• #details (boolean) – Set to true if selected as a details field in the JumpStart interface

• #view (boolean) – Set to true if selected as a view field in the JumpStart interface

• #edit (boolean) – Set to true if selected as an edit field in the JumpStart interface

• #readOnly (boolean) – Set to true if selected as a read only field in the JumpStart interface

• #add (boolean) – Set to true if selected as an add field in the JumpStart interface

• #index – The field index; 1 for first field, 2 for second field, etc.

• #first (boolean) – Set to true if this is the first field in the loop

• #last (boolean) – Set to true if this is the last field in the loop

• #longName - the long SQL field name or Alias name; if the field doesn't have a long name, this variable will return the same value as #dbfield, or the standard/short field name. If the user did not change the value of the field name (#field), and if the field name isn't long, then #dbfield is the same as #field.

• #safeLongName - In most cases, this will be identical to #longName. If #longName contains a value that is unusable in RPG variables, however, then #safeLongName will return the same value as #dbfield.⁵

• #generatedAlways (boolean) - Set to true if this field is always auto-generated by the SQL engine

• #generatedByDefault (boolean) - Set to true if this field auto-generated by the SQL engine by default but can still be overridden to a different value by the application

• #use - Specified whether the field is I (input), O (output), B (both) or N (neither)

• #parentFile - the file to which the current field belongs. ¹

• #parentFullFile - the library and file to which the current field belongs.¹

• #parentCorrel - The user-specified correlation value for the field's file. Empty if not specified.¹

• #coalesceVal - The user-specified value to use as the second argument in a COALESCE SQL function. Empty if not-specified.¹

¹ Available in Version 5, Fix Pack 8.0 and later.

² Available in Version 5, Fix Pack 12.0 and later.

³ Available in Version 6, Fix Pack 2.0 and later.

⁴ Available in Version 6, Fix Pack 4.0 and later.

⁵ Available in Version 6, Fix Pack 16.0 and later.

Conditional Expressions

JumpStart templates support conditional expressions using the #if directive in Rich Display Files and the #if, #else, and #endif directives in code templates.

The basic syntax is as follows:

Where expression is a valid JavaScript expression that can include JumpStart global or field-specific variables. 

For example, in a code template, you may have something like this:

Or

It is important to note that variable replacement happens prior to the evaluation of the expression and therefore string variables will generally need to be enclosed in quotations.  For example, the following is NOT the right way to construct an expression:

After variable replacement, the expression will look as follows if the user selected a Paging Subfile:

paging == “paging”

This will not evaluate to true because the variable paging (which does not even exist) will not equal the string “paging”.

Whenever strings are involved, the correct way to construct the expression would be something like this:

After variable replacement, the expression will then look as follows:

“paging” == “paging”

Which will evaluate to true, as desired.

Rich Display Files also support conditional expressions on widgets. The expression must be placed as a “user defined data” property. For example, if a widget contains the expression #if #php under “user defined data”, the widget will only be created if the selected language is PHP.

Loops

Loops allow JumpStart to iterate through field lists, file lists, and SQL From-clause strings.

In Rich Display File templates, loops are implied and do not have to be coded. However, in application code templates, you will have to use loops to deal with fields.  For example, a loop can be used to generate the WHERE clause of an SQL statement based on the search fields selected by the developer in the JumpStart interface.

A loop will repeat a code template section for every iteration.  For example, the following loop generates comments into the code to list field names and descriptions of all the fields in the selected database file:

Loops cannot be nested.

Field Loops

The following loops are available in JumpStart for iterating over fields selected in the Field Selection section of the interface:

• #for each field / #endfor

• #for each grid field / #endfor

• #for each view field / #endfor

• #for each edit field / #endfor

• #for each detail field / #endfor

• #for each add field / #endfor

• #for each key field / #endfor

• #for each search field / #endfor

• #for each nonGenerated field / #endfor

• #for each nonGeneratedAlways field / #endfor

Field Loop Limiters

The various "#for each ___ field" loops iterate over different subsets of the list of fields. Loop limiters can be added to any of those loops to cause a smaller subset of fields to be iterated over. Limiters follow the "field" word in the "for each __ field", are separated by spaces, and must be on the same line as the "#for".

Limiters are (case sensitive):

• inMain - limits the loop to those fields that belong to the main file. Useful for generating SQL for updating only the main file.

• chosen - limits the loop to fields that were chosen in the Field Selection section of the interface; i.e. the grid, search, view, edit, read-only, detail, use, or add checkbox was selected for the field. Useful for omitting unused fields from SQL queries and data structures.

• inGrid - limits the loop to fields that were chosen for the Grid in the Field Selection section of the interface; i.e. the field's Grid checkbox was checked.

• nonKey - limits the loop to fields that are not keys. Useful for updating non-key fields, like with input-capable subfiles.

• inDetail - limits the loop to fields that were chosen for the Detail screen in the Field Selection section of the interface; i.e. for Subfile application type using Combined screens.

• inEditNonRO - limits the loop to fields that were chosen for the Edit screen in the Field Selection section of the interface, and not chosen as Read Only; i.e. for Subfile application type using Separate screens.

Limiters allow you to take advantage of loop-variables that you couldn't normally use with If-Else statements inside a loop.  The loop variable, #first, is true on the loop's first iteration. #last is true on the loop's last iterations.

Loop limiters are available with Profound UI Version 5, Fix Pack 8.0 and later.

Example Loop Limiters

The template portion below generates an If statement to test only fields chosen for the grid, that are in the main file (not extra files), and that are not keys:

Sample output:

File Loop

Profound UI Version 5, Fix Pack 8.0 supports selecting multiple files in JumpStart. The following loop is available for iterating over files:

• #for each file / #endfor

This loop supports the following loop-specific variables;

• #index - the loop iteration index. starts at 1.

• #first - true if this is the first iteration; false otherwise.

• #last - true if this is the last iteration; false otherwise.

• #curFile - the file name of the current file in the loop.

• #curFullFile - the library and file name of the current file in the loop.

• #curFileCorrel - the user-specified correlation for this file, or blank if no correlation was specified.

• #joined - true if this file is the main file or if this file is joined to the main file; false otherwise.

• #isMainfile - true if this file is the main file specified in the JumpStart interface; false otherwise

• #curLongFile - long SQL name of current file, or same as #curFile if name is not long.¹

• #curFileFieldCount - number of fields in the current file.¹

• #curFileIsLogical - true if the current file is a logical file; false if it is physical.¹

• #curFileIsSqlView - true if the current file is an SQL view; false otherwise.¹

• #curFileDescription - the 50-character description of the current file object.¹

¹These fields are available in versions of Profound UI later than Version 6 Fix Pack 2.1.

SQL From Clause Loop

JumpStart (in Profound UI Version 5, Fix Pack 8.0 and later) provides an interface to join multiple files. The interface also allows correlation names to be chosen for files. JumpStart generates the From-clause, Join conditions, and correlation names for you. To avoid generating code too long for a line in an RPG source member, each join condition is split up into pieces, with the "FROM ___" as the first piece.

You can generate the From clause of a query using using this loop:

• #for each fromclause / #endfor

One variable is available inside the fromclause loop:

• #clausestring - part of the generated From string.

The first string is "FROM ", followed by the main file chosen (with library name, if specified), and followed by the correlation, if the user specified it.

Macro Expressions

JumpStart can evaluate JavaScript expressions in your RPG and PHP templates*. The #eval() macro generates output and can be used multiple times in a single line. The #evalQ() macro evaluates JavaScript quietly, without generating a line of source code. #evalQ() is useful in pre-processing for constructing complicated strings to be output later in the generated code. A line containing #evalQ() is not output in the generated source code.

For example with #eval(), suppose you want to name an RPG procedure based on the name of the generated program excluding the last character. To accomplish that, you would use an expression like this:

If the generated program name is to be JMPSTR001R, then the resulting code would be this:

Macro expressions are evaluated after the template pre-processor removes comments and processes variables, for-loops, else-, and if-statements.

Note, then, that in the example above when the macro is processed, "#program" would be a valid JavaScript string; e.g. "JMPSTR001R". Also, the quotes (") are necessary in this example. Otherwise, JavaScript would not handle JMPSTR001R as a string and would throw an exception.

You may use any valid JavaScript function or expression that returns a string in #eval(). If the expression returns undefined, then the #eval() expression is replaced with the literal text, undefined. If the expression throws a JavaScript exception, then an error is displayed, and processing halts.

Variables set in #evalQ should be declared globally. Otherwise, the variable's scope is lost, and the variable is undefined in later calls to #evalQ() or #eval().

#evalQ() Example 1

This code generates part of a query string on a single line instead of generating a line for each field. Unlike RGP, PHP has no limit on the length of the source code line.

Using the PUISAMPLES/PRODP file, the generated code would include the single line:

Hint: To avoid possible name conflicts with JumpStart internal JavaScript variables, avoid short variable names, such as a, b, c, i, j, x,y, z.. Instead, perhaps use a prefix "tmpl_" for variable names used in the template macros.

#evalQ Example 2
In the code below, evalQ gets the value of #parentCorrel, if #parentCorrel is not empty; or it uses the value of #parentFile. Then "." and the database field name are appedned to the end. Later, the string generated in the evalQ macro is output. Without evalQ, the code below would need an additional, nested #if/#else for each case, resulting in some duplicate template code.

Using part of the PUISAMPLES/PRODP file, (not specifying COALESCE), the generated code is below:

*#eval() is available with Profound UI Version 5, Fix Pack 7.0 and later; #evalQ() is available with Version 5, Fix Pack 8.0 and later.

#eval() and #newfile Example

This example shows how to dynamically generate two new files named from part of the main script's filename:

So if the Main script were named index042.php, then in addition to index042.php being generated, two more files would be generated: index042A.php and index042B.php.

Other Template Directives

RPG, Profound.js (Node.js), PHP, and Universal Display File Directives

Example Append:

Some functions' parameter lists depend on the number of fields in a file. A "#for each" loop can be used to select each field, but the loop outputs each field on a new line. This is the template segment:

Without Append

The resulting output without append:

Without Append

If the template is changed to take advantage of append:

With Append

Then the resulting function declaration only takes one line:

With Append

RPG and Universal Display File Template Directives

These directives can be used inside either RPG code templates or Universal Display File templates.

Example Template Error:

After a user clicks "Generate Application" in Jumpstart and no key fields were chosen, then the code above stops the generator and displays an alert:

Open

Example Template Notice:

The code above comes from a Universal Display File (web-service) template. Only two fields are expected in the JSON response, so the template sends hints to the user if more than 2 fields were used:

Open

Note that Jumpstart always sends the "Web Connector" hint when a web-service template was used.

RPG Template Directives

If the template includes a #newfile directive, then these directives apply to the most recent #newfile directive. If these directives are on a line before any #newfile directives (or if there are no #newfile's), then each directive applies to the source member specified in the RPG Program Name field. The must be no spaces between the beginning of a line and the beginning of the directive.

Example Directives in an RPG Template

Rich Display File Directives

Adapting Templates for Multiple Files, Joins, Correlations, Coalesce

Profound UI Version 5, Fix Pack 8.0 and later support some new features, including Joins, user-specifed field names, correlations, and alternate values for null-capable fields (via coalesce). Templates designed for older versions will generate the same code as before if the user doesn't change the field names in Field Selection.

To take advantage of the new features, the developer should be mindful of a few things:

• The #field variable can be user-specified, so parts of some templates should use #dbfield instead of #field. Specifically, when generating SQL statements, #dbfield should be used.

• Instead of using "SELECT * FROM #fullFile " in a template, field loops and the from-clause loop should be used. See the examples below.

• Loops creating code for UPDATE and INSERT statements should use "#for each nonGeneratedAlways inMain" instead of "#for each nonGeneratedAlways" to avoid including fields from extra files in the query.

• With RPG, the Table_In and Table_Out data structures used in the old Standard template are no longer correct when using multiple files. These structures should be generated using new directives, as demonstrated below.

Note: key fields from extra files are not select-able in the interface. Thus, "#for each key field" only iterates on fields from the main file, and inMain is not needed.

Example Generate Data Structure for Multiple Files

In our Standard RPG template, we chose to use a single data structure to hold query results from multiple files.

The output from two joined files, one specified with a library name, would be of the form:

Example Select-From-Join Generation

The following template snippet generates the Select-From-Join portion of a SQL query. It supports Joins, handles null-capable fields via COALESCE, and uses the correlation if the user-specified it.

The output from two joined files, one specified with a library name, correlations chosen, and a coalesce value specified would be of the form:

The Standard.rpgle template installed with Profound UI fully supports these new features.

Note: The new #eval() and #evalQ() macros are available for generating text in fewer lines of template code than before.