doc/UIHandler/UG/2_19817_CNL113512.adoc

---
Author: Zoltán Zsichla
Version: 2/198 17-CNL 113 512, Rev. J
Date: 2016-12-05

---
= EPTF CLL UIHandler, User Guide
:author: Zoltán Zsichla
:revnumber: 2/198 17-CNL 113 512, Rev. J
:revdate: 2016-12-05
:toc:

== About This Document

=== How to Read This Document

This is the User Guide for the UIHandler of the Ericsson Performance Test Framework (TitanSim), Core Library (CLL). EPTF CLL is developed for the TTCN-3 <<_1, [1]>> Toolset with TITAN <<_2, [2]>>. This document should be read together with the Function Description of the UIHandler feature <<_6, [6]>>. For more information on the EPTF CLL please consult the Product Revision Information, the User’s Guide <<_4, [4]>> and the Function Specification <<_3, [3]>> of the TitanSim.

=== System Requirements

In order to use the UIHandler feature the system requirements listed in EPTF CLL User Guide <<_4, [4]>> should be fulfilled.

The minimum required web browser version for using the Browser GUI is Mozilla Firefox 38.5.2 Extended Support Release (module name in AFS: firefox/38.5.2esr).

== Description of Required External Features outside CLL

[width="100%",cols="34%,33%,33%",options="header",]
|=======================================================================================================================================================================================================================================
|*Product Number* |*Product Name* |*Product Description*
|1/CAX 105 6334 |RapidXml 1.13 |RapidXml is required by the current web based GUI component. It is used to generate web pages based on templates/descriptions stored in XML files
|33/CAX 105 3414 R1A |jQuery 2.2.3 |It provides a rich function set including, but not limited to HTML document traversal and manipulation, event handling, animation, and AJAX calls. Other 3rd parties depend on this library as well.
|2/CAX 105 6945 |Flot 0.8.3 |Flot is used by the BrowserGUI feature to display charts (e.g.: CPS charts). It replaces a similar 3rd party component that was removed from TitanSim due to licensing problems.
|1/CAX 105 8146 |Html2Canvas 0.4.1 |Html2Canvas is used to convert any html element to canvas, which then can be saved as an image file. It is used by the BrowserGUI feature.
|=======================================================================================================================================================================================================================================

= UIHandler

== Overview

Users of TitanSim may want to interactively display their data on a user interface or they want to control the behaviour of their tests through such interface. The UIHandler feature provides support for this.

The `EPTF_CLL_UIHandlerClient_CT` component may have EPTF Variables and it can connect these variables to widgets on a runtime GUI connected to an UIHandler. When the variable changes, the content of the connected widget will be changed automatically. When the user changes the content of a connected widget, its new value will be automatically forwarded to the associated variable.

The `EPTF_CLL_UIHandler_VariableUI_CT` can be used just like `EPTF_CLL_UIHandlerClient_CT`, but it provides some functions that can be used to handle masses of variable – widget subscriptions.

It also provides functions to change the layout of the GUI.

Usage in steps:

* Create an UIHandler component, and map the necessary ports.
* Initialize the UIHandler component.
* Create your component that extends `EPTF_CLL_UIProviderClient_CT` and implicitly the `EPTF_Var_CT`. Initialize the UIHandlerClient component.
* Create and/or modify the runtime GUI configuration where you want to display your data.
* Create your variables.
* Order the UIHandler via functions of the UIHandlerClient to subscribe to your variables, and connect these variables to widgets. If you want to connect your variables to more than one widget, you can do it.
* Run your test logic.

The feature can operate in either as a client and a server too, to make connection with the Runtime GUI. The UIhandler, if used with headless mode activated, is capable of seamlessly continue operation even if the connection to the runtime GUI is lost. Alternately you can use a web browser to view the GUI. For more details see <<_3, [3]>>.

== Compilation Dependencies

The EPTF CLL UIHandler API includes the following files:

