Thinfinity VirtualUI offers a rich API that allows for a tight integration with external web resources.

JavaScript Remote Objects (jsRO) makes possible to define remote objects and expose properties, methods and events that are synchronized in both ends, the application and the web browser.

Web Components specialized methods let you embed HTML and Javascript components that can enhance your application with web browser content.

Read more:

· JavaScript Remote Objects (jsRO)

· Web Components

Thinfinity VirtualUI includes an html test environment called Development Lab. You can test your customized application and access the available programming resources through the objects.

The Development Lab will load when you execute an application in Dev mode from your development environment by calling the URL where Thinfinity VirtualUI is running (i.e. http://127.0.0.1:6080/).

The environment consists of five panels:

· The Address bar. Load here the web page address that you want to open. If you call the root address ("/"), app.html will load; if you enter an application's virtual path, it will load the address that was specified as Home Page for this application in the Thinfinity VirtualUI Server Manager, and if the Home Page wasn't defined it will load app.html.

· The Model Inspector. The Model Inspector's function is to show the available properties, methods and events for each data model. In its upper part there's a combobox that shows the published models; by selecting an item you will see its attributes. From this panel, you can change the properties value, provided that they are not read-only.

· The Log pane. The log pane shows a log of the interaction between the jsRO object and the application. The newer entrances will show on top.

· The Console pane. In the console pane, you can assign a new value to a property or call a method.

· The Browser pane. This is the most important panel. The selected application will load there and it will show just like it would in the browser independently.

Read more:

· Life Cycle of jsRO Objects

· Creating jsRO Objects

· Updating Properties

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

As stated previously, the sjRO models are created in the application and then propagated to the browser, where they can be consumed from Javascript through a Thinfinity.sjRO class instance.

Let's see a complete example of this sequence:

Both examples create a 'ro' object, which has a 'text' property with the value: 'Hello!'.

Using Delphi, in the Create method of the form:

// Creates the remote object and its property
 ro := TJSObject.Create('ro');
 ro.Properties.Add('text');
 ro.ApplyModel;

Using C# (.Net Winform application)

// Creates the remote object and its property
 ro = new JSObject("ro");
 ro.Properties.Add("text");
 ro.ApplyModel();

Let's see how to work with this object from Javascript:

$(document).ready(function () {

 ...
 ...
 var jsro = new Thinfinity.JsRO();
 var ro = null;
 ...
 ...
 jsro.on('model:ro', 'created', function () {
 ro = jsro.model.ro;
 });
 });

Sequence diagram for the creation of an object:

Read more:

· Updating Properties

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

When publishing a model, jsRO will keep the state of the created object synchronized in the application side and in the browser. Each time a property is updated in the server side, this change is propagated to the browser, where besides updating the value it can be handled by the corresponding .on(“model:object.property”, “change”, …) event, if this event was declared.

When a property is updated on the browser side, this change is sent in the opposite direction (from the web to the application) and triggers an OnPropertyChange event in the instantiated JSObject object. This is a good place to do things like propagating the change of a property value to some other element of the application, update a group of values in a database, etc.

jsRO can also handle changes in the properties of its object through the declaration of the OnSet and OnGet property events.

By invoking the ApplyChanges method on a JSObject object, the collection of the properties added to the object is traversed and if any of these properties has an OnGet event declared, it's triggered.

The OnSet event, however, is executed when it receives a change from a particular property from the browser.

The way to add the OnSet and OnGet event handlers to a property is based on their definition, you can do so when of adding the property or afterwards, always remember to fire an ApplyModel so that the model is propagated to the browser.

The next example shows how the browser can retrieve the application form background color in a #RRGGBB format, and also how to change the background color using a value sent from the browser. Since the desktop application doesn't interpret colors like the web does, we need a conversion that works both ways:

Delphi Definition:

.Net definition:

Assigning the property value in Javascript:

In order to achieve more interaction between the remote application and the browser, the object model provided by jsRO allows the creation of remote methods and events defined in the application by the developer. Both the methods and the events are created and added to a model. While the methods can be invoked from the browser to remotely execute the application's own actions, the events are fired from the application to the browser, where they can be handled by the corresponding callback.

Read more:

· Remote Methods

· Custom Events

JavaScript Remote Objects (jsRO) allows you to increase your application's power, extending it to the web environment. This is made possible by the publishing of data models defined programmatically from the application that expose properties, methods and events, easing the dialog between the web and the original application.

To make the development of applications with jsRO easy, Thinfinity VirtualUI provides a web environment that allows you to interact with the application during the development and test its functionality: the Development Lab.

Read more:

· The Development Lab

· Life Cycle of jsRO Objects

· Creating jsRO Objects

· Updating Properties

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

jsRO objects are always defined inside the application and propagated to the browser. New properties, methods or events can't be added From Javascript, but events that are produced can be handled, the property values can be retrieved and modified, and the object's methods can be invoked.

There are four pre-defined Javascript events that are related to the life cycle of a jsRO object, associated to its creation, updating and destruction,

Starting from the first ApplyModel produced in the application, jsRO will create the object, propagate it to the browser and trigger there the event related to this creation:

on(“model:object”, “created”)

also, for the properties that are created with an assigned value, jsRO will replicate their initial values in the browser and fire the corresponding events:

on(“model:object.property”, “changed”)

and from that moment on, it will keep the state of the properties synchronized in the application and the browser.

If the model needs to be updated by the addition of new attributes (properties, events or method) a new ApplyModel must be made, which will, in turn, with the model already created, fire a changed event on the model:

on(“model:object”, “changed”)

Finally, if the object is destroyed in the application, the deleted event will be triggered and the object will be destroyed in Javascript too.

on(“model:object”, “deleted”)

This last event will also be triggered when closing the application.

Read more:

· Creating jsRO Objects

· Updating Properties

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

Below you'll find the available demos for JSRO and Thinfinity VirtualUI :

· Vui-Video = This demo uses JSRO to transmit a video for rendering in the browser.

· Vui-Audio = This demo uses JSRO to send audio directly to the browser.

· Vui-QZ = This demo uses JSRO to scan barcodes and send them to the application.

· Vui-Webcam = This demo uses JSRO to access the user Webcam and transmit it to the application.

We took VirtualUI integration tools one step further and created the HTMLDoc Object to enhance the integration of Windows app resources to the web.

This object handles web elements from the server side, sparing the developer the need to learn javascript to include interactive web content in their application. This makes the web enabling process much more straightforward in terms of time and organization and empowers developers to easily enhance their VirtualUI web enabled application with reusable widgets and components in web documents and web applications.

This API allows your to take advantage of Web Components and can also be used to include and run Javascript files that do not follow the HTML5 Web Component specification.

Read more:

§ The HTMLDoc Object

§ Web Components

jsRO will keep each property synchronized in the browser and in the application. Each time a property is updated in the server side, this change triggers an event to the browser, where it can be handled by the corresponding on(“model:object.property”, “change”, …) event, if this event was declared. Similarly, when a property is updated in the browser, this change travels to the application and triggers the object.OnPropertyChange and property.OnSet events.

Sequence diagram for the assignation of a property value from the application and from the browser:

Read more:

· OnPropertyChange(), OnSet() and OnGet() Events

· jsRO Remote Calls

The remote jsRO methods allow you to make the application's own actions available to be invoked from Javascript.

When the invokation of a method arrives to the application from the browser, two events are fired: the first is OnMethodExecuted, at the level of the JSObject object, which receives all the methods calls from the browser; the second is OnCall, and it happens at the level of the remote method.

If the invoked method is a function (if it returns a value), the value will be returned and propagated to the browser, where it will be handled asynchronously by a callback defined as the last argument in the call to the method.

The following examples show how to add a method to an object and how it can be called from Javascript. In this case, we create a method called multiply, which will receive two integer type arguments as parameters and will return the result of the product between them. This result will be shown in the callback to the method call.

Method definition in Delphi:

// Creates the remote object
 FRo := TJSObject.Create('ro');
 // Adds the method
 FRo.Methods.Add('multiply') // Returns a IJSMethod
 .AddArgument('a', JSDT_FLOAT) // First value to multiply
 .AddArgument('b', JSDT_FLOAT) // Second value to multiply
 .OnCall(TJSCallback.Create( // Adds the callback
 procedure(const Parent: IJSObject; const Method: IJSMethod)
 var
 a, b: int;
 begin
 a := Method.Arguments['a'].AsFloat;
 b := Method.Arguments['b'].AsFloat;
 Method.ReturnValue.AsFloat := a * b;
 end))
 .ReturnValue.DataType := JSDT_FLOAT; // Sets the return type
 FRo.ApplyModel;

Method definition in .Net:

// Creates the remote object
 ro = new JSObject("ro");
 // Adds the method
 ro.Methods.Add("multiply") // Returns a JSMethod
 .AddArgument("a", IJSDataType.JSDT_FLOAT) // First number to multiply
 .AddArgument("b", IJSDataType.JSDT_FLOAT) // Second number to multiply
 .OnCall(new JSCallback( // Adds the callback
 delegate(IJSObject parent, IJSMethod Method)
 {
 float a, b;
 a = Method.Arguments["a"].AsFloat;
 b = Method.Arguments["b"].AsFloat;
 Method.ReturnValue.AsFloat = a * b;
 })).ReturnValue.DataType = IJSDataType.JSDT_FLOAT;
 ro.ApplyModel();

Method definition in C#:

// Creates the remote object
ro = new JSObject("ro");
// Adds the method
ro.Methods.Add("multiply") // Returns a JSMethod
 .AddArgument("a", IJSDataType.JSDT_FLOAT) // 1st number to multiply
 .AddArgument("b", IJSDataType.JSDT_FLOAT) // 2nd number to multiply
 .OnCall(new JSCallback( // Adds the callback
 delegate(IJSObject parent, IJSMethod Method)
 {
 float a, b;
 a = Method.Arguments["a"].AsFloat;
 b = Method.Arguments["b"].AsFloat;
 Method.ReturnValue.AsFloat = a * b;
 }))
 .ReturnValue.DataType = IJSDataType.JSDT_FLOAT;
ro.ApplyModel();

Invoke the method in order to run it from Javascript. Use a callback in case the result needs to be retrieved (like in this case):

 ro.multiply(3, 4, function (result) {
 alert("Result is " + result);
 });

Read more:

· Custom Events

Thinfinity VirtualUI allows you to load and run Javascript files from the Windows app. In order to load a new javascript file, you can use the LoadScript method of the HTMLDoc component:

VirtualUI.HTMLDoc.LoadScript(URL, [Filename])

· The "URL" parameter is the Uniform Resource Locator pointing to the Javascript file location in the net.

· "Filename" is an optional parameter that, when specified, points to the actual Javascript file in the local file system. In this case the "URL" parameter will be virtual, and will resolve to this local "filename".

Custom Events

On top of the events detailed in Life Cycle of jsRO Objects, events can be created in the application that are defined by the programmer and when fired will be propagated from the application to the browser.

The following example shows how to add a personalized event to an object and how this can be handled from Javascript. In this case we'll expose, as a JSON, the mouse coordinates.

Definition and use of an event in Delphi:

// Creates the remote object
 FRo := TJSObject.Create('ro');
 // Adds the event
 FRo.Events.Add('mousePositionChanged')
 .AddArgument('coords', JSDT_JSON); // Adds the mouse position as JSON
 FRo.ApplyModel;
 procedure TForm1.FormMouseMove(Sender: TObject; Shift: TShiftState;
 X, Y: Integer);
 begin
 FRo.Events['mousePositionChanged']
 .ArgumentAsJSON('coords', '{"x": ' + X + ', "y": ' + Y + '}')
 .Fire;
 end;

Definition and use of an event in .Net:

// Creates the remote object
 ro = new JSObject("ro");
 // Adds the event
 ro.Events.Add("mousePositionChanged")
 .AddArgument("coords", IJSDataType.JSDT_JSON) // Adds the mouse position as JSON
 ro.ApplyModel();
 ...
 ...
 private void Form1_MouseMove(object sender, MouseEventArgs e)
 {
 ro.Events["mousePositionChanged"]
 .ArgumentAsJSON("coords",
 "{ \"x\": " + MousePosition.X + ", \"y\": " + MousePosition.Y + "}")
 .Fire();
 }

Definition and use of an event in C#:

// Creates the remote object
ro = new JSObject("ro");
// Adds the eventro.Events.Add("mousePositionChanged")
.AddArgument("coords", IJSDataType.JSDT_JSON) //the mouse position as JSON
ro.ApplyModel();
...
...
private void Form1_MouseMove(object sender, MouseEventArgs e)
{ ro.Events["mousePositionChanged"]
 .ArgumentAsJSON("coords", "{ \"x\": " + MousePosition.X + ", \"y\": " + MousePosition.Y + "}")
 .Fire();
}

To handle the event in Javascript, please note that the Javascript syntax for the personalized events differs slightly from the syntax for the model events, since it's declared directly associated to the name of the jsRO (without the "model"):

 jsro.on('ro', 'mousePositionChanged', function (coords) {
 console.log('mouse moved to [' + coords.x + ', ' + coords.y + ']');
 });

VirtualUI provides a specialized application-side object called HTMLDoc, with methods that allow you to add web content without changing the original HTML or javascript files.

· Load and run Javascript files from the Windows app.

· Import HTML files from the Windows app.

· Securely access files not located in the web tree (needed to deploy web or media files along with your application).

· Create an HTML5 Web Component defined in an imported HTML file.

With the purpose of providing secure urls to files that are not located in the application's web tree, we included two methods:

VirtualUI.HTMLDoc.CreateSessionURL(URL, LocalPath)

This method allows you to create a virtual URL valid during the session's lifetime.

· The "URL" parameter is the virtual URL to access the Filename or Directory specified in LocalPath.

· "LocalPath" can be a file name or a directory. If it is a file name, the URL parameter resolves to that filename; if it is a directory, the URL parameter is a virtual path that can be used to access any file under this local directory.

URL = VirtualUI.HTMLDoc.GetUniqueURL(Filename, lifetime)

This method allows you to create a unique virtual URL for a specific file, valid during the time specified in minutes in the Lifetime parameter.

· The "Filename" parameter points to the local filename we want to create an unique URL for.

· "Lifetime" is the time during which the returned URL will be valid.

To create a Web Component instance, we added a specific method that will allow you to embed the component in the web page, tied or untied to a Windows control.

When the Web Component is tied to a Windows control, it will look like it is "embedded" in the form, replacing the Windows control area, following its position and size when it changes. When untied, it will be embedded into the web page, but its position and size will not be attached to any control area.

VirtualUI.HTMLDoc.CreateComponent(Id, TagOrHTML, ReplaceWnd)

· "Id" parameter is the HTML element ID.

· "TagOrHTML" can be a tagname or a valid HTML string.

· "ReplaceWnd" is the handle to the window control to be "replaced".

Examples:

1. Adding a tied Web Component by the tagname:

VirtualUI.HTMLDoc.CreateComponent("video1", "vui-video", panel1.Handle)

In this example, the HTML "<vui-video></vui-video>" will be inserted, and dynamically positioned according to panel1's position and size.

1. Adding tied HTML content from a valid HTML string:

VirtualUI.HTMLDoc.CreateComponent("hworld", "<div><span>hello world</span></div>", panel1.Handle)

In this example, the HTML "<div><span>hello world</span></div>" will be inserted, and dynamically positioned according to panel1's position and size.

1. Adding an untied Web Component by the tagname:

VirtualUI.HTMLDoc.CreateComponent("qzprinter1", "qzprinter")

In this example, the Web Component will be inserted, but not positioned according to any visible control.

Web Components are defined in HTML files. In order to be able to create a Web Component, you need to import that file into the HTML DOM. With VirtualUI you can do this from your Windows app by calling the ImportHTML method of the HTMLDoc component.

Let's suppose that you are about to include some new functionality and logic which may need some Javascript library that is currently not loaded.

In order to load this new javascript library you can use the LoadScript method of the HTMLDoc component.

Thinfinity VirtualUI allows you to insert HTML content into the current web page. You can do this from your Windows app by calling the ImportHTML method of the HTMLDoc component:

VirtualUI.HTMLDoc.ImportHTML(URL, [Filename])

· The "URL" parameter is the Uniform Resource Locator pointing to the HTML file location in the net.

· "Filename" is an optional parameter that, when specified, points to the actual HTML file in the local file system. In this case, the "URL" parameter will be virtual, and will translate to this local "filename".

Let's suppose we include a web component that needs to display a signature, and the signature image file is somewhere in the file system. Complying with standard web server specifications, Thinfinity VirtualUI forbids the access to files that are not in the root web tree. This means that to access that image file, you would be forced to first place it in the application's web tree. This wouldn't be neat!

With the purpose of providing secure urls to files that are not within the web tree root, we included the CreateSessionURL and GetUniqueURL methods. These methods help you create virtual URLs for the application session's lifetime, or for a specific file and valid only during a specified lifetime, in minutes.

Web Components are a new and exciting technology that takes the well known "reusable software components" concept to the web. With this HTML5 specification you can build HTML+javascript pieces and use them as a custom HTML element.

In Thinfinity VirtualUI you can easily embed Web Components in your Windows application. Some Web Components examples are: a native video streaming component, a raw printing component, a QR component, a signature component, a Google Maps component, and so on.

With the purpose of embedding a Web Component in a Windows application, we provide a specialized object that allows you to:

· Load and run Web Component Javascript files from the Windows app.

· Import Web Component HTML files from the Windows app

· Securely access local resources that are not in the application's web tree (needed to deploy web or media files in your application)