Create a JavaScript Interface Asset

Table of Contents

    Introduction

    NOTE: 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.

    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, Chrome, Samsung Tizen and LG webOS. 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 into your project.

    Useful links:

    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.

    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 just have to declare them in the constructor of your object:

    function SimpleCounter() {
        this.Count = 0;
    }
    

    With the .NET DLL protocol, we recommended the implementation of a "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 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)

    You just have to 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 in:

    • C:\ProgramData\IntuiLab\IntuiFace\Composer\Logs for IntuiFace 6 and above.

    • C:\ProgramData\IntuiLab\IntuiFace5\Composer\Logs for IntuiFace 5

    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