The technology of the
PmaReport 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 examples.
Basic principle
The basic principle of the
PmaReport object is, reading the source file, finding the statements and executing them. The statement syntax in the source file is always
<!--Pm:xxxxxxxx--> where
xxxxxxxx is the command body (
<!-- --> represents the HTML note and therefore it is possible to browse the HTML source text for example in the Web browser even if there are the statements included).
Executing the command will always modify the content of the source file with the command itself being removed from the content.
Most of statements are used with parameters. These parameters affect executing of the statement. The parameter values can be:
- Constant (text - for example "hello", number - for example 3.14)
-
key value entered into the
PmaReport object by the
SetKeyValue method (creating the content from the application current data). For example if into the
PmaReport object is inserted a key
SetKeyValue("txt1","The boiler temperature exceeded 80 degrees Centigrade"), then the statement can be linked to a key text by the
key.txt1 identifier.
-
The value of cycle statement - see further for statements
Pm:Cycle....
Pm:SetText - Statement for direct text input
The whole statement is replaced by the text evaluated by this command
Syntax:
<!--Pm:SetText(sValue)-->
Parameters:
- sValue: The value (text), that will replace (overwrite) the statement
Example1:
If the 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:
<!--Pm:SetText($.text("app","txt1")-->Pm:TagSetValue - Statement for changing the tag value
The statement will enter or change the value of following HTML or XML tag (this statement 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:
If the 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 - Statement for changing tag attribute
The statement will enter or change the value of the attribute directly following the HTML or XML tag (this statement 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:
If the following setting:
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", $.path("appres","picture.jpg"))-->
<img src="" title="picture.jpg"/>
Pm:TagSetStyle - Statement for changing the tag style
The statement will enter or change the style value directly following the HTML or XML tag (this statement 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:
If the following setting:
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)- Statement for evaluating a simple condition
The expressions in the condition can contain constants, keyword values, variables from cycle. One row form (1st syntax) can be used for short, simple tests. The block form (2nd 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 statements are executed. If the condition is
false (2nd syntax), then the statements in the
IfElse are executed.
Syntax:
<!--Pm:IfBegin(condition)-->
...
<!--Pm:IfEnd-->
or:
<!--Pm:IfBegin(condition)-->
...
<!--Pm:IfElse-->
...
<!--Pm:IfEnd-->
Condition syntax:
Value1 == Value2 : equal to
Value1 != Value2 : not equal to
Value1 < Value2 : less than
Value1 > Value2 : greater than
Value1 <= Value2 : less or equal
Value1 >= Value2 : greater or equal
Example1:
If the following setting:
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 statements is removed.
Example2:
If the following setting:
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 statements is removed.
Pm:VarSet - Statement for creating and configuring the value of the variable
This statement creates and sets the value of the variable. This variable can be used in following statements when creating the template.
Syntax:
<!--Pm:VarSet(sKey,sKeyName,Value)-->
Parameters:
- sKey: Key
- sKeyName: Name of the variable
- Value: Variable value
Example1:
Creates the bDone variable, and enters the value of 1.
<!--Pm:VarSet("key","bDone",1)-->
Example2:
Test 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 - Detects the dimensions of the array
Returns 1st or 2nd dimension of the variable 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... - Statement for single phase text multiplication (simple cycle)
This statement is used for simple text multiplication meaning: E.g. there is the following tag in the source file:
and it is necessary to fill all the values from the value array into this tag. It means that 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 statement. The most common usage of this statement is, for example, for multiplying the rows in the 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 statements, for example Pm:TagSetValue)
<!--Pm:CycleEnd(sId)-->
Parameters:
- sId: cycle identifier. CycleBegin and corresponding CycleEnd must have identic identifier. The identifier is used for detecting the cycle variable (in the form for example id.sId.Index).
- PmLib.GetArraySize(key.arr,1): multiplication count (e.g. number of rows)
Cycle variables (these variables can be used for statements inside the cycle):
- id.sId.Index: cycle index (zero-based index), e.g. the index 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 2-dimensional array into the
arr key. The number of columns of the array is always 3, the number of rows is variable and saved into the
rows key. The command 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... - Statement for two-phase text multiplication (double cycle)
This statement 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 number of rows in the table is too high and the table is to be separated into multiple sections in order to have each page printed with its header, etc. The need is to enter a large array of values (one row one value) and let this statement to divide the values into tables and rows.
The whole statement consists of the outer statement
Pm:CyclePage.. (solving tables multiplication, each table on one page) and inner statement
Pm:CycleLine.. (solving the rows multiplication in the table).
The terms "table", "row", "page" are just auxiliary. The concept of the statement is general and does not have to solve just the division of rows into tables and pages. The statement also does not solve the physical paging for HTML printing.
Syntax:
<!--Pm:CyclePageBegin(sId,PmLib.GetArraySize(key.arr,1),nCountFirstPage,nCountNextPages)-->
... (multiplied texts and statements, for example the header of each table)
<!--Pm:CycleLineBegin(sId)-->
... (multiplied texts and statements, for example table rows)
<!--Pm:CycleLineEnd(sId)-->
... (multiplied texts and statements, for example the footer of each table)
<!--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 detecting the cycle variable (in the form for example id.sId.Index).
- PmLib.GetArraySize(key.arr,1): The total number of multiplication, for example the total number of rows in all tables
- nCountFirstPage: the number in the first statement cycle Pm.CycleLine... Allows, for example, to specify different number of rows for the first table and following tables.
- nCountNextPage: the number in the following statement cycles Pm.CycleLine.. (number of rows in following tables).
Cycle variables (these variables can be used for statements inside the cycle):
- id.sId.Index: the total cycle index (zero-based index), for example the index of processed line for all tables.
- PmLib.GetArraySize(key.arr,1): The total number of items, for example the total number of rows 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 number of pages.
- id.sId.LineIndex: the item index processed by the inner cycle (zero-based index), for example the row index in current table.
- id.sId.LineCount: the number of items processed by the inner cycle, for example number of rows in current table.
Example:
The
SetKeyValue method saves a 2-dimensional array into the
arr key. The number of columns of the 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 result 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 statement 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")-->