Promotic
WikipediaLinkedInYoutubeTwitterFacebook

Source file description of the PmReport object

The technology of the PmReport object is oriented especially at HTML and XML format source files and therefore it is necessary to have some HTML syntax knowledge including some related CSS styles. Simple TXT files can also be used.
 
For easy understanding of following descriptions it is handy to check out Report example.
 

Basic principle

The basic principle of the PmReport object is, reading the source file, finding the commands and executing them. The command syntax in the source file is always <!--Pm:xxxxxxxx--> where xxxxxxxx is the command body (<!-- --> represents the HTML note, therefore it is possible to browse the HTML source text for example with the Internet Explorer eventhough there are the commands included).

Executing the command will always modify the contents of the source file with the command itself being removed from the content.

 
Most of the commands are used with parameters. These parameters affect executing of the command. The parameter values can be:
- Constant (text - for example "hello", numbers - for example 3.14)
- key value entered into the PmReport object by the SetKeyValue method (creating the content from the application current data). For example if in the PmReport object, there is a key SetKeyValue("txt1","The boiler temperature exceeded 80 degrees Centigrade"), then the command can be linked to a key text by the key.txt1 identifier.
- Macro expression, that is evaluated during command execution. For example Macro expression $.text can be handy for entering localized texts. Macro expression $vb cannot be used.
- The value of cycle command - see further for commands Pm:Cycle....
- Expressions in JavaScript syntax, e.g. 1+key.val1. See The JavaScript operators and syntax description.

Pm:SetText - Command for direct text input

The whole command is replaced by the text evaluated by this command
 
Syntax:
<!--Pm:SetText(sValue)-->
 
Parameters:
- sValue: the value (text), that will replace (overwrite) the command
 
