Promotic
WikipediaLinkedInYoutubeTwitterFacebook

Object viewer open

Some PROMOTIC objects have viewers of the corresponding content. This chapter describes the viewer opening procedures in running applications (runtime).

Be advised that all objects do not have, for example, internal method for displaying their corresponding content (although it seems logical in reality it is not practical). The functionality is based on commands that "open the object viewer" with parameter sObjectPath that defines path to corresponding object.

 
Object that have a viewer of coresponding content:
- PmPanel: viewer of the user graphics
- PmReport: viewer of dynamicaly generated HTML report
- PmWorkspace: divide the main window into smaller portions
- PmAlarmEvent: viewer of alarm/event group status and history
- PmWeb: viewing Web pages of PROMOTIC applications
- PmWebDir: viewing HTML pages provided by this object
- PmWebFolder: viewing HTML pages provided by this object
- PmWebLang: viewing HTML pages provided by this object
 
In addition to the viewers of objects mentioned above it is also possible to open global component viewers:
- Viewer for PmForm object (path: "/#glob/form")
- WWW pages viewer (path: "/#glob/webbrowser")
- Viewer for INFO system (path: "/#glob/infosystem")
 
The possible ways of opening the object viewer:
 
1) Static configuration:
a) in the PmWorkspace object (see the configurator "Viewer of component" and "Params default value"). This way, it is possible to open any viewers automatically at application launch in specific PmWorkspace frames.
b) in PmiWFrame graphic item (see the configurator "Viewer"). This way, it is possible to open any viewer in PmiWFrame graph icitem while being opened.
 
2) Dynamically by script using the OpenView methods:

The set of these methods allows to open any viewer within the framework of the PmWorkspace object, in PmiWFrame graphic item, or as a standalone window. Method is very handy and therefore it has been implemented into multiple objects:

The method is asynchronous, i.e. the method only activates the opening of corresponding viewer (and/or closing the previous viewer), but after the method is completed the viewer may not yet be open.

Caution!Any viewer can be opened in the PmiWFrame graphic item only by using the PmiWFrame.OpenView method.

 
Displaying the content viewer of any object is managed the unified way. Generally you need the following four parameters:
 

sObjectPath

(String) Path (relative or absolute) to the object or component whose viewer will be opened.
 
The path to the objects is allowed: PmPanel, PmReport, PmAlarmEvent, PmWorkspace, PmWeb, PmWebFolder, PmWebDir, PmWebInfo, PmWebLang.
PmAlarmEvent object: The object provides two viewers (state a history), therefore it is possible to add to sObjectPath, following the object path, a text /#state for state viewer or a text /#history for history viewer. If the viewer type is not defined then the alarms are opened in state viewer, and the events are opened in history viewer.
 
or a path to global components can be used here:
"/#glob/form": Opening a form PmForm that can be used in order to create items dynamicaly (i.e. by script). These items can then be used for data displaying or data input. In this case the value oExtra.ViewObject must be set to existing object PmForm. See Form creation procedure.
"/#glob/webbrowser": General HTML page viewer (on the web or on local disc). See Example of web browser opening.
"/#glob/infosystem": Viewer for INFO system. See Example and see How to open the INFO system.

sOptions

(String) The parameters transfered to the viewer. These define where and how to open the viewer.

Entries with assigned value are separated by a semicolon, for example "target:_blank;modal:1;".

 
For viewers of objects PmPanel and PmReport: The static default sOptions values can be set in the configurator PmPanel > Panel > sOptions default value or in the configurator PmReport > Report > sOptions default value. In such case the static default setup of the object is combined with the entries provided dynamically. If the same information is present on both places, the dynamical information provided at viewer opening is preferred by the system.
 
target:xx; - Defines where will viewer be opened.
If not defined otherwise, the following settings are used as default:
- if the window is open as modal (set as "modal:1;"), then "target:_blank;" is set.
- if the window is open by the PmPanel.OpenView method then "target:_self;" is set.
- if the window is open by the PmWorkspace.OpenView method then the main frame identifier in this workspace is used (defined in Default frame configurator).
- if the window is open by the PmiWFrame.OpenView method then this entry is not used (the viewer is always displayed in the PmiWFrame item).
target:frameid; - The new viewer is opened in PmWorkspace object in frame with frameid identifier.
target:_blank; - The new viewer is opened in a new window.
target:_self; - The new viewer is opened in the current window (frame) and the viewer, over which the method was called, is closed.
scrollbar:nn; - Defines whether the window will have the scroll bars for moving the contents, if the panel size is greater than the size of the window, the panel is inside.
scrollbar:0; - The scrollbars will not be displayed and therefore the content cannot be scrolled. It is handy for example for a window of the "toolbar" type, where the window is very narrow.
scrollbar:1; (default) - The window will display the scrollbars automatiacally thus allwing to scroll the panel, if the panel size is greater than the size of the window, the panel is inside.
refresh:xx; - Only for opening the PmPanel object viewer. Defines whether the panel has the automatic refresh according to the globally set system period or the panel has its own refresh rate. So far it is not functional when opening WEB panel.
refresh:0; - The panel will have its own refresh, i.e. the PmPanel.Refresh method will be called.
refresh:system; (default) - The panel will have the automatic refresh according to the globally set system period (See PmRoot > Application > Panels timer period).
viewtype:xx; - Only for opening the PmAlarmEvent object viewers. Defines whether the full historic/state viewer is opened (including all control buttons), or just the table (data) version (with no control buttons).
viewtype:full; (default) - Full historic/state alarm/event viewer is opened, including all control buttons.
viewtype:data; - Table (data) version of historic/state alarm/event viewer with no control buttons is opened.
 
The following entries are relevant only when opening in new window (i.e. with "target:_blank;"):
 
modal:nn; - Defines the modal window option.
modal:0; (default) - The window will not be modal.
modal:1; - The window will be modal.
dependent:nn; - Defines the window dependency on the application main window.
dependent:0; - The window will be independent on the application main window. So far it is not functional when opening WEB panel.
dependent:1; (default) - The window will be dependent on the application main window.
caption:nn; - Defines whether the window has the header or not (i.e. the blue stripe on top).
caption:0; - The window will have no header. So far it is not functional when opening WEB panel.
caption:1; (default) - The window will have the header.
ontop:nn; - Defines whether the window will be "Always on top".
ontop:0; (default) - The window will not be "Always on top".
ontop:1; - The window will be "Always on top". So far it is not functional when opening WEB panel.
state:xx; - Defines the initial state of the window.
state:normal; (default) - The window will be displayed normally (neither maximalized nor minimalized).
state:max; - The window will be maximalized. So far it is not functional when opening WEB panel.
pos:xx; - Defines the initial position of the window in normal state.
pos:top,center; (default) - The window will be displayed in the center of the active application window (workspace).
pos:top,x,y; - The window will have the top left corner in coordinates x and y (in pixels) relative to the active application window (workspace).
pos:frame,center; - The window will be displayed in the center of the window from which the new window was opened.
pos:view,x,y; - The window will have the top left corner in coordinates x and y (in pixels) relative to content of the window from which it is opened.

The position is set as relative to window content (view) and not to the window itself (frame). This way it is possible for example to place the new window aside from the graphic item the window was opened from. See Example of window opening and placing according to the graphic item position.

size:xx; - Defines the initial size of the window in normal state.
size:panel; (default) - The size of the window will be set in order to contain the whole opened panel (i.e. no scrollbars are created). Width and height of the panel is defined in the panel editor in PmiRoot object on the Panel page.
size:dx,dy; - The size of the window will be defined by the dx and dy values (in pixels). These values define the outer size of the window (i.e. inctluding the margins and window title bar).
fixed:xx,yy,..; - Allows to disable the change of state, position and panel size. It is defined as a list of prohibitions separated by "comma" (,). So far it is not functional when opening WEB panel. The preset value is: everything is enabled.
state - Forbids to change the window state (normal / maximized / minimized).
pos - Forbids to change the position of the window in normal state.
size - Forbids to change the size of the window in normal state.
size2 - Disables changing the size of the window in normal state - the window size cannot be larger than the size of corresponding panel.

sParams

(String) Parameters transfered to the object that is to be viewed by the corresponding viewer.

Entries with assigned value are separated by a semicolon, for example "name1:value1;name2:value2;".

These parameters usually parametrize or filter the content of the corresponding viewed object and are depending on the opened object type.

 
PmPanel: Allows to set the value of parameters of PmiRoot graphic item. This parameter is then accessible in the panel configurators by the Macro expression $.par and from the script by the GetPar method. Each parameter consists of an identifier (name) and a value. Syntax: "par:name1=value1;par:name2=value2; ...". See also: Parameters of graphic item.

The static default sParams parameter values can be set in the configurator PmPanel > Panel > sParams default value. In such case the static default setup of the object is combined with the entries provided dynamically. If the same information is present on both places, the dynamical information provided at viewer opening is preferred by the system.

 
PmReport: Allows to set the value of report parameters. These parameters are then accessible in the pEvent.Pars parameter in onReportRequest event. Each parameter consists of an identifier and a value.

Syntax: "par:name1=value1;par:name2=value2; ...".

The static default sParams parameter values can be set in the configurator PmReport > Report > sParams default value. In such case the static default setup of the object is combined with the entries provided dynamically. If the same information is present on both places, the dynamical information provided at viewer opening is preferred by the system.

 
PmWorkspace: Not used.
 
PmWebDir: "file:xx;" = The file with the extension (e.g. file:MyPage.htm), to be displayed. This file must be placed in a folder offered to WEB by PmWebDir (see the configurator "Folder with files"). If the file is located in subfolder, then the file parameter must be entered using the "subfolder/file" syntax. If the file parameter is not specified, then "default.htm" will be opened and if no such file exists, then a dynamicaly created HTML page with file list is opened.
 
"/#glob/webbrowser": Allows to set the address of the HTML page to be displayed. Syntax: "url:http://www.promotic.eu;".