* UIHandler
** __EPTF_CLL_UIHandlerCLI_CommandDefinitions.ttcn__ +
Contains the CLI command patterns.
** __EPTF_CLL_UIHandlerCLI_Definitions.ttcn__ +
Type definitions for the CLI feature of the UIHandler.
** __EPTF_CLL_UIHandlerCLI_Functions.ttcn__ +
Function definitions for the CLL feature of the UIHandler.
** __EPTF_CLL_UIHandlerClient_Definitions.ttcn__ +
Definitions for client layer of the UIHandler.
** __EPTF_CLL_UIHandlerClient_Functions.ttcn__ +
Private and public function definitions for client layer of the UIHandler.
** __EPTF_CLL_UIHandlerVariableUI_Definitions.ttcn__ +
Definitions for the VariableUI.
** __EPTF_CLL_UIHandlerVariableUI_Functions.ttcn__ +
Function definitions for the VariableUI.
** __EPTF_CLL_UIHandlerBrowser_Functions.ttcn__ +
These functions realizes the web browser GUI functionalities.
** __EPTF_CLL_UIHandler_CLIClientDefinitions.ttcn__ +
Definitions for client layer of the UIHandlerCLI.
** __EPTF_CLL_UIHandler_ConvertFunctions.ttcn__ +
These functions are used in data display converting data.
** __EPTF_CLL_UIHandler_Definitions.ttcn__ +
Type definitions for the `EPTF_CLL_UIHandler_CT` component.
** __EPTF_CLL_UIHandler_MsgDefinitions.ttcn__ +
Message structures and data types.
** __EPTF_CLL_UIHandler_PrivateFunctions.ttcn__ +
Internally used functions of `EPTF_CLL_UIHandler_CT` component.
** __EPTF_CLL_UIHandler_WidgetFunctions.ttcn__ +
Functions of the `EPTF_CLL_UIHandler_CT` component to manipulate runtime GUI.
** __EPTF_CLL_UIHandler_XSD_XTDPTemplateDefinitions.ttcn__ +
Message types and data structures used in the communication with the runtime GUI using XSD.
** __EPTF_CLL_UIHandler_XTDPTemplateDefinitions.ttcn__ +
Message types and data structures used in the communication with the runtime GUI using XTDP Test Port.

[[usage_dependencies]]
== Usage Dependencies

The UIHandler feature is part of the EPTF Core Library (CLL). It relies on several features of the CLL. To use the UIHandler the user has to obtain the respective files from the following features:

* Base
* Common
* FreeBusyQueue
* HashMap
* Logging
* Semaphore
* Transport
* Variable

UIHandler also requires files from TestPorts, ProtocolModules

* XTDPasp_CNL113494
* Common_Components/Abstract_Socket_CNL113384
* Common_Components/Socket_API_CNL113686
* XTDP_CNL113663
* XSDASN_CNL113474
* TELNETasp_CNL113320
* IPL4asp_CNL113531
* TCCUsefulFunctions_CNL113472

= Workflow

== Installation

Since `EPTF_CLL_UIHandler` is used as a part of the TTCN-3 test environment this requires TTCN-3 Test Executor to be installed before any operation of these functions. For more details on the installation of TTCN-3 Test Executor see the relevant section of <<_2, [2]>>.

If not otherwise noted in the respective sections, the following are needed to use `EPTF_CLL_UIHandler`:

* Copy the files listed in Section <<usage_dependencies, Usage Dependencies>> to the directory of the test suite or create symbolic links to them.
* Import the UIHandler demo or write your own application using UIHandler
* Create _Makefile_ or modify the existing one. For more details see the relevant section of <<_2, [2]>>.
* Edit the configuration file according to your needs, see section <<configuration, Configuration>>].

[[configuration]]
== Configuration

The executable test program behavior is determined via the run-time configuration file. This is a simple text file, which contains various sections. The usual suffix of configuration files is _.cfg_. For further information on the configuration file see <<_2, [2]>>.

This UIHandler feature defines TTCN-3 module parameters as defined in <<_2, [2]>>, clause 4. Actual values of these parameters – when no default value or a different from the default actual value wished to be used – shall be given in the `[MODULE_PARAMETERS]` section of the configuration file.

This UIHandler feature defines the following module parameters:

* `tsp_EPTF_GUI_Main_Window_WidgetId`
* `tsp_EPTF_GUI_Main_Window_Width`
* `tsp_EPTF_GUI_Main_Window_Height`
* `tsp_EPTF_GUI_Main_Window_Title`
* `tsp_EPTF_GUI_Main_Toolbar_WidgetId`
* `tsp_EPTF_GUI_Main_Tabbox_WidgetId`

These are the main Window and Tabbox parameters and the default toolbar’s ID, all optional.

* `tsp_xtdp_listen_addr:="127.0.0.1"`
* `tsp_xtdp_listen_port := 11420;`
+
The component will connect to the runtime GUI listening on `tsp_xtdp_listen_addr` address and `tsp_xtdp_listen_port` port.

* `tsp_EPTF_savedGUIPrefix := "GUI"`
+
The `f_EPTF_UIHandler_saveLayout` function saves the layout to a configuration file with the given prefix. The name of the file consists of the value of this module parameter, plus the date, month, year, hours and minute.

* `tsp_EPTF_GUI_DefaultWindow :=""`
+
See <<module_parameter, Module Parameter>>.

