Use IntuiFace Factory Services in Javascript Interface Assets

    Introduction

    Before proceeding, be sure you know how to create your own JavaScript Interface Asset

    To ensure JavaScript Interface Assets work both on Player for Windows and Player for iPad, this protocol has a few limitations - described in this article - that need to be overcome. This is why we created the IntuiFace Factory, exposing IntuiFace services accessible on all platforms.

    Usage

    In your JS code, just call the get function of the intuiface object with the name of the service as a parameter:

    this.myServiceInstance = intuiface.get("serviceName");

    At this moment, the following Factory services are available:

    • HTTP request
    • MailAsAService
    • File service

    If you can't find a service you want to use in IntuiFace, feel free to post your idea to our Ideas Community.

    HTTP Service

    Name: httpService

    Specification

    • get(url, headers, callbacks) :invoke a web service using the GET verb. Note that parameters must be passed in the URL.
      • url (string) : URL to call.
      • headers (object) : A JSON object containing the headers parameters,
      • callbacks (object) : callbacks after invocation of the URL.
        • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
        • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
    • post(url, headers, params, callbacks): invoke a web service using the POST verb.
      • url (string) : URL to call.
      • headers (object) : A JSON object containing the headers parameters,
      • params (object) : POST body parameters. Can be a string or a JSON object.
      • callbacks (object) : callbacks after invocation of the URL.
        • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
        • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
    • put(url, headers, params, callbacks): invoke a web service using the PUT verb.
      • url (string) : URL to call.
      • headers (object) : A JSON object containing the headers parameters,
      • params (object) : PUT body parameters. Can be a string or a JSON object.
      • callbacks (object) : callbacks after invocation of the URL.
        • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
        • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
    • patch(url, headers, params, callbacks): invoke a web service using the PATCH verb.
      • url (string) : URL to call.
      • headers (object) : A JSON object containing the headers parameters,
      • params (object) : PATCH body parameters. Can be a string or a JSON object.
      • callbacks (object) : callbacks after invocation of the URL.
        • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
        • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.
    • del(url, headers, callbacks): invoke a web service using the DELETE verb. Note that parameters must passed in the URL.
      • url (string) : URL to call.
      • headers (object) : A JSON object containing the headers parameters,
      • callbacks (object) : callbacks after invocation of the URL.
        • success(result) is called when the URL has been successfully invoked. The 'result' parameter contains the data received by the call.
        • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reason for the failure.

    Example

    var httpService = intuiface.get("httpService");
    
    var self = this; //to be able to use "this" in the callbacks
    
    httpService.get("http://mywebservice.com/serviceName?param1=value&param2=value", { 
                    "success": function(result) {
                     //process your result
                     self.emit('Success', [result]);
                    },
                    "error" : function(errorMessage) {
                        self.emit('Error', [errorMessage]);
                    }});
     
    httpService.post("http://mywebservice.com/authenticate", 
                     "key1=value1;key2=value2", { 
                    "success": function(result) {
                     //process your result
                     self.emit('Success', [result]);
                    },
                    "error" : function(errorMessage) {
                         self.emit('Error', [errorMessage]);
                    }});
    

    Mail as a service

    Name: mailService

    Specifications

    • sendMessage(to, subject, body, attachments, callbacks) : send email using IntuiLab's hosted email service. Note that Composer Free experiences are limited to a quota of 10 emails per day and all emails sent by IntuiLab's hosted email service contain an IntuiFace tagline.
      • to (string) : recipient of the message (only one recipient per call)
      • subject (string) : subject of the email
      • body (string) : content of the email. Can be plain text or HTML-formatted.
      • attachments : list of local file paths to attach to the e-mail.
      • callbacks (object) : callbacks after invocation of the mail service.
        • success() is called when the email has been successfully sent.
        • error(errorMessage) is called in cases of failure. 'errorMessage' is an indication of the reasons for failure.

    Example

    var mailer = intuiface.get("mailService");
      
    mailer.sendMessage(to, subject, body, attachments, {
            "success": function () {
                 self.emit('MailSent');
            },
            "error": function (errorMessage) 
            {
                 self.emit('Error', [errorMessage]);
            }});
    

    File Service

    Name: fileService

    Usage: this.fileService = intuiface.get('fileService', this);

    WARNINGS:

    • Do not forget the second parameter in the above call.
    • For security reasons, you can only access files and folders located in your Interface Asset folder, e.g. C:\Users\{UserName}\Documents\IntuiFace\{XPName}\Files\InterfaceAssets\{MyJS_IA}
    • This service cannot be instantiated in your interface asset's constructor and requires a little delay. Here is an example:
    var self = this;
        setTimeout(function() {
             this.fileService = intuiface.get('fileService', this);
       }, 500);
    

    Specifications

    • read(filePath: string, isBinary: boolean, callbacks: {'success': function, 'error': function}): void: read the content of either a text or binary file
      • parameters:
        • filePath: relative file path (i.e. relative to the experience folder) of the file to be read
        • isBinary: indicates if it's a text file or a binary file (such as an image)
        • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
          • If successful, it will receive as an argument either the text for a text file or the binary content as a byte array (type ArrayBuffer if using Player for Tables/Kiosks, array of bytes if using Player for Windows)
          • If unsuccesful it will receive a displayable error indicating what went wrong
        • return nothing
    • write(content: string|ArrayBuffer|Blob, filePath: string, isBinary: boolean, callbacks: {'success': function, 'error': function}): void: write the given content into a file. Content can be text or binary data.
      • parameters:
        • content can either be a string or a binary type such as ArrayBuffer or Blob.
        • filePath: relative file path (i.e. relative to the experience folder) of the file to be written
        • isBinary must be consistent with the given content type and indicate what kind of writing must be applied
        • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
          • , it will not receive any argument
          • If unsuccessful, it will receive a displayable error indicating what went wrong
      • returns nothing
    • getFilePath(relativePath: string, callbacks: {'success': function, 'error': function}): string: gets the absolute file path for a file path relative to the experience
      • parameters:If successful
        • relativePath: relative file path (i.e. relative to the experience folder)
        • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
          • If successful, it will receive the displayable path as argument
          • If unsuccessful, it will receive a displayable error indicating what went wrong
      • returns: the absolute file path. Can be assigned, for example, to the "Image" property of the Image asset. This method is synchronous and asynchronous in order to manage calls from the IA (asynchronous) and also internal calls (for the player internal sauce)
    • deleteFile(filePath: string, callbacks: {'success': function, 'error': function}): void: delete the given file from its relative path.
      • parameters:
        • filePath: relative file path (i.e. relative to the experience folder) of the file to be deleted
        • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
          • If successful, it will not receive any argument
          • If unsuccessful, it will receive a displayable error indicating what went wrong
      • returns: nothing
    • getDirectoryContent(directoryPath: string, calbacks: {'success': function, 'error': function}): array: get the contents of the directory indicated by a relative path
      • parameters:
        • directoryPath: the relative path to the directory whose content is to be listed
        • callbacks: as with all service communication, this is used to capture the result or the error in an asynchronous way
          • If successful, it will receive an array of entries
          • If unsuccessful, it will receive a displayable error indicating what went wrong
      • returns: the list of entries of the directory. Each entry will have the following properties:
        • name: name of the entry
        • isDirectory: boolean indicating if the entry is a directory or not
        • isFile: boolean indicating if the entry is a file or not
        • fullPath: the absolute path of the entry

    Samples

    Email body formatter

    You can download an example of an email body formatting interface asset here. This interface asset will load an HTML template from a file located next to the JavaScript file and will let you generate an email body based on several input parameters.
    You can see it in action in our Food Ordering sample.

    Folder as a dynamic source for a collection

    You can use the GetDirectoryContent action to dynamically get the list of objects contained within a folder located next to your Interface Asset in the project file structure. For security reasons, the fileService will not permit you to access files outside of this folder.

    You can download a sample here that will list all the images within a folder named Images located next to your interface asset files.