PREV NEXT

Generic Logic, Inc. www.genlogic.com


5 Using the JavaScript Version of the Toolkit

Introduction

The JavaScript version of the GLG Toolkit provides an HTML5 JavaScript library that is used to deploy a GLG application on a web page in a browser. The library provides the same complete GLG API as the GLG C/C++, Java and C# libraries used to develop desktop applications. With the JavaScript API, these applications can be ported to HTML5 and deployed in a web browser with the client-side JavaScript.

The supported browser include Firefox, Chrome, Safari and Microsoft Edge, including both the desktop and mobile versions.

Standard, Intermediate and Extended APIs

The JavaScript API provides three levels of a programming interface:

JavaScript Library

The GLG JavaScript Library is a JavaScript object engine that renders GLG objects in the Web environment via HTML5 and JavaScript. The Toolkit takes care of the low-level details of the rendering process, such as optimized damage repair, screen-resolution independent coordinate conversion, transparent zooming and panning, double-buffering and other coding-intensive driver-level tasks.

The Toolkit provides a high-level graphical object model which allows an application developer to concentrate on the application logic, speeding up the development process and dramatically increasing the developer's productivity.

The Toolkit contains the Graphics Builder, a graphical editor used to create graphical objects and define their attributes and dynamic properties without tedious programming. The resulting drawing is then saved into a file and loaded into a web application on a web page using a provided GLG JavaScript library.

JavaScript API

Overview

The GLG JavaScript API methods mimic the corresponding methods of Java and C# GLG APIs described in the previous chapter, with minor differences related to the JavaScript syntax. This allows to share not only the drawings but also the programming logic between the desktop and Web versions of an application.

The GLG JavaScript Online Documentation contains descriptions of all JavaScript API methods. It may be found on the GLG web site at the following location:

http://www.genlogic.com/doc_html/start.html#JavaScriptDoc

Even though the JavaScript is a dynamically typed language, this documentation uses "class" and "type" terms to describe GLG methods and their parameters. The GlgObject "class" is an object that provides methods that can be applied to an instance of GlgObject of any type, such as a polygon or a viewport.

The majority of the GLG methods are listed in the GlgObject section of the documentation.

A few utility "classes", such as GlgPoint, GlgCube, GlgTraceData, etc., are used to pass data to and from the GLG object engine.

There are also several helper classes, such as GlgInputListener, GlgTraceListener, etc., that define type signature of various callback functions.

Using JavaScript API Methods

The vast majority of the JavaScript API methods are the same as the corresponding Java or C# methods of the GLG API. The only exception are the methods that initialize the GLG API and load the GLG drawing. The JavaScript demos and examples provide source code examples of using these methods.

The JavaScript API methods use the same arguments as their corresponding Java or C# equivalents. For example, the SetDResource( resource_name, value ) method expects a string as the first parameter and a double value as the second parameter.

For methods that expect integer parameters, such as GetElement( element_index ), it is an error to pass a numerical value that is not an integer, such as 3.5. Such errors will be detected if a debugging version of the library (described on page 382) is used during development. If a production version of the GLG library is used, the error may be undetected and cause errors later in the program.

Static methods are invoked on a GLG handle obtained via a call to the GlgToolkit method at the beginning of the program:

// Get a handle to the GLG Toolkit library.
var GLG = new GlgToolkit();

// Load GLG drawing.
GLG.LoadWidgetFromURL( "process.g", null, LoadCB, null );

Instance methods are invoked on the object instance:

viewport.SetGResource( "FillColor", 0.7, 0.7, 0.7 );

Comparing GLG Objects

Some methods, such as GetResourceObject, return an instance of GlgObject. The returned object is actually a wrapper around the internal representation of the object used by the GLG object engine. As a result, two different wrapper instances may actually refer to the same internal GlgObject.

To avoid incorrect results, the Equals instance method should be used instead of the == operator in the JavaScript code to check if two GLG objects are the same:

var same = obj1.Equals( obj2 );

A static ObjectsEqual method can also be used to compare two objects, in case obj1 may be null:

GLG.ObjectsEqual( obj1, obj2 );

Predefined Constants

For methods that use predefined integer constants, the constants are grouped using an "enum" concept, with the "enum" name listed as a "type" in the online documentation. For example, the GetObjectType method returns an integer object type using constants defined in the GlgObjectType "enum", which is an object containing GLG object type constants.

Another example is a WRAPPED_TEXT constant that is defined in the GlgTextType "enum" and may be used to set TextType of a GLG text object:

text.SetDResource( "TextType, GLG.GlgTextType.WRAPPED_TEXT );

The WRAPPED_TEXT constant shown above should be used instead of its numerical value to provide the required integer value.

All "enums" are defined as properties of the global GLG handle object, which makes it easier to find constants using auto-completion.

The complete list of all enums can be found at the end of the GlgToolkit*.js files and can also be accessed online at the following link:

http://www.genlogic.com/doc_html/javascript_doc/namespacemembers_enum.html

Asynchronous Load

In JavaScript, all operations that load any file from a server, such as a drawing, data or any other resource, are asynchronous. As a result, the GLG methods that load files, such as LoadDrawingFromURL, take a callback parameter. The callback will be invoked synchronously when the loading request has been completed. A JavaScript application that loads any file from a web server should be aware of the asynchronous nature of the load requests and use an appropriate design.

A simplified LoadAsset method of the GLG API may be used by an application instead of handing HTTP requests in JavaScript to load any type of data the application may need.

Additional Programming Notes

1. The GlgObject instances received as parameters of a callback function, such as the Input or Trace callback, are valid only inside the callback and the assignment operator (=) cannot be used to store them in global variables to be used outside of the callback (the only exception are GlgObject instances received as parameters of the load callbacks). The static GetReference method must be used to store GlgObject in a global variable in a way that allows it to be used outside of the callback.
2. To minimize garbage collection, the ReleaseToCache instance method may be used to collect temporary objects, such as GlgPoint or GlgCube, after they have been used. ReleaseToCache may also be invoked on temporary GlgObject instances, in which case it will release to the cache the object's wrapper instance without affecting the internal GLG object the wrapper refers to.

Deploying GLG JavaScript Library

JavaScript Library Layout

The GLG JavaScript Library consists of two parts: the GLG object engine and the API bindings. A debugging version of the library described below is also provided. Depending on the flavor of the GLG API, several versions of the library are provided:

Standard API
Glg.js                         - GLG object engine
GlgDebug.js              - debugging version of the GLG object engine
GlgToolkit.js             - API bindings
Intermediate API
GlgInt.js                      - GLG object engine
GlgIntDebug.js           - debugging version of the GLG object engine
GlgToolkitInt.js          - API bindings
Extended API
GlgExt.js                     - GLG object engine
GlgExtDebug.js           - debugging version of the GLG object engine
GlgToolkitExt.js          - API bindings
Community Edition
GlgCE.js                     - GLG object engine
GlgCEDebug.js              - debugging version of the GLG object engine
GlgCEDebugSafary.js    - debugging version of the GLG object engine for the Safari browser
GlgToolkitCE.js             - API bindings

The libraries are located in the lib directory of the GLG installation.

GLG Demo Note

GLG demos in the DEMOS_HTML directory use the demo version of the GLG libraries:

GlgDemo.js
GlgToolkitDemo.js

To use the source code of any demo as a template for the application development and evaluation, use GlgCE.js and GlgToolkitCE.js in the .html file instead of GlgDemo.js and GlgToolkitDemo.js.

To run the demos, place the demo files on a web server, since most browsers will not allow running JavaScript demos from a local file system due to the security restrictions.

Deploying JavaScript Library in HTML

The GLG JavaScript library is deployed in the form of two files: Glg<V>.js and GlgToolkit<V>.js, where <V> is replaced with the type of the GLG API as described above. We will use the Standard API examples in the rest of this chapter.

The library also uses the gunzip.min.js file for uncompressing GLG drawings saved in the compressed format. These three script files must be included in the html file before the application script as follows:

<script defer src="Glg.js"></script>
<script defer src="GlgToolkit.js"></script>
<script defer src="gunzip.min.js"></script>
<script defer src="application_script.js"></script>

The application_script.js file provides custom application code.

Windows IIS Web Server Notes

Custom application/x-glg MIME type should be added for the GLG drawing files with the .g extension. To add a MIME type:

1. Start IIS Manager
2. Select MIME Types
3. Right-click, Add
4. In the Add MIME Type dialog, specify MIME type "application/x-glg",
File name extension ".g"
5. If the project uses subdrawings that were saved using an .sd extension, the extension would also need to be assigned the application/x-glg MIME type using the above steps. The .sd extension is filtered by the IIS by default, resulting in the "File Not Found" error for the subdrawings. To disable filtering of the .sd extension, a web.config file containing the following lines needs to be placed in the root directory of the project:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <security>
      <requestFiltering>
        <fileExtensions allowUnlisted="true">
          <remove fileExtension=".sd" />
          <add fileExtension=".sd" allowed="true" />
        </fileExtensions>
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

             A sample web.config file is provided in the src directory of the GLG installation.

Debugging Version of the GLG JavaScript Library

The debugging version of the JavaScript library file can be used for debugging purposes during application development. While it executes slower than the highly optimized production library, the debugging library contains various verification checks that help catch errors at the application development stage.

The debugging library performs type checking of all method parameters and generates an exception if an incorrect parameter type is detected. It is recommended that the debugging library is used for the development, and a production library is used only for the deployment, after thorough testing of all code branches.

The ThrowExceptionOnError method shown in the demos and examples code may be used to stop execution on the GLG errors: the stack trace in the browser's debugger will show the location of the code that caused the GLG error.

By default, GLG errors, such as "Can't find resource", generate an error message on the browser console, but do not stop execution of the program. Throwing an exception on error can help find the exact code in the application script that generated the error.

NOTE: The GlgCEDebugSafary.js file provided with the Community Edition can be used for debugging with the Safari browser on macOS.

Global Configuration Resources

GLG global configuration resources may be used to control some aspects of the GLG Toolkit run-time behavior. For example, GlgDisableMouseButtonCheck and GlgDisableControlKeyCheck resources may be used to adjust application behavior for mobile devices with a touch screen, and GlgWrapNativeLabels may be used to control label wrapping in native buttons and toggles. The GlgSetNativeAttributes resource may be used to obtain a more complete control over the native widgets' appearance inside a GLG drawing.

Refer to Appendix A: Global Configuration Resources on page 423 for a list of the global configuration resources.

Using HTML Cascading Style Sheets

HTML attributes of native widgets inside a GLG drawing, such as buttons, toggles, text boxes, etc.) may be controlled by the HTML style sheets using each widget class type. The browser's Inspector feature may be used to find the class assigned to a native widget of each type.

The HTML attributes of native widgets may also be set in the JavaScript code by using the GetNativeComponent method of a native widget's viewport to get the ID of the widget's HTML element and then using this ID to set the element's style attributes.

Deploying GLG Drawings Created in Different System Locales

JavaScript Encodings

Internally, JavaScript uses UTF-16 encoding to represent strings. When external strings are loaded in JavaScript, they are converted from an external encoding to UTF-16.

JavaScript supports a limited number of external encodings for importing strings, such as ASCII, Latin1 and UTF-8, and does not support all possible system locales for individual languages. Instead, it uses UTF-8 encoding for importing strings in different languages.

GLG JavaScript API uses Latin1 encoding as a default, which allows loading drawings containing both ASCII and Latin1 characters without a need to convert them to UTF-8. Drawings containing characters other than Latin1 stored in non-UTF-8 encodings need to be converted to UTF-8 as described below.

Using GLG Drawings in JavaScript

ASCII Drawings

GLG Drawings that contain strings with only ASCII characters do not require any special handling, since these characters are the same in the ASCII, Latin1 and UTF-8 encodings.

Latin1 Drawings

GLG drawings created in Latin1 locale and containing strings with Latin1 characters do not require any special handling either, since GLG JavaScript API uses Latin1 as a default encoding.

Non-ASCII Drawings Created on Linux/Unix in UTF-8 Locale

If GLG drawings containing non-ASCII characters (either Latin1 or in any other language) were created in the UTF-8 locale on Linux/Unix, they can be loaded into a GLG JavaScript program by either setting the GlgDefaultEncodingName global configuration resource to "utf8" to define a default encoding, or by specifying "utf8" as the encoding parameter value of the GLG drawing loading methods, such as LoadWidgetFromURL.

Non-Latin1 Drawings Created on Windows or on Linux in non-UTF-8 Locale

GLG drawings created in Latin1 locale do not require any special handling as described above.

If a GLG drawing containing characters in any other language was created in any system locale other than UTF-8, the strings have to be converted to UTF-8 by re-encoding them in UTF-8 and setting their UTF8Encoding flag. In the Graphics Builder or HMI Configurator, it may be done on per-string basis by clicking on the DEF toggle, which will change to UTF.

The GLG Drawing File Conversion Utility (gconvert) may be used to convert the entire drawing, or all drawings in a directory tree. The -convert-to-utf8 command-line option of the gconvert utility is used to convert all strings in a drawing to the UTF-8 encoding. The -r converter option may be used to recursively convert all drawing files in a directory tree.

Refer to the Drawing File Conversion Utility on page 406 for more information.

The converter should be run in the system locale in which the drawing was created. All strings in the drawing will be converted to UTF-8 and marked as UTF-8-encoded in the converted drawing by setting their UTF8Encoding flag. When the drawing is loaded by the GLG JavaScript library, the strings are automatically recognized as UTF-8 encoded and will be properly handled automatically.

The UTF-8 conversion makes the strings independent from the encoding specified in JavaScript. As a result, the converted drawing may be loaded in the GLG JavaScript program using the default (or any other) encoding settings.

The UTF-8 conversion is performed on string attributes that are objects, such as the TextString attribute of a text object. String attributes that are not objects, such as object names, tag names and tag sources, will not be converted.


Generic Logic, Inc.
www.genlogic.com
PREV NEXT