* `tsp_EPTF_UIHandler_headlessmode := true`
+
Switch it to `_true_` if you want the UIHandler to be able to operate in headless mode.

* `tsp_EPTF_UIHandler_udp_port := 3333;`
+
When UIHandler is in client mode, and headless mode is on, it tries to reconnect to the server GUI. In order to do this, it first pings the GUI at the specified port. Only after receiving proper answers to these pings it attempts to reopen the lost XTDP connection.

* `tsp_EPTF_UIHandler_servermode := false;`
+
Starts the UIHandler in XTDP-server mode if `_true_`, so it waits for a GUI to connect.

* `tsp_EPTF_UIHandler_Authmsg := "Enter password";`
* `tsp_EPTF_UIHandler_Authresp := "";`
+
When these parameters are specified as non-empty strings, the GUI needs to authenticate itself. UIHandler will send the first message to GUI that waits for an input from the user. In case the "password" from the user is the same as the second module parameter’s value, then the connection is established. Otherwise the UIHandler closes the communication connection.

* `tsp_EPTF_UIHandler_authMaxTimer := 1.0;`
+
This module parameter defines the maximal time of the authentication. If the password is not received during this time, the XTDP session is closed by the UIHandler.

* `tsp_EPTF_UIHandler_handshakeMaxTimer := 1.0`
* `tsp_EPTF_UIHandler_byeMaxTimer := 1.0`
+
Timers used for the XTDP protocol.

* `tsp_EPTF_UIHandler_maxWaitTimer := 5.0`
+
Max wait time for responses.

* `tsp_EPTF_UIHandler_maxGUIWaitTime := 30.0`
+
The max wait time in the init function of the UIhandler to wait until Runtime GUI is connected.

* `tsp_EPTF_UIHandler_bufferedXTDP := 0.5;`
+
By default, UIHandler sends XTDP Request messages in a buffered way, with 0.5 second timeouts. This timeout can be configured with this module parameter. The value `_0.0_` disables this feature.

* `ts_CLI_refreshRate := 5.0;`
+
The refreshing time of the CLI.

* `tsp_EPTF_UIHandler_CLIPrefix := ""`
+
Common prefix for the UIHandler Command-Line Interface commands

* `tsp_EPTF_UIHandlerClient_maxKillTime:= 30.0;`
+
This tsp defines in seconds how long shall wait the `UIHandler_Client` component for every pending message to arrive during the cleanup. After this timeout the component exists even if not all pending messages arrived.
+
NOTE: The XTDP test port must be configured to use connection ASPs in the test-port parameters section in order to be able to use the UIHandler functionality.

* `tsp_debug_EPTF_UIHandlerClient_Functions := false`
* `tsp_debug_EPTF_UIHandler_VariableUI := false`
* `tsp_debug_EPTF_UIHandler_CLI_Functions := false`
* `tsp_debug_EPTF_UIHandler_Functions := false`
+
Enables debug printouts in UIHandlerClient,VariableUI,CLI,UIHandler.

* `tsp_schemaLocation := "XTDP-Message.xsd"`
+
Location of the schema.

* `tsp_EPTF_runtimeGuiExitButtonWidgetId := "EPTF_exit_ttcn_button"`
+
The widget ID of the exit button.

* `tsp_EPTF_UIHandler_enableBrowserGUI := true`
+
Enables the BrowserGUI feature.

* `tsp_EPTF_UIHandler_Browser_RemoteAddress := ``127.0.0.1''`
+
The BrowserGUI feature will listen on this adress.

* `tsp_EPTF_UIHandler_Browser_RemotePort := 4000`
+
The BrowserGUI feature will listen on this port.

* `tsp_EPTF_UIHandler_Browser_xsl2send := "EPTF_LoadMain.xsl"`
+
This xsl file will be used for the main page.

* `tsp_EPTF_UIHandler_Browser_xsl4Tabpage := "EPTF_LoadTabpage.xsl"`
+
This xsl file will be used for the pages when changing between different tabpages.

* `tsp_EPTF_UIHandler_Browser_favicon2send := "favicon.ico"`
+
This file will be used as favicon icon.

* `tsp_EPTF_UIHandler_Browser_welcomeScreen := "welcome.html"`
+
This file will be used as welcome screen, displayed when nothing is on screen.

* `tsp_EPTF_UIHandler_Browser_directory := "../BrowserGUI/"`
+
Location of the BrowserGUI files : _.png_, _.js_, _.jpg_, _.xsl_

== Screen Layout Design

=== Static Design

==== XUL File

The runtime GUI can be initialized with a static XUL file. The initialization XUL files can be set by a command line parameter when the runtime GUI starts.

