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 examples.
 

Basic principle

The basic principle of the PmReport 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, therefore it is possible to browse the HTML source text for example with the Internet Explorer even if there are the statements 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 statements are used with parameters. These parameters affect executing of the statement. 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 statement can be linked to a key text by the key.txt1 identifier.
- Macro expression, that is evaluated during statement execution. For example Macro expression $.text can be handy for entering localized texts. Macro expression $vb cannot be used.
- The value of cycle statement - see further for statements Pm:Cycle....
- Expressions in JavaScript syntax, e.g. 1+key.val1. See The JavaScript operators and syntax description.

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:
Usng the Macro expression $.text, the statement will be replaced by localized text with the txt1 identifier.
<!--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:
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 - 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:
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)- 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:
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 statements is removed.
 
Example2:
If the 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 statements is removed.
 

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

This statement creates and configures 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: 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 1st or 2nd dimension of 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... - 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:
<p> </p>
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 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 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 locating the cycle variable (in the form 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 statements 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 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 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 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 inside 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 page)
<!--Pm:CycleLineBegin(sId)-->
... (multiplied texts and statements, for example table rows)
<!--Pm:CycleLineEnd(sId)-->
... (multiplied texts and statements, 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 (in the form 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 statement cycle Pm.CycleLine... Allows, for example, to specify different row number for the first table and following tables.
- nCountNextPage: the number in the following statement cycles Pm.CycleLine.. (the 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 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 number of columns 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 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")-->
 
PROMOTIC 8.3.22 SCADA system documentation - MICROSYS, spol. s r.o.

Send page remarkContact responsible person
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice