Opening the viewer

Some Pma objects have viewer of the corresponding content. This chapter describes the viewer opening procedures in the running application (in runtime).
The instructions mentioned here are relevant for the OpenView method that is considered obsolete (but still functional) so now it is better to use the Pm.CreateView method for opening viewers.

Objects that have a viewer of coresponding content:

- PmaPanel: panel viewer

- PmaReport: viewer of dynamically generated HTML report

- PmaWorkspace: workspace viewer

- PmaAlarmGroup: viewer of the alarm states and history

- PmaEventGroup: event history viewer

- PmaWeb: viewing Web pages provided by this object

- PmaWebDir: viewing Web pages provided by this object

- PmaWebFolder: viewing Web pages provided by this object

- PmaWebLang: viewing Web pages provided by this object

Global components that contain the viewer of their own content:

- viewer of the PmForm object (path: "/#glob/form")

- Web pages browser (path: "/#glob/webbrowser")

- viewer for INFO system (path: "/#glob/infosystem")

The possible ways of opening the object viewer:

1) Static configuration:

a) in the PmaWorkspace object (see the "Viewer of component" configurator and the "Params default value" configurator). This way, it is possible to open any viewers automatically after the application is launched in specific frames of the PmaWorkspace object.

b) in the PmgFrame object (see the "Viewer" configurator). This way, it can be opened any viewer in the PmgFrame object while being opened.

2) Dynamically in the script by methods OpenView:
The set of these methods allows to open any viewer in the frame of the PmaWorkspace object, in the PmgFrame object, or as a separate window. Method is very handy and therefore it has been implemented into multiple objects:

- PmaWorkspace.OpenView

- PmaPanel.OpenView

- PmgFrame.OpenView

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

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

- sObjectPath

- sOptions

- sParams

- oExtra

sObjectPath

(String) Path (relative or absolute) to the object or component whose viewer will be opened.

The path to the objects is allowed: PmaPanel, PmaReport, PmaAlarmGroup, PmaWorkspace, PmaWeb, PmaWebFolder, PmaWebDir, PmaWebInfo, PmaWebLang.

The PmaAlarmGroup object: This object provides two viewers (state a history), therefore it is possible to add to sObjectPath, following the object path, a text /#state for alarm state viewer or a text /#history for history viewer.
If the viewer type is not defined, then the alarms are opened in alarm state viewer, and the events are opened in event history viewer.

or a path to global components can be used here:

"/#glob/form": Open a form PmForm that can be used in order to create objects dynamically (i.e. by script). These objects can then be used for data displaying or data input. In this case the value oExtra.ViewObject must be set to existing PmForm object. See Example: Creates items for entering data in the PmgForm object.

"/#glob/webbrowser": General Web browser of HTML pages (on the Web or on the disk).
In the running application, a Web browser using InternetExplorer core is opened.
See The 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 transferred to the viewer. These define where and how to open the viewer.
Entries are in the KeyVal format, for example "target:_blank;modal:1;".

For viewers of objects PmaPanel and PmaReport: The static default values sOptions can be set in the "PmaPanel > Panel > sFramePars default value" configurator or in the "PmaReport > Report > sFramePars default value" configurator.
In this case the static default setting of the object is combined with the entries provided dynamically.
If the same information is present on both places, then the dynamical information provided at viewer opening is preferred by the system.

target:xx; - Specifies in which frame will viewer be opened.

If not set, then the following settings are used as default:

- if the window is open as modal (is set "modal:1;"), then "_blank" is set.

- if is opened from the PmaPanel object, then "_self" is set.

- if is opened from the PmaWorkspace object, then the main frame identifier of the workspace is used (defined in the "Default frame" configurator).

- if is opened from the PmgFrame object, then the viewer displays in the PmgFrame object).

frameid - The new viewer is opened in the PmaWorkspace object in the frame with frameid identifier.

_blank - The new viewer is opened in a new window.

_blank.blankid - Identifier of the independent or modal window.
If a window with blankid identifier already exists then the new viewer opens in current window, otherwise it opens in a new window.

The meaning of the identifier:

- Prevents opening a large number of windows with the same identifier.

- It allows this window to be referenced, for example:

- the method Pm.WndOper(0, "_blank.xy", 10) closes the window with xy identifier.

This is a system name, so it must contain only alphanumeric and must not contain any diacritics (i.e. national dependent characters), spaces and first character must not be a number.

_self - The new viewer is opened in the current window (in the frame) and the viewer, over which the method was called, is closed.

scrollbar:nn; - Specifies whether the window will have the scrollbars and allows moving the contents, if the panel size is greater than window size, the panel is inside.

0 - The scrollbars will never be displayed and therefore the window content cannot be scrolled.
It is handy for example for very narrow "toolbar" type windows.

1 (default) - The window displays the scrollbars and allows to scroll the panel, if the panel size is greater than window size, the panel is inside.

refresh:xx; - Only for opening the viewer of the PmaPanel object. Specifies whether the panel has the automatic refresh according to the globally set system period or the panel has its own refresh rate. For now, it is not functional when opening Web panel.

0 - The panel will have its own refresh, i.e. the PmaPanel.Refresh method will be called.

system (default) - The panel will have the automatic refresh according to the globally set system period (see the "PmaRoot > Application > Panels timer period" configurator).

The following entries are relevant only when opening in a new window (i.e. with setting "target:_blank;"):

modal:nn; - Specifies whether the window will be modal.

0 (default) - The window will not be modal.

1 - The window will be modal.

dependent:nn; - Specifies whether the window will be dependend on the application main window.

0 - The window will be independent on the application main window.

1 (default) - The window will be dependent on the application main window and will always be on top of the application.

caption:nn; - Specifies whether the window has the window title bar or not (i.e. the blue stripe on up).

0 - The window will have no title bar. For now, it is not functional when opening Web panel.

1 (default) - The window will have the title bar.

ontop:nn; - Specifies whether the window will be "Always on top".

0 (default) - The window will not be "Always on top".

1 - The window will be "Always on top". For now, it is not functional when opening Web panel.

state:xx; - Specifies the initial state of the window.

normal (default) - The window will be displayed normally (neither maximalized nor minimalized).

max - The window will be maximalized. For now, it is not functional when opening Web panel.

pos:xx; - Specifies the initial position of the window in normal state.
This position is just recommended. If the window size does not fit into the screen, then the position is shifted so the biggest possible portion of the window is visible.

top,center (default) - The window will be displayed in the center of the active application window (of the workspace).

top,x,y - The window will have the left upper corner in coordinates x and y (in pixels) relative to the active application window (of the workspace).

frame,center - The window will be displayed in the center of the window from which the new window was opened.

view,x,y - The window will have the left upper 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 Pmg object the window was opened from. See Example for opening of the panel and placing according to the Pmg object position.

screen,x,y - The window will have the left upper corner in coordinates x and y (in pixels) in Windows absolute grid system. This option is not functional on the Web. It is used for positioning in main windows of the application (PmaWorkspace or PmaPanel) to individual displays. Other application windows are then usually positioned relatively to these main windows.

size:xx; - Specifies the initial size of the window in normal state.

content (default) - The window will be sized to fit the whole opened panel (i.e. no scrollbars are created).
Width and height of the panel is entered in the graphics editor in the PmgRoot object on the "Panel" tab.
The same function as the content value has the old (but still functional) value panel.

dx,dy - The window size will be defined by the dx and dy values (in pixels). These values define the outer window size (i.e. including the borders and window title bar).

fixed:xx,yy,..; - It allows to disable the change of state, position or panel size. It is defined as a list of prohibitions separated by "comma" (,). For now, it is not functional when opening Web panel. The default value is: Everything is enabled.

state - Disables to change the window state (normal / maximized / minimized).

pos - Disables to change the position of the window in normal state.

size - Disables to change the window size in normal state.

size2 - Disables changing window size in normal state - the window size cannot be greater than the size of corresponding panel.

sParams

(String) The data transferred to the object that is to be viewed by the corresponding viewer.
Entries are in the KeyVal format, for example "name1:value1;name2:value2;".
These data usually parametrize or filter the content of the corresponding viewed object and are depending on the opened object type.

PmaPanel: It allows to set the value of parameters of the PmgRoot object.
This parameter is then accessible in configurators of the panel by means of the Macro expression $.par and in the script by the GetPar method.
Each parameter here consists of an identifier (name) and a value.
Syntax: "pars:{name1:value1;name2:value2; ...}".
See also: Parameters of the Pmg object.
The static default values of the sParams parameters can be set in the "PmaPanel > Panel > sViewPars default value" configurator. In this case the static default setting of the object is combined with the entries provided dynamically.
If the same information is present on both places, then the dynamical information provided at viewer opening is preferred by the system.

PmaReport: It allows to set the value of the report parameters. These parameters are then accessible in the pEvent.Pars parameter of the onReportRequest event.
Each parameter consists of an identifier and a value.
Syntax: "pars:{name1:value1;name2:value2; ...}".
Static default values of the sViewPars parameters can be set in the "PmaReport > Report > sViewPars default value" configurator. In this case the static default setting of the object is combined with the entries provided dynamically. If the same information is present on both places, then the dynamical information provided at viewer opening is preferred by the system.

PmaWorkspace: Not used.