The address must be defined in full syntax including the protocol: (http://, https:// or file://).

 
"/#glob/form": Not used.
"/#glob/infosystem": Not used.
 
PmAlarmEvent: Filtering text that specifies which alarms/events are to be included into the desired output.

Different filtration fields can be used simultaneously, the alarm/event then must comply with all of them (e.g. "desc:FIQ100;priority.ge:5;").

The filtering text xx cannot be empty (e.g. it is not possible to enter "desc:;").

Entries with assigned value are separated by a semicolon, for example "desc:Test2;records:50;".
 

The folowing types of filtration texts exist (where "field" represents some of the alarm columns):

"field:xx;" means that the corresponding alarm field must be equal to the value of xx.
"field:#eq:xx;" means that the corresponding alarm field must be equal to the text xx. If the corresponding alarm field is to be equal to one of several texts, it is possible to enter multiple texts separated by #or: (OR operator).
"field:#begin:xx;" means that the corresponding alarm field must begin with the text xx. If the corresponding alarm field is to begin with some of several texts, it is possible to enter multiple texts separated by #or: (OR operator).
"field:#in:xx;" means that the corresponding alarm field must contain the textxx. If the corresponding alarm field is to contain some of several texts, it is possible to enter multiple texts separated by #or: (OR opertor).
"field:#le:xx;" means that the corresponding alarm field must be less or equal to xx.
"field:#ge:xx;" means that the corresponding alarm field must be greater or equal to xx.
 
Note! If the field begins with the text s., then this is the setting hidden from the enduser in the alarm/event viewer and it is used to set the definite script filtration independent on end user settings. Both filtration type fields can be used for a single column simultaneously. In order to let the alarm/event pass the filter it must comly to both filtering fields. This can be handy for definite script filtrations (independent on enduser) and also for setting the initial state of user defined filtration (that can be modified by the enduser). For example s.source:#begin:Boiler;source:Boiler1;.
 
"state:xx;" (optional) - Display alarms whose state equals to the state xx. Even several states, separated by comma, can be mentioned. For example "state:3,2,1;".
"hoot:xx;" (optional) - Display alarms by sound notification, where xx:
0 = alarms without sound
1 = alarms with sound
"area:#oper:xx;" (optional) - Show alarms with area observing the defined operation #oper:xx. The part of filter dependent on user setting in the alarm/event viewer. For example "area:BoilerPlant1;" or "area:#eq:BoilerPlant1;" or "area:#eq:BoilerPlant1#or:BoilerPlant2;" or "area:#begin:BoilerPlant;".
"s.area:#oper:xx;" (optional) - Show alarms with area observing the defined operation #oper:xx. The part of filter hidden from the user in the alarm/event viewer. For example "s.area:BoilerPlant1;" or "s.area:#eq:BoilerPlant1;" or "s.area:#eq:BoilerPlant1#or:BoilerPlant2;" or "s.area:#begin:BoilerPlant;".
"source:#oper:xx;" (optional) - Show alarms with source observing the defined operation #oper:xx. The part of filter dependent on user setting in the alarm/event viewer. For example "source:Boiler;" or "source:#eq:Boiler;" or "source:#eq:Boiler1#or:Boiler2;" or "source:#begin:Boiler;".
"s.source:#oper:xx;" (optional) - Show alarms with source observing the defined operation #oper:xx. The part of filter hidden from the user in the alarm/event viewer. For example "s.source:Boiler;" or "s.source:#eq:Boiler;" or "s.source:#eq:Boiler1#or:Boiler2;" or "s.source:#begin:Boiler;".
"desc:#oper:xx;" (optional) - Show alarms with description (desc) observing the defined operation #oper:xx. The part of filter dependent on user setting in the alarm/event viewer. For example "desc:FIQ101;" or "desc:#eq:FIQ101;" or "desc:#eq:FIQ101#or:FIQ102;" or "desc:#begin:FIQ;".
"s.desc:#oper:xx;" (optional) - Show alarms with description (desc) observing the defined operation #oper:xx. The part of filter hidden from the user in the alarm/event viewer. For example "s.desc:FIQ101;" or "s.desc:#eq:FIQ101;" or "s.desc:#eq:FIQ101#or:FIQ102;" or "s.desc:#begin:FIQ;".
"comment:#oper:xx;" (optional) - Show alarms with comment observing the defined operation #oper:xx. The part of filter dependent on user setting in the alarm/event viewer. For example "comment:correction;" or "comment:#eq:correction;" or "comment:#eq:correction#or:test;" or "comment:#begin:correction;".
"s.comment:#oper:xx;" (optional) - Show alarms with comment observing the defined operation #oper:xx. The part of filter hidden from the user in the alarm/event viewer. For example "s.comment:correction;" or "s.comment:#eq:correction;" or "s.comment:#eq:correction#or:test;" or "s.comment:#begin:correction;".
"priority:#oper:xx;" (optional) - Display alarms whose priority complies with the iperation #oper:xx. The part of filter dependent on user setting in the alarm/event viewer. For example "priority:5;" or "priority:#eq:5;" or "priority:#le:5;" or "priority:#ge:5;".
"from:xx;" (optional) - Display the alarms with time of creation (timeon) greater or equal to time "xx". The time is entered as time(YYYY.MM.DD-hh:mm:ss.mmm), e.g. from:time(2016.07.28-14:30:00.000); The time interval allows to narrow down the searched alarm set (the alarms outside the time interval are not tested).
"to:xx;" (optional) - Display the alarms with time of creation (timeon) less or equal to time "xx". The time is entered as time(YYYY.MM.DD-hh:mm:ss.mmm), e.g. from:time(2016.07.28-15:00:00.000); The to time can also be entered by the now keyword, which means the current time (at the moment of calling), e.g. to:now. The time interval allows to narrow down the searched alarm set (the alarms outside the time interval are not tested).
"timerange:xx;" (optional) - Display the alarms with the creation time (timeon) belonging to specified time interval For selecting the time interval by timerange, the value of from or to must be defied, then the timerange allows to compute the missing limit of the time interval. Thus the time interval can be defined by the following pairs: from - to, from - timerange or to - timerange. For example to:now;timerange:30m;. The time interval allows to reduce the portion of alarm items to be searched (the alarm items outside the time interval are not tested).

The time span can be entered as whole number followed by time unit sign (without space). Valid time units are: w = week, d = day, h = hour, m = minute, s = second. For example timerange:12h; or timerange:90m;.

"viewsort:columnid.dir;" (optional) - Defines the first column for sorting. The following syntag is used: column identifier, separator period (.), direction ascending (a) / descending (d). The status viewer can use sorting based on any column (ascending/descending). The status viewer sorts always based on the timestamp of origin (timeon) ascending/descending. The predefined sorting is time based ascending.For example"viewsort:timeon.a;".

oExtra

(Object) Additional entry of viewer behavior. The items are defined here by creating properties in the PmMap type object (this is a difference compared to previous parameters sOptions and sParams where the entry is added in text form) - this way it is possible to transfer general values (not only text).

The object is created by the Pm.CreatePmMap method.

 
Example of creating, filling and using the oExtra object:
var oExtra = Pm.CreatePmMap();
oExtra.onClose = Pm.CreatePmAction(1, pMe, "ClosePanel");
pMe.PmPanel.OpenView("/Boiler/Panel", "target:_blank;", "", oExtra);
 
List of properties that can be created in the object:
oExtra.Arguments (optional) - (Variant) Value passed to the viewer that is being opened. This value is then available in:
- oExtra.onOpen event (see further).
- panel PmPanel also later by the PmiRoot.Arguments property.

It can be a simple value (Integer, String, ..), array or object of the PmArray or PmMap type (it is not recommended to transfer objects of other types here).

Entering this value is often important, for example, if modal window is being opened in order to edit data. The Arguments property is then used as input initialization value (the ReturnValue property as modified input value) - see How to work with modal windows.

oExtra.ViewObject (optional) - (Variant) The PmForm object that is being viewed.

When viewing the PmForm object (i.e. if sObjectPath="/#glob/form" is used) then this value is set to dynamicaly created and configured PmForm object. See Form creation procedure.

For other viewer types, this value is irrelevant.

oExtra.onClose (optional) - (Object of the PmAction type) User method is defined here and is called when the panel closes.

The object for this property is created by the Pm.CreatePmAction method.

This user method must have two parameters:

- oSystem: Object of the PmMap type. The properties of this object are set by system based on the source of calling. In such case the system sets the following properties:
- oSystem.CloseReason: (String) Window closing type identifier.
- Entered when closing the PmPanel viewing window by the method PmiRoot.Close(sReason).
- When viewing the PmForm object, the identifier value depends on the button that has been used to close the viewer. See PmForm.SysButtons and PmForm.Close.
- When other objects are being viewed, this property is not set.
- oSystem.ReturnValue: (Variant) Output value of the viewer.
- When viewing the PmPanel object, it is possible to set the value by the PmiRoot.ReturnValue property.
- When other objects are being viewed, this property is not set.
- oSystem.ViewObject: (Object) The PmForm object that is being viewed.
- When other objects are being viewed, this property is not set.
- oPrivate: Object of the PmMap type. The properties of this object are set by the designer in the PmAction.PrivateData object. The application designer does not have to set any property in this object. If some property is set the result can be for example that a single method can be used for multiple purposes based on the value of the property in PrivateData it can be recognised where was the method called from.
oExtra.onOpen (optional) - (Object of the PmAction type) User method is defined here that is called when the panel opens (i.e. when the panel is being displayed and all graphic objects are constructed).

The object for this property is created by the Pm.CreatePmAction method.

This user method must have two parameters:

- oSystem: Object of the PmMap type. The properties of this object are set by system based on the source of calling. In such case the system sets the following properties:
- oSystem.Arguments: (Variant) Input value of the viewer that can be defined in the oExtra.Arguments entry while opening by the OpenView method.
- oSystem.ViewObject: (Object) The PmForm object that is being viewed. When other objects are being viewed, this property is not set..
- oPrivate: Object of the PmMap type. The properties of this object are set by the designer in the PmAction.PrivateData object. The application designer does not have to set any property in this object. If some property is set the result can be for example that a single method can be used for multiple purposes based on the value of the property in PrivateData it can be recognised where was the method called from.
oExtra.onChange (optional) - (Object of the PmAction type) User method is defined here that is called when some item is changed in the viewed object.

The object for this property is created by the Pm.CreatePmAction method.

This is functional only if the viewed object is PmForm.

This user method must have two parameters:

- oSystem: Object of the PmMap type. The properties of this object are set by system based on the source of calling. In such case the system sets the following properties:
- oSystem.ViewObject: (Object) The PmForm object that is being viewed.
- oSystem.ItemId: (String) Item type (this is entered when the item is created by the PmForm.CreateItem method).
- oSystem.ChangeType: (String) Modification type identifier:
- "value": Some item value has been changed.
- "push": Some item has been pressed. Functional only for PmFormItemButton item type.
- oSystem.NewValue: (Variant) Item value after change. This property is set only if ChangeType="value".
- oSystem.OldValue: (Variant) Item value before change. This property is set only if ChangeType="value".
- oPrivate: Object of the PmMap type. The properties of this object are set by the designer in the PmAction.PrivateData object. The application designer does not have to set any property in this object. If some property is set the result can be for example that a single method can be used for multiple purposes based on the value of the property in PrivateData it can be recognised where was the method called from.
© MICROSYS, spol. s r. o.Tavičská 845/21 703 00 Ostrava-Vítkovice