The XUL files can be edited by text editors.

[[module_parameter]]
==== Module Parameter

The `tsp_EPTF_GUI_DefaultWindow` module parameter can describe an initial GUI layout. If this module parameter was set, the UIHandler component clears the actual runtime GUI layout and creates a new one within the `f_EPTF_UIHandler_init_CT` function described by the module parameter.

The structure of this module parameter is the same as the structure of a XUL file except that the XML header is missing, and the quotation marks (""), the escape characters (\) and the new line characters must be preceded by an escape character.

The `f_EPTF_UIHandler_snapshot` function returns the content of the current runtime GUI, and the `f_EPTF_UIHandler_saveLayout`(`f_EPTF_UIHandler_snapshot`()) creates a configuration file containing the runtime GUI layout.

==== Initialization Parameter

If the `pl_windowLayout` parameter of the `f_EPTF_UIHandler_init_CT` function is present, then it can describe an initial runtime GUI layout. The syntax is the same as the syntax of the `tsp_EPTF_GUI_DefaultWindow` module parameter.

=== Dynamic Design

The UIHandler component provides functions to add widgets to the runtime GUI, remove widgets, or clear the GUI. UIHandlerClient component provides functions to add widgets to the runtime GUI, remove widgets too.

== Runtime Test Configuration Design (deployment)

Any component in the runtime configuration can extend the `EPTF_UIHandler_CT`, the `EPTF_UIHandlerClient_CT` or the `EPTF_UIHandler_CLI_CT` components. Even a single component can extend all the three component types at the same time.

= DataSource Elements

The UIHandler can be used as DataSource Client. It has a data element, which can be connected to a button widget on the GUI. The application used data elements can be saved to a file via pressing this button.

There is another data source that can be used to display progress information during startup. The value of this dataSource should be changed to write new progress information into this variable. All changes of this dataSource are appended to each other into the progressBarHistory dataSource. The value of the progressBar dataElement can be changed from the UIHandler component by the `f_EPTF_UIHandler_updateProgress` API function call. From other PTCs, the dataSource should be requested from the DataSourceClient feature and the returned variable can be adjusted to change the progress information.

To display progress information during custom GUI creation, a simple XML containing the UIHandler progressBar or progressBarHistory dataSources should be loaded before the large custom XML. Also the progressBar dataSource can be added to the custom XML also, which makes it possible to see the progress information after the custom XML is loaded.

For more information on dataSources in UIhandler see the natural documentation and the next chapter.

= Simulation Mode

There is a extended functionality in UIHandler, it can be started in simulation mode with a silmulation database file. The main purpose of the simulation mode is to be able to see the custom gui layout without knowing the data behind it. If the data is not available at all (not as dataelement, neither in presaved database), random data will show in the GUI to simulate its layout.

There are several behaviors, depending on the initial parameters:

[source]
----
public function f_EPTF_UIHandler_init_CT(
    in charstring pl_selfName,
    in boolean pl_connectGUI := true,
    in template charstring pl_windowLayout := "",
    in EPTF_CLI_CT pl_CLI_compRef := null,
    in charstring pl_prefix := tsp_EPTF_UIHandler_CLIPrefix,
    in boolean pl_simulationMode := false,
    in charstring pl_simulation_buildDB_file := "")
----

For this functionality the last 2 parameters are important.

1.  If the `pl_simulationMode` is false, and the `pl_simulation_buildDB_file` is empty string, the UIHandler works the usual way.
2.  If the `pl_simulationMode` is false and the `pl_simulation_buildDB_file` is given, that means the user can use a button to save the used dataelements to the given file. This file is can be used as database file in simulation mode. Only use this mode, if you want to save the database to file, otherwise building the database has performance cost.
3.  If the `pl_simulationMode` is true and the `pl_simulation_buildDB_file` is given, that means that the UIhandler will show the GUI layout with all dataelement. If the dataelement can not be handled by DataSource server, the UIhandler will use the given database. If the database does not contain it either, the UIHandler will use random data.

= Examples

The "demo" directory of the deliverable contains the following examples:

* _cfg.cfg_
* __UI_Handler_Test.ttcn__

== Configuration File

The used configuration file (_cfg.cfg_) is for the UIHandler example is placed in the demo directory.

== Demo Module

In this section we will look at the `tc_Messages` testcase in the demo directory.

The task is simply making two textboxes, that one is writeable, and the second updates itself automatically to the the data of the first. This is done by two variables and two subscribing methods.

After installing and setting up the dependencies, we need to design the layout as described in the previous section. It is done by a simple TTCN code, what sends the widgets (XTDP templates) directly to GUI.

