Introduction
- Before proceeding, be sure to review Interface Asset general concepts and our introduction to creating your own interface asset. Treat these articles as prerequisites to the content below.
- Did you know Intuiface Academy has a video-based lesson about Creating a JavaScript Interface Asset?
In addition to Intuiface's support for REST-based Web Service and .NET Interface Assets (IA), you can also extend your experiences using JavaScript (JS).
As with the REST IA, you can use JavaScript IAs on all Player-supported operating systems: Windows, iOS on the iPad, Android, BrightSign ChromeOS, and Samsung Tizen. The additional flexibility of JavaScript over REST makes it Intuiface's most powerful cross-platform IA protocol for handling logic, business rules, or any behavior you want to add to your project.
Useful link: Simple Counter source code. This archive contains the three following files:
- EventEmitter.js: to be used in all the JavaScript Interface asset you want to create, as a prototype object.
- SimpleCounter.js: sample source code
- SimpleCounter.ifd: sample Interface Descriptor file
To create a new JavaScript Interface Asset, we recommend you to download the simple counter archive then rename the files and objects to your needs.
Global Process
- Create your JS code in one or more .js files using your preferred editor (ex: Notepad++, WebStorm, Visual Studio...)
- Write the Interface Descriptor (.ifd) file describing the Properties, Triggers and Actions you want to expose to Intuiface
- Add a folder containing your .ifd & .js files into
C:\Users\{UserName}\Documents\Intuiface\Interface Assets
You can now use your custom JavaScript IA in any Intuiface project by following the instructions found in this article
JavaScript specifications, usage & limitations
From a technical point of view, Player for Windows embeds the Chrome V8 engine to run the JavaScript code you will write and use within Intuiface.
For more details on the JavaScript language, you can look at the ECMAScript language specification
Limitations
Chrome V8 is only a JavaScript engine, not a Web browser. Some common Web browser JavaScript properties and methods implemented by the 'window' object - such as 'location' - are not available. As a result, your IA must rely on JavaScript code only and will not work with libraries such as JQuery, Dojo, and so on.
Some criteria you want to consider when planning to include a library to a custom JavaScript Interface Asset are:
- library must be a front-end library
- library can be run in an iframe
- library won't be able to manipulate the DOM, as it will be "contained" in an iframe
- library must be ES5 compatible (for instance, keywords such as import/export are from ES6)
Examples of unsupported libraries: JQuery, Dojo, Angular, Node.
Intuiface Factory
To compensate for some JavaScript limitations, Intuiface offers a few services through a factory mechanism, such as
- Providing underlying system access such as file system, Web request, or printer
- Providing access to Intuiface mechanisms such as space content, asset properties, etc.
For more information about the Intuiface Factory, click here.
If you can't find a service you want to use in Intuiface, feel free to post your idea on our Ideas Community.
How to start creating your JavaScript Interface Asset
Create a .js file, specify the prototype of your main object if needed (see below), and declare a constructor
SimpleCounter.prototype = new EventEmitter(); SimpleCounter.prototype.constructor = SimpleCounter;
How to create Properties
You have to declare properties in the constructor of your object:
function SimpleCounter() { this.Count = 0; }
With the .NET DLL protocol, we recommended the implementation of an "INotifyPropertyChanged" .NET interface to ensure property values are updated in real-time on the Intuiface side.
To mimic this mechanism in the JavaScript protocol, we added the following coding convention: when a "XXXChanged" event is emitted from the JS Interface Asset, a change of the "XXX" property (if it exists) will be automatically applied on the Intuiface side.
Note: The new value of the property must be passed as an argument of this event.
Example:
SimpleCounter.prototype.AddOne = function () { this.Count++; this.emit('CountChanged', [this.Count]); };
Reminder: You can download the full SimpleCounter.js file here
To create setters for your properties, the convention is to create a function for your prototype named setPropertyname. This will allow you to modify those properties directly in Intuiface Composer when creating your Experience.
Example:
//let's say you have a new InitialValue variable declared in your constructor //here is the setter that will be called when you change the value in Composer SimpleCounter.prototype.setInitialValue= function (value) { if (this.InitialValue != value){ this.InitialValue = value; this.emit('InitialValueChanged', [this.InitialValue]); } };
How to create Triggers (events)
Though events are not part of the JavaScript core specification, it is very common and easy to implement such a mechanism.
Intuiface uses a modified version of the EventEmitter library. You need to download the only required file here: EventEmitter.js
How to use it:
- first set EventEmitter as the prototype of your main object (this is similar to the inheritance mechanism in .NET)
- then call the emit function with
- required: the event name as the first argument
- optional: an array containing your event arguments. This can be empty or an array of 1 item only.
Example:
MyObject.prototype = new EventEmitter(); this.emit('ASimpleEvent'); this.emit('AnEventWith1Argument', [arg1]); this.emit('AnEventWith3Arguments', [arg1, arg2, arg3]);
You then have to declare them in your Intuiface Descriptor (.ifd) file using the following syntax
"events" : { "ASimpleEvent" : { "id" : "ASimpleEvent", "title" : "A Simple Event" }, "AnEventWith1Argument" : { "id" : "AnEventWith1Argument", "title" : "An Event With 1 Argument", "properties" : { "arg1" : { "title" : "Argument 1", "type" : "string" } } }, "AnEventWith3Arguments" : { "id" : "AnEventWith3Arguments", "title" : "An Event With 3 Arguments", "properties" : { "arg1" : { "title" : "Argument 1", "type" : "string" }, "arg2" : { "title" : "Argument 2", "type" : "string" }, "arg3" : { "title" : "Argument 3", "type" : "string" } } } }
How to create Actions (functions)
For each action, add a JS function to your main prototype:
SimpleCounter.prototype.AddOne = function () { //write your code here };
If you plan to launch a large processing treatment, we recommend you run it asynchronously via Promises.
Debug & Logs
NOTE: These logs are currently only available with Player for Windows
Two levels are available for logging:
console.log("My Log"); console.error("My Error");
This will respectively display the following logs in the Trace.log file:
---------------------------------------- 20/11/2014 09:57:43 : General : My Log ---------------------------------------- ---------------------------------------- 20/11/2014 09:57:44 : Error : My Error ----------------------------------------
This log file is located inC:\ProgramData\IntuiLab\Intuiface\Composer\Logs
Writing the Interface Descriptor (.ifd)
As with the REST-based Web Service IA, you have to write the Interface Descriptor (.ifd) file that will describe all the elements within your JavaScript IA that will be exposed and available in Intuiface. In fact, the rules for writing this .ifd file are identical for the REST and JavaScript IAs.
Complete documentation for writing the .ifd file is here and a SimpleCounter sample is here.
Comments
0 comments
Article is closed for comments.