Customizing Hotspots in Verastream HTML5 Web Applications

  • 7021326
  • 05-Jun-2013
  • 11-Mar-2018

Environment

Verastream Host Integrator version 7.5 or higher

Situation

Beginning in Verastream Host Integrator (VHI) version 7.5, hotspots are enabled in the HTML5 web applications generated with the VHI Web Builder utility. This technical note describes advanced customization techniques for hotspots.

Hotspots are buttons that can be configured to appear over screen text in the terminal display, allowing you to provide the user with a means of mouse-clicking (or finger-tapping) on the screen to invoke some type of action. For a general overview about hotspots, see http://docs2.attachmate.com/verastream/vhi/7.5/en/topic/com.attachmate.vhi.webbuilder.help/html/reference/about_hotspots.xhtml.

Resolution

Editing Web Applications Generated by Web Builder

When Web Builder generates an application, the results are copied to two locations on your computer:

  • <my documents> location:
<my documents>\Attachmate\Verastream\HostIntegrator\projects
  • "deployed" location:
<install location>\Attachmate\Verastream\HostIntegrator\servletengine\webapps

Do not make edits to files found under the “deployed†location on your Development Kit system. Instead, make all needed changes to applications generated by Web Builder using the version saved to the <my documents> location. This will ensure that all customizations will become part of the .war file for the application that Web Builder creates.

After saving changes to files in the web application, use Web Builder to rebuild and redeploy the web application.

Examining the hotspot.configurations File

HTML5 web applications generated by Web Builder define hotspots in a text file called hotspot.configurations found at this location:

<my documents>\Attachmate\Verastream\HostIntegrator\projects\<your app name>\webapp\<your app name>\WEB-INF\classes\hotspot.configurations

The file contains a list of hotspot configurations.

  • Each hotspot configuration consists of a single line of parameters separated by commas, in the following order:
"regex", "script", "tooltip", "attributes", matchCase, wholeWord, column, row, quantity
  • To add a new hotspot configuration, add a new line to this list, with parameters as shown in the following section.
  • To remove a configuration, insert a # (hash) at the beginning of the line, which will render it a “comment†in the list.

Parameters Used in the hotspot.configurations File

The following parameters are used in hotspot.configurations.

Note: The first four parameters are quoted text strings; if you need to include a " (quote) character within these parameters, the quote must be escaped with a \ (backslash) character.

"regex"

The text to match; must be a valid regular expression string. (For more information about regular expressions, see http://docs2.attachmate.com/verastream/vhi/7.5sp1/en/topic/com.attachmate.vhi.help/html/reference/reg_expressions.xhtml.)

"script"

JavaScript to run when the hotspot is invoked; must be a valid JavaScript expression. The default set of hotspot configurations all call a VHI-defined function to send an AID key to the host system, but any custom JavaScript could be used. See Options for JavaScript Invoked by Hotspots for more details.

"tooltip"

The hotspot mouseover tooltip; any string. Not particularly useful in mobile or tablet browsers.

"attributes"

A hotspot is rendered as an HTML anchor element ( <a> ). The attributes for a hotspot configuration are the HTML attributes to be associated with the hotspot <a> element. The example seen in all the default hotspot configurations indicate that a Cascading Style Sheets (CSS) class named “ak_hotspot†should be associated the hotspot. This class is defined in a file located at <my documents>\Attachmate\Verastream\HostIntegrator\projects\<your app name>\webapp\<your app name>\themes\MobileUX.

matchCase

The regular expression must match case, true or false.

wholeWord

The regular expression must match a whole word, true or false.

column

Column position at which the regular expression must be found: 0=any column, >0=specific column

row

Row position at which the regular expression must be found: 0=any row, >0=specific row

quantity

How many times should the regular expression be matched for hotspots on the current screen? 0=show first match only, 1=show last match only, 2=show all matches

Options for JavaScript Invoked by Hotspots

There are three ways to include JavaScript for hotspots:

  • For simple tasks, you can place JavaScript directly in the hotspot.configurations file, as part of the “script†parameter for a hotspot configuration. Separate multiple statements with a semicolon.
  • To add a larger amount of custom JavaScript, you could add it directly to one of the existing JavaScript files that are part of the generated web application, for example, at the bottom of <my documents>\Attachmate\Verastream\HostIntegrator\projects\<your app name>\webapp\<your app name>\scripts\mobileux.js
  • Or, to add a lot of new JavaScript code to the project, you might want to include your own custom .js file. To do this:
    1. Add your .js file to
<my documents>\Attachmate\Verastream\HostIntegrator\projects\<your app name>\webapp\<your app name>\scripts\
    1. Have the project recognize your new file by adding
<script type="text/javascript" src="scripts/MyNewCode.js"></script>

to the <head> section in

<my documents>\Attachmate\Verastream\HostIntegrator\projects\<your app name>\webapp\<your app name>\main.jsp

Using the Hotspot Text Value with JavaScript

It is possible to capture the text that has been matched by the hotspot configuration’s regular expression, and use it in JavaScript. Being able to get this hotspot text in JavaScript makes hotspots especially useful. For example, if your hotspot regular expression is intended to match an account number, you might want to use that account number as part of the URL query string when opening a new browser window using JavaScript.

To store the current hotspot text in a JavaScript variable, use this syntax within the hotspot configuration "script" parameter:

var theText = document.getElementById(id).innerHTML;

The “id†variable corresponds to the “id†attribute for the hotspot’s <a> element. Before using the JavaScript from the hotspot.configurations, the web application prepends a statement defining this id variable. To illustrate, use the Chrome browser to view the host screen with the web application where hotspots are visible; right-click one of the hotspots, and select “Inspect element.â€

Here is an example of a hotspot configuration that is set to do a Google search on the text matched by the hotspot regular expression:

"myRegEx", "var theText = document.getElementById(id).innerHTML; window.open(\"http://www.google.com/search?q=\" + theText); ", "Google search on this hotspot!", "class=ak_hotspot", false, false, 0, 0, 2

Note the following:

  • Hotspots cannot span from one row to the next; they must be contained all on a single line.
  • Hotspots cannot include input fields.
  • Hotspot areas cannot overlap.
  • Each hotspot.configurations file applies to the current web application only; they are not shared among web applications generated by Web Builder.

Additional Information

Legacy KB ID

This document was originally published as Attachmate Technical Note 10146.