PmaWebDir: "file:xx;" = The file with the extension (e.g. file:MyPage.htm), to be displayed. This file must be placed in the folder offered to the Web by PmaWebDir object (see the "Folder with files" configurator).
If the file is located in subfolder, then the file parameter must be entered in the form of "subfolder/file".
If the file parameter is not specified, then the default.htm file will be opened and if such file does not exist, then a dynamically created HTML page with file list is opened.

"/#glob/webbrowser": It allows to set the address of the HTML page to be displayed. Syntax: "url:https://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.

PmaAlarmGroup, PmaEventGroup: It allows to set either the filtering string only or complex panel parameters of the registered alarm/event viewer (including the filtering string). See Viewing alarms/events or Filtering string.

oExtra

(Object) Additional entry for the viewer. The data are defined here by creating properties in the PmMap object (contrary 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:

JavaScriptSelect and copy to clipboard



var oExtra = Pm.CreatePmMap();

oExtra.Arguments = 3.14;

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 the oExtra.onOpen event (see further).

- in the PmaPanel object by means of the PmgRoot.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, when opening modal window in order to edit data.
The Arguments property is then used as input initialization value (the ReturnValue property as modified output 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 value is set to dynamically created and configured PmForm object. See Example: Creates items for entering data in the PmgForm object.
For other viewer types, this value is irrelevant.

oExtra.onClose (optional) - (object of the PmAction type) Designer method is defined here that is called when the panel closes.
The object for this property is created by the Pm.CreatePmAction method.
This designer method must have two parameters:

- oSystem: Object of the PmMap type. Properties of this object are set by system based on the source of calling. In this case the system sets the following properties:

- oSystem.CloseReason: (String) Window closing type identifier.

- Entered when closing the PmaPanel object by method PmgRoot.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 PmaPanel object, it is possible to set the value by means of the PmgRoot.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. Properties of this object are set by the designer in the PmAction.PrivateData object. The designer does not have to set any property in this object. If some property is set the result can be for example that a one designer method can be used for multiple purposes based on the value of the property in PrivateData it can be recognised in this method where was the method called from.

oExtra.onOpen (optional) - (object of the PmAction type) Designer method is defined here that is called when the panel opens (i.e. if the panel is being displayed and all graphic objects are constructed).
The object for this property is created by the Pm.CreatePmAction method.
This designer method must have two parameters:

- oSystem: Object of the PmMap type. Properties of this object are set by system based on the source of calling. In this case the system sets the following properties:

- oSystem.Arguments: (Variant) Input value of the viewer that can be entered in the oExtra.Arguments entry when 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.

oExtra.onChange (optional) - (object of the PmAction type) Designer method is defined here that is called if 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 designer method must have two parameters:

- oSystem: Object of the PmMap type. Properties of this object are set by system based on the source of calling. In this case the system sets the following properties:

- oSystem.ViewObject: (Object) The PmForm object that is being viewed.

- oSystem.ItemId: (String) Pmf object type (this is entered when creating the object by the PmForm.CreateItem method).

- oSystem.ChangeType: (String) Modification type identifier:

- "value": Some object value has been changed.

- "push": Some item has been pressed. It is functional only for the PmfButton object.

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

History:

Pm8.03.11: Generalization: in oExtra.onOpen entry it can be set a method that is called once the panel opening is completed.

Pm8.03.06: Highly generalized panel opening by using the OpenView methods:

- New (fourth) optional oExtra parameter added to the OpenView methods. This parameter allows to set properties for opening:

- oExtra.Arguments (object of the PmMap type): Value that is passed to the opening panel and will be available in the panel by means of the PmgRoot.Arguments property.

- oExtra.onClose (object of the PmAction type): It can be defined the designer method here that is called when this panel is being closed.

- This generalization also changes the way the modal windows are created - i.e. windows that block user access to other windows during data entry.
The OpenViewModal method is now considered obsolete - this method is "synchronous", i.e. when called the script waits until the window is closed and continues its function after that. This approach is not functional in many Web browsers and the concept itself from the script operation point of view is not correct.
New type of a modal window opening by the OpenView method (with defined entry modal:1;) opens the window modaly but the script continues to run. Once the modal window is closed, designer method is called that was defined in the oExtra.onClose entry
See How to work with modal windows.

Modal windows that are open this way are functional fully in all Web browsers.

Pm8.03.05: The size and position of the panel opened in a separate window were not evaluated correctly (i.e. if "target:_blank;").

PROMOTIC 9.0.31 SCADA system documentation MICROSYS, spol. s r.o.

Send page remark Contact responsible person

Navigation:

- PROMOTIC SCADA/HMI system

- Documentation contents

- Examples, directions and appendixes

- Configuration of the DCOM interface for ActiveX

- Configuration of the DCOM interface for OPC-DA server

- Configuration PC and Windows OS

- Keys constants

- XML and INI configuration files for $.cfgfile