Example1:
With following setting:
oReport.SetKeyValue("value1", "The boiler temperature exceeded 80 degrees Centigrade")
then the source file will contain the section:
<!--Pm:SetText(key.value1)-->
replaced by text:
The boiler temperature exceeded 80 degrees Centigrade
Example2:
Usng the Macro expression $.text, the command will be replaced by localized text with the txt1 identifier.
<!--Pm:SetText($.text("app","txt1")-->
 

Pm:TagSetValue - Command for changing the tag value

The command will enter or change the value of following HTML or XML tag (this command is not available for TXT source files)
 
Syntax:
<!--Pm:TagSetValue(sValue)-->
 
Parameters:
- sValue: the value that will be entered into the HTML/XML tag
 
Example:
With following setting:
oReport.SetKeyValue("value1", "The boiler temperature exceeded 80 degrees Centigrade")
then the source file will contain the section:
<!--Pm:TagSetValue(key.value1)-->
<h1></h1>
replaced by text:
<h1>The boiler temperature exceeded 80 degrees Centigrade</h1>
 

Pm:TagSetAttr - Command for changing tag attribute

The command will enter or change the value of the attribute directly following the HTML or XML tag (this command is not available for TXT source files).
 
Syntax:
<!--Pm:TagSetAttr(sName,sValue)-->
 
Parameters:
- sName: the name of HTML/XML attribute
- sValue: the value that will be entered into the HTML/XML attribute
 
Example1:
With following setting:
oReport.SetKeyValue("value2", "xyz")
then the source file will contain the section:
<!--Pm:TagSetAttr("class",key.value2)-->
<h1>Title</h1>
replaced by text:
<h1 class="xyz">Title</h1>
Example2:
Using the $.path("appres") expression will enter the path to picture.jpg into the src attribute of the img tag.
<!--Pm:TagSetAttr("src",#appres:picture.jpg)-->
<img src="" title="picture.jpg"/>
 

Pm:TagSetStyle - Command for changing the tag style

The command will enter or change the style value directly following the HTML or XML tag (this command is not available for TXT source files).
 
Syntax:
<!--Pm:TagSetStyle(sName,sValue)-->
 
Parameters:
- sName: the name of the HTML CSS style
- sValue: the value that will be entered into the HTML CSS style
 
Example:
With following setting:
oReport.SetKeyValue("value2", "#ff0000")
then the source file will contain the section:
<!--Pm:TagSetStyle("background-color",key.value2)-->
<h1>Title</h1>
replaced by text:
<h1 style="background-color:#ff0000;">Title</h1>
 

Pm:If.. (Pm:If..Pm:IfElse)- Command for evaluating a simple condition

The expressions in the condition can contain constants, keyword values, variables from cycle. One row form (first syntax) can be used for short, simple tests. The block form (second syntax) offers more flexibility and complexity than the on row form. The condition is tested when executing the block. If the condition is true, then the following commands are executed. If the condition is false (second syntax), the commands in the IfElse are executed.
 
Syntax:
<!--Pm:IfBegin(condition)-->
...
<!--Pm:IfEnd-->
 
or:
<!--Pm:IfBegin(condition)-->
...
<!--Pm:IfElse-->
...
<!--Pm:IfEnd-->
 
Condition syntax:
Value1 == Value2 : equal
Value1 != Value2 : is not equal
Value1 < Value2 : less than
Value1 > Value2 : greater than
Value1 <= Value2 : less or equal
Value1 >= Value2 : greater or equal
 
Example1:
With following setting:
oReport.SetKeyValue("req", 3)
then the source file will contain the section:
<!--Pm:IfBegin(key.req==3)-->
  <p>test</p>
<!--Pm:IfEnd-->
replaced by text:
  <p>test</p>
otherwise the whole section including the text between these two commands is removed.
 
Example2:
With following setting:
oReport.SetKeyValue("req", 3)
then the source file will contain the section:
<!--Pm:IfBegin(key.req!=3)-->
  <p>test1</p>
<!--Pm:IfElse-->
  <p>test2</p>
<!--Pm:IfEnd-->
replaced by text:
  <p>test2</p>
otherwise the whole section including the text between these two commands is removed.
 

Pm:VarSet - A command for creating and configuring the value of the variable

This command creates and configures the value of the variable. This variable can be used in following commands when creating the template.
 
Syntax:
<!--Pm:VarSet(sKey,sKeyName,Value)-->
 
Parameters:
- sKey: Key
- sKeyName: Variable name
- Value: Variable value
 
Example1:
Creates the bDone variable, and enters the value of 1.
<!--Pm:VarSet("key","bDone",1)-->
Example2:
Tests whether the input value bDone has been entered. If not, then the variable is created and the value of 0 is entered.
<!--Pm:IfBegin(!key.bDone)-->
  <!--Pm:VarSet("key","bDone",0)-->
<!--Pm:IfEnd-->

PmLib.GetArraySize - Detecting the dimensions of the array

Returns 1- or 2-dimensional variables of the array type.
 
Syntax:
PmLib.GetArraySize(key.arr,n)
 
Parameters:
- arr: array variable name
- n: 1 for detecting the first dimension or 0 for the second dimension
for detecting the first dimension also the short syntax can be used:PmLib.GetArraySize(key.arr)

Pm:Cycle... - Comand for single phase text multiplication (simple cycle)

This command is used for simple text multiplication meaning: E.g. there is the following tag in the source file :
<p> </p>
and it is necessary to fill all the values from the value array into this tag. I.e. we want to multiply the tag with the following result:
<p>1234</p>
<p>3.14</p>
<p>56.8</p>
<p>-345</p>
Exactly this need is being solved by this command. The most common usage of this command is, for example, for multiplying the rows in a table (i.e. for multiplying the <tr> tag in the <table> tag) - see Example3. But the concept is general and can be used also, for example, for multiplying the values in a text file, etc.
 
Syntax:
<!--Pm:CycleBegin(sId,PmLib.GetArraySize(key.arr,1))-->
... (the multiplied texts and another commands, for example Pm:TagSetValue)
<!--Pm:CycleEnd(sId)-->
 
Parameters:
- sId: cycle identifier. CycleBegin and corresponding CycleEnd must have identic identifier. The identifier is used for locating the cycle variable (the syntax for example id.sId.Index).
- PmLib.GetArraySize(key.arr,1): multiplication count (e.g. the number of rows)
 
Cycle variables (these variables can be used for commands inside the cycle):
- id.sId.Index: cycle index (zero-based index), e.g. the number of processed row.
- PmLib.GetArraySize(key.arr,1): the number of items, e.g. the total number of rows.
 
Example3:
The SetKeyValue method saves a two-dimensional array into the arr key. The number of columns of this array is always 3, the number of rows is variable and saved into the rows key. The comman in the source file can be as follows:
<table>
  <tr>
    <th>Col1</th>
    <th>Col2</th>
    <th>Col3</th>
  </tr>
  <!--Pm:CycleBegin("cyc",PmLib.GetArraySize(key.arr,1))-->
  <tr>
    <!--Pm:TagSetValue(key.arr[0][id.cyc.Index+1])-->
    <td></td>
    <!--Pm:TagSetValue(key.arr[1][id.cyc.Index+1])-->
    <td></td>
    <!--Pm:TagSetValue(key.arr[2][id.cyc.Index+1])-->
    <td></td>
  </tr>
  <!--Pm:CycleEnd("cyc")-->
</table>
 

Pm:CyclePage... / Pm:CycleLine... - Commands for two-phase text multiplication (double cycle)

This command generalises the previous simple cycle adding the possibility for example not only to multiply the table rows, but also the tables itself. This can solv the problem when the row number of the table is too high and the table is to be separated into multiple sections in order e.g. to have each page printed with its header, etc. The need is to enter a large value array (ane row one value) and let this command to divide the values into tables and rows.

The whole command consists of the outer command Pm:CyclePage.. (solving tables multiplication, each table on one page) and inner command Pm:CycleLine.. (solving the rows multiplication inside the table).

The terms "table", "row", "page" are just auxiliary. The concept of the command is general and does not have to solve just the division of rows into tables and pages. The command also does not solve the physical paging for HTML printing.

 
Syntax:
<!--Pm:CyclePageBegin(sId,PmLib.GetArraySize(key.arr,1),nCountFirstPage,nCountNextPages)-->
... (multiplied texts and commands, for example the header of each page)
<!--Pm:CycleLineBegin(sId)-->
... (multiplied texts and commands, for example table rows)
<!--Pm:CycleLineEnd(sId)-->
... (multiplied texts and commands, for example the footer of each page)
<!--Pm:CyclePageEnd(sId)-->
 
Parameters:
- sId: the cycle identifier. CyclePageBegin and corresponding CycleLineBeginEnd, CycleLineEnd and CyclePageEnd must have identic identifier. The identifier is also used for locating the cycle variable (the syntax for example id.sId.Index).
- PmLib.GetArraySize(key.arr,1): the total number of multiplication, for example the total row number in all tables
- nCountFirstPage: the number in the first command cycle Pm.CycleLine... Allows, for example, to specify different row number for the first table and following tables.
- nCountNextPage: the number in the following command cycles Pm.CycleLine.. (the number of rows in following tables).
 
Cycle variables (these variables can be used for commands inside the cycle):
- id.sId.Index: the total cycle index (zero-based index), for example the number of processed line for all tables.
- PmLib.GetArraySize(key.arr,1): the total number of items, for example the total row number for all tables.
- id.sId.PageIndex: the inner cycle processing index (zero-based index), for example the page (table) number.
- id.sId.PageCount: the total number of inner cycles processing, for example the total page number.
- id.sId.LineIndex: the item index processed by the inner cycle (zero-based index), for example the number of the row in current table.
- id.sId.LineCount: the number of items processed by the inner cycle, for example the number of rows in current table.
 
Example:
The method SetKeyValue saves a two-dimensional array into the arr key. The column number of this array is always 3, the number of rows is variable, saved into the rows key. Because the rows number may be high (e.g. 300), we want the output report to be saved into several tables, the first table cointaining max 35 rows and the following tables max 40 rows. The number of tables will be sufficient in order to display all rows of the array. Each table will have the header with column names (Col1, Col2, Col3). The command in the source file may look as follws:
<!--Pm:CyclePageBegin("cyc",PmLib.GetArraySize(key.arr,1),35,40)-->
<table>
  <tr>
    <th>Col1</th>
    <th>Col2</th>
    <th>Col3</th>
  </tr>
  <!--CycleLineBegin("cyc")-->
  <tr>
    <!--Pm:TagSetValue(key.arr[0][id.cyc.Index+1])-->
    <td></td>
    <!--Pm:TagSetValue(key.arr[1][id.cyc.Index+1])-->
    <td></td>
    <!--Pm:TagSetValue(key.arr[2][id.cyc.Index+1])-->
    <td></td>
  </tr>
  <!--Pm:CycleLineEnd("cyc")-->
</table>
<br/>
<!--Pm:CyclePageEnd("cyc")-->
 
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice