blob: 3556fb35602d936e78ee8c31fcaab97b949f9926 [file] [log] [blame]
---
Author: Tamás Levente Kiss
Version: 1/1553-CNL 113 512, Rev. C
Date: 2016-12-05
---
= Guideline to use the Browser-based GUI
:author: Tamás Levente Kiss
:revnumber: 1/1553-CNL 113 512, Rev. C
:revdate: 2016-12-05
:toc:
== Knowledge Prerequisites
The solution uses XML schema transformations (<<_5, [5]>>), HTML cascading style sheets (<<_6, [6]>>), and Java scripts (<<_7, [7]>>) as the most commonly used HTML data manipulation techniques. Most of this document assumes the knowledge of these technologies. However, some parts (for examplechanging the lookup with replacing or editing files) can be used without any special knowledge.
[[system_requirements]]
== System Requirements
In order to use the BrowserGUI feature the system requirements listed in EPTF CLL User Guide <<_4, [4]>> should be fulfilled. The minimum required web browser version is Mozilla Firefox 38.5.2 Extended Support Release (module name in AFS: firefox/38.5.2esr).
= `BrowserGUI`
The TitanSim applications have multiple solutions for handling user interactions and show statistics. The command line interface and the java based `RuntimeGUI` are currently in use. To follow the new technologies, a new GUI was designed and developed. This new user interface is similar to the `RuntimeGUI` from the GUI layout point of view, which helps the users to be familiar with it in a very short time.
The browser-based GUI (`BrowserGUI`) is an HTML based feature, which uses standard technologies in order to support as many web browsers as possible (Mozilla, IE, etc.). It makes the used code understandable, if the customer is familiar with HTML, XSLT and javascript basics.
== How it works
The main concept of this feature is to define the graphical user interface in an XML file that is generated by the server. The structure of the XML file is described by the XTDP Protocol Module.
This XML file is processed by using an XSL transformation, and the layout is formed by the client side, as its shown on figure below:
image::images/Browser_GUI_behavior.PNG[Main concept of the BrowserGUI behavior]
When an HTTP client requests data from the application, it adds an `<?xml-stylesheet XML type="text/xsl" href=…>` tag to the beginning of the XML data. This XSL file transforms the XML data to an XHTML page. This is the only file required by the `BrowserGUI` feature for a successful data exchange. The file path and name can be set in module parameters (see <<tsp-eptf-uihandler-browser-remoteport, `tsp_EPTF_UIHandler_Browser_RemotePort`>>, <<tsp-eptf-uihandler-browser-xsl2send, `tsp_EPTF_UIHandler_Browser_xsl2send`>>, and <<tsp-eptf-uihandler-browser-welcomescreen, `tsp_EPTF_UIHandler_Browser_welcomeScreen`>>). If the file is unavailable for the server, it results in an error message on the client side, in the browser.
== Existing Sample Solution
The TitanSim framework provides a sample solution that can be used. This section gives a brief overview about the main client side components and files that this solution is built from.
[[eptf-loadmain-xsl]]
=== _EPTF_LoadMain.xsl_
As it was mentioned earlier, the GUI is defined in an XML file, which is sent to the client, when the user first loads the web page of the application. This XML file refers to an XSL file. That XSL file defines the transformation rules, which create the HTML code of the page. Each widget type has its equivalent HTML element type. The properties of these items mostly defined in the source XML, like size, orientation or color. These properties are used during the transformation and defined in the HTML code as well.
The XSL file defines only valid, standard HTML elements that can be processed by multiple web browsers. The XSL transformation rules can be edited by the user, in order to process a new widget type or modify an existing transformation. For applying the changes only the web page needs to be reloaded.
[[main-css]]
=== _main.css_
The generated HTML file uses this CSS file to define the style of the GUI layout. This technology makes it possible to define the visualization information separated from the XSL transformation and the javascript code.
This file defines the font types, size, color and orientation information of the elements. It is possible to create multiple CSS files for this application that gives the possibility to use different skins for the same application without changing the source code or the GUI descriptor XML.
The GUI can be visualized without this file as well, but it will contain mostly plain text, without any style information and background image and so forth. The predefined CSS file is the main.css, this file can be modified or overwrite by the user at any time, the web page needs to be reloaded in order to apply the changes. See below figure:
image::images/browserguiexecctrl_green_cut.jpeg[Execution Control tab with green CSS style]
=== Javascript Files
The above mentioned files are used for creating the basic GUI layout. This interface does not contain all the elements, defined in the XML file of the GUI and it is also not capable to communicate with the server side in case of any changes on the web page or handle interactions with it.
Some additional files are needed, which contain the javascript that handles the interactions with the application, visualizes the special elements and provides a refresh method in order to follow the statistics of the running tests in the application.
The `BrowserGUI` uses AJAX technology in order to refresh the web page in a predefined time interval and updating the server side in case of any, user indicated changes. There are elements on the GUI, like the different kind of charts that also use javascript technology.
=== External Javascript Libraries
External javascript libraries are used to support the chart generation, event handling and AJAX technology that is used for refreshing the page.
We use jquery (_jquery-2.2.3.min.js_) for supporting the user interaction with the GUI and the refresh method.
[[htmlbrowser-js]]
=== _htmlbrowser.js_
The htmlbrowser.js file contains the developed javascript itself, which uses the functions provided by the above mentioned libraries. This file can be edited or replaced by the user and the changes can be applied by reloading the webpage.
The main functionalities of the javascript are the following: refreshing the web page elements in every three seconds, handling the tab changes, sending the updates of the web page to the server.
The refresh and update methods are implemented as AJAX requests. The messages have `JSon` string format, which makes it easier to handle the content on the client side with built-in functions. The `JSon` string has a predefined format, which contains key-value pairs. In our feature the key is the Id of the refreshed or updated element and the value is the value of that element.
In order to decrease the size of the messages between the client and the server the refresh method requests the new values of only the visible form elements on the active tab of the page. It is important in case of the charts and tables, which contains great number of statistics.
This javascript file handles the chart creation mechanism as well. Every chart has a chart object with parameters that came from the server side in the GUI descriptor XML. When the chart is created for the first time, the client requests historical data from the server, if there is any. When the chart is refreshed only the new value and timestamp value is requested. When the chart is scrolled out from the screen, the chart object is destroyed and it is created again, when the chart becomes visible again.
The javascript handles the tab changes as well, when the user clicks on a tab in the horizontal or vertical menu. The script requests for the XML file only of that tab and not the whole page. When the proper XML file is received from the server, the client transforms it with the XSL transformation and visualizes it by applying the CSS rules as well.
=== Image Files
The HTML technology gives the possibility to embed images into the GUI layout for instance as background images.
The image files can be edited or replaced by the customer at any time. If you replace the files with files having the same name, nothing else has to be changed. If the new files have different names, the references have to be changed also. (Since the CSS, XSL and JS files are text files, it means a simple text replace.) To apply the changes it is enough to reload the web page.
=== Logo
Any application specific logo can be added to the GUI layout, it depends on the customer needs. It can be easily inserted by editing the XSL and the CSS files to set its place and look. The actual version of the feature uses the Ericsson and TitanSim logos (the files are the __ericsson_logo_top.png__ and __titansim_logo_animated.gif__).
=== Background Images
The images can be used as background for example for buttons, or tab menu elements. It is important to avoid the use of too many and too big pictures as their size can make the page loading mechanism slow because of the size of the files the browser downloads, when it loads the page for the first time.
The CSS file defines the position of an image in most cases, which makes it possible to store multiple background images in one file.
=== Loading Image
Loading images are used for elements that need noticeable time for loading and visualizing the data, like charts. The loading image is only visible until the chart is rendered to the screen. It can be changed by replacing the _loading.gif_ file.
=== Led
The leds are used to show status information, as for example the green led indicates that a test is in running state. These leds are inserted from png images, which can be changed by replacing the proper files (__led_green_16x16.png__, __led_red_16x16.png__, etc.).
== Customization
The `BrowserGUI` is a fully customizable feature of the TitanSim. All the files that were mentioned above can be edited or replaced by the user at any time. The technologies that were used are all based on standards in order to support multiple web browsers and make the customization process more user friendly.
The files can be changed even while the application is running. The changes appear after reloading the web page. In case of changing the module parameters, the application needs to be restarted in order to read the modified configuration files.
= Module parameters
The `BrowserGUI` feature has some parameters that can be set in the configuration files of the application by setting the values of the following module parameters:
[[tsp-eptf-uihandler-enablebrowsergui]]
* `tsp_EPTF_UIHandler_enableBrowserGUI`
+
The `BrowserGUI` feature can be turned on or off by setting this module parameter to true or false.
+
The default value of it is `_true_`.
[[tsp-eptf-uihandler-browser-remoteaddress]]
* `tsp_EPTF_UIHandler_Browser_RemoteAddress`
+
[source]
----
modulepar charstring tsp_EPTF_UIHandler_Browser_RemoteAddress := "127.0.0.1";
----
+
This parameter defines the IP address of the application, where the `BrowserGUI` is available. The default is the localhost address, but it can be changed to the IP address of the host machine, where the application is running.
[[tsp-eptf-uihandler-browser-remoteport]]
* `tsp_EPTF_UIHandler_Browser_RemotePort`
+
[source]
----
modulepar integer tsp_EPTF_UIHandler_Browser_RemotePort := 4000;
----
+
This parameter defines the port number, where the GUI is available. The default port number is 4000, but it can be changed to any valid port number as well.
[[tsp-eptf-uihandler-browser-xsl2send]]
* `tsp_EPTF_UIHandler_Browser_xsl2send`
+
[source]
----
modulepar charstring tsp_EPTF_UIHandler_Browser_xsl2send := "EPTF_LoadMain.xsl";
----
+
This parameter defines the XSL file, which contains the XSL transformation rules that need to be used, when the client visualizes the XML file of the web page that came from the server side.
[[tsp-eptf-uihandler-browser-xsl4tabpage]]
* `tsp_EPTF_UIHandler_Browser_xsl4Tabpage`
+
[source]
----
modulepar charstring tsp_EPTF_UIHandler_Browser_xsl4Tabpage := "EPTF_LoadMain.xsl";
----
+
There is a possibility to define a different XSL file for transforming the XML file of the tabpages.
[[tsp-eptf-uihandler-browser-welcomescreen]]
* `tsp_EPTF_UIHandler_Browser_welcomeScreen`
+
[source]
----
modulepar charstring tsp_EPTF_UIHandler_Browser_welcomeScreen := "welcome.html";
----
+
The `BrowserGUI` feature provides the capability for displaying a welcome screen, while the application is starting. The current welcome screen is defined in the _welcome.html_ file. This file can be edited or replaced as well in order to change the welcome screen if needed.
[[tsp-eptf-uihandler-browser-directory]]
* `tsp_EPTF_UIHandler_Browser_directory`
+
[source]
----
modulepar charstring tsp_EPTF_UIHandler_Browser_directory := "../BrowserGUI/";
----
+
The path of the files, which were mentioned in this section, has to be defined. The default is a `BrowserGUI` folder on the same level as the build folder of the application.
= New Features
The TitanSim applications have different look, but there are some common components, which is used by every of them. This section gives a brief overview about the usage of the common features of the new web-based GUI.
== Menu Hide
The layout usually has several menu items on the screen both horizontal and vertical ones. These elements can use a quite large amount from the screen in case of small display resolution or window size. The `BrowserGUI` has the capability to collapse these menus and increase the size of the useable part of the browser window. See below figures:
image:images/menushow.jpeg[menu_show]
Menu with full size
image:images/menuhide.jpeg[menu_hide]
Menu after hide
== Window Resize
The browser window is mostly resizable and the GUI layout adapts to this change. The `BrowserGUI` is configured to display a vertical scrollbar as the tables and charts of the statistics cannot fit into a browser window.
The size of the elements on the GUI is decreased, even the size of the charts as well. The GUI keeps its layout as long as it is possible.
image:images/windowfullsize.jpeg[window_full_size]
Figure Full size window
image:images/windowsmallsize.jpeg[window_small_size]
Window after resize
image:images/chartfullsize.jpeg[chart_full_size]
Chart at full window size
image:images/chartsmallsize.jpeg[chart_small_size]
Chart after resize
When the horizontal scrollbar is enabled, the GUI layout does not change and the scrollbar appears, if the window width becomes smaller, than the width of the GUI layout.
== Chart Functions
Line (for example, CPS) and bar (for example, density) chart types are supported. Following interactive features are provided:
* Zooming
* Toggle series (if there is more than one dataset in one chart, you can choose to hide certain dataset),
* Save as image (saving chart state as an image in PNG format)
== Open Tab in New Tab
The TitanSim applications mostly have difficult statistics and resource usage tabs with many values in the tables and on the charts. This results in small and unreadable tables and charts as too much information is positioned onto one page.
The BrowserGUI has the capability to open the tabs of the application in separate browser tabs by right clicking on the tab header in the menu and selecting the Open Link in New Tab option. This can make the tables and charts bigger and after this, the information in these elements is much easier to read.
This solution is the best, when hiding the menu items is not enough. The refresh method work continuously in the new browser tab as well. The difference is spectacular for instance in case of the CPS Chart tab of the Execution Control component, as it can be seen on Figure 12 and Figure 13.
image:images/cpschart_fullwindow.jpeg[CPS_chart_full_window]
Chart inside of the application window
image:images/cpschart_in_own_tab.jpeg[CPS_chart_in_own_tab]
Chart in separate browser tab
== HTML insert
The GUI descriptor xml file can be customized in several ways. The user can assemble the items of an own, individual user interface like a puzzle. The `BrowserGUI` feature provides additional puzzles parts in the form of HTML code insert.
This feature makes it possible to embed several external HTML pages or even another TitanSim application into one `BrowserGUI` window. These HTML pages can be visualized in separate tabs, like any other tabs.
The following code can be inserted into a hbox, or tabpage:
[source]
----
<htmlcode>
<value>&lt;iframe width="1100px" height="800px"
src="https://mhweb.ericsson.se/TREditWeb/faces/tredit/tredit.xhtml?create=true"&gt;&lt;/iframe&gt;</value>
</htmlcode>
----
The value tag cannot contain new line characters and the special values inside it, like < and >, has to be escaped until the next release of Titan. The result of this HTML code insert is depicted on figure below:
image:images/browserguihtml_insert_mhweb_cut.jpeg[BrowserGUI_HTML_Insert_MHWeb_cut]
MHWeb inserted into the `BrowserGUI` on a separate tab.
= BrowserGUI Setup
The initial steps to start the `BrowserGUI` feature:
. The module parameter, which enables the feature, is the `tsp_EPTF_UIHandler_enableBrowserGUI`. The default value of it is `_true_`. If the feature does not start, check the value of this parameter.
. Set module parameters
+
If the application parameters differ from the default values of the module parameters, these parameters need to be updated. The additional files can be replaced by the user or deleted as well. The XSL transformation file is required for the browser to process and visualize the web page definition and the javascript files are required for the additional features of `BrowserGUI`.
+
. Start a web browser
+
See the required web browser version in <<system_requirements, System Requirements>>
. Type the address
+
(http://browsergui_address:browsergui_port)
Make sure that the firewall settings are correct, if you try to use the feature from another machine, than the host of the application.
= Terminology
*Core Library(CLL):* +
It is that part of the TitanSim software that is totally project independent. (that is, 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
AFS:: Andrew File System
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] http://www.w3.org/TR/xml/[Extensible Markup Language (XML)] +
[[_6]]
[6] http://www.w3.org/Style/CSS/[Cascading Style Sheets] +
[[_7]]
[7] http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=55755[JavaScript] +