[source]
----
var EPTF_UIHandlerClient_SubsRet ret := f_EPTF_UIHandlerClient_addElementToGUI(c_MainHBox, tsp_EPTF_GUI_Main_Window_WidgetId);
  ret := f_EPTF_UIHandlerClient_addElementToGUI(c_MainTabBox, tsp_EPTF_GUI_Main_Window_WidgetId);
ret := f_EPTF_UIHandlerClient_addElementToGUI(c_MainWidgets, "bubuTab");
f_EPTF_UIHandlerClient_removeElementFromGUI("EPTF_snapshot_button");
f_EPTF_UIHandlerClient_enableGUIElement(c_EPTF_runtimeGuiExitButtonWidgetId);
var XTDP_XML_Tag vl_xul;
vl_xul :={
    xtdp_textbox := {
      disabled := false,
      flex := omit,
      id := "bubuTextBox",
      multiline := false,
      readonly := false,
      rows := 1.0,
      textvalue := "bubu",
      widgetType := "console",
      wrap := false
    }
  };
ret := f_EPTF_UIHandlerClient_addElementToGUI(vl_xul, "EPTF_Main_hbox_Textboxes");
vl_xul.xtdp_textbox.id := "tb2";
vl_xul.xtdp_textbox.textvalue := "tb2";
ret := f_EPTF_UIHandlerClient_addElementToGUI(vl_xul, "EPTF_Main_hbox_Textboxes");
----

We will be using the UIHandlerClient component as the type of our MTC and create a PTC with type UIHandler. This component will be the subscriber to the variables. Creating them and make a subscription is done by the following code:

[source]
----
f_EPTF_Var_newInt("intVarProv",10, vl_intVarIdx);
f_EPTF_Var_newFloat("floatVar",9.7, vl_floatVarIdx);
f_EPTF_UIHandlerClient_subscribeMe("intVarProv", "intVar_Subscriber","bubuTextBox");
f_EPTF_UIHandlerClient_subscribeMe("intVarProv","","tb2");
----
we may deploy two load measuring components:
[source]
----
var EPTF_HostAdminUI_CT ct_hostadmin := EPTF_HostAdminUI_CT.create;
ct_hostadmin.start(f_EPTF_HostAdminUI_behavior("LocalHostAdmin","Localhost",ct_subscriber));

var EPTF_HostAdminUI_CT ct_hostadmin2 := EPTF_HostAdminUI_CT.create(-,”192.168.0.2”);
ct_hostadmin2.start(f_EPTF_HostAdminUI_behavior("HostAdmin2","Host2",ct_subscriber));
----

After that, we only need to implement a main loop and the behaviors that describe the actions to our events. Only one exists in this case, the pressing of the Exit button.

NOTE: The widgets that can be manipulated, or can control execution like buttons, should be connected to a variable, and only the variable’s changes should be handled, not the widget’s. In case it is not connected, but used as a controlling action, the shadowed GUIs won’t be updated, and actions from them may affect the execution.

The whole source code can be found in the `tc_Messages` testcase of the demo ttcn file.

= Terminology

*Core Library (CLL):* +
It is that part of the TitanSim software that is totally project independent. (i.e., which is not protocol-, or application-dependent). The Core Library is to be supplied and supported by the TCC organization. Any Core Library development is to be funded centrally by Ericsson.

= Abbreviations

CLI:: Command Line Interface

CLL:: Core Library

EPTF:: Ericsson Performance Test Framework

TitanSim:: New synonym for the EPTF framework

TTCN-3:: Testing and Test Control Notation version 3 <<_1, [1]>>

= References

[[_1]]
[1] ETSI ES 201 873-1 v3.2.1 (2007-02) +
The Testing and Test Control Notation version 3. http://www.etsi.org/deliver/etsi_es/201800_201899/20187301/03.02.01_60/es_20187301v030201p.pdf[Part 1: Core Language]

[[_2]]
[2] User Guide for the TITAN TTCN-3 Test Executor

[[_3]]
[3] EPTF Core Library for TTCN-3 toolset with TITAN, Function Specification

[[_4]]
[4] EPTF Core Library for TTCN-3 toolset with TITAN, User Guide

[[_5]]
[5] EPTF CLL UIHandler, Function Description

[[_6]]
[6] EPTF CLL for TTCN-3 toolset with TITAN +
http://ttcn.ericsson.se/TCC_Releases/Libraries/EPTF_Core_Library_CNL113512/doc/apidoc/html/index.html[Reference Guide]

[[_7]]
[7] Runtime GUI for TTCN-3 Toolset with TITAN, User's Guide