Interface definition language

The IDL is a way of generating enough native code to prompt the native code's compilers and IDEs to take notice of the Javascript code.

It provides a set of documents that detail the conversations that native code and shared code is having, which becomes a point of conversation between engineers of different disciplines during the design phase of the app.

File structure

All IDL files are just javascript modules. But the build needs to be able to find them.

Place them in a directory, for example called idl.

Edit the package.json file to include a kirin object (this is probably already there), and in the kirin object, put an entry for idl. The value is the relative path to the directory where the idl files will reside.

{
  "name": "idl-example",
  "kirin": {
    "idl": "idl"
    "directories": ["shared"]
  }
}

Then place the *.idl.js files inside the idl directory.

Organization

Each idl file is a node.js module which exports a single object:

module.exports = {
    namespace: "org.acme.firstapp",
    classes: {
        "INextScreenModule": {
            implementedBy: "javascript",
            namespace: ".shared",
            methods: {
                "setItem:Name:": [{id:"integer"}, {name:"string"}],
                "onItemTapped:": [{id:"integer"}]
            }
        },
        
        "INextScreen": {
            implementedBy: "native",
            namespace: ".android",
            methods: {
                "setDataForScreen": [{data:"INextRequest"}]
            }
        },
        
        "INextRequest": {
            namespace: ".shared.requests",
            role: "request",
            properties: {
                name: "string"
            }
        }
    }
};

Non-obvious keywords:

• namespace: the namespace maps to the package name where the Java interfaces will end up. They have no relevance in Objective-C.
• implementedBy: Accepts two values: native and javascript. This will affect what kind of protocols and interfaces that will be constructed. Both these types may only have methods.
• role: Accepts two values: request and response. Request objects may have methods, and properties. These will be read-only properties. Response object may have only properties.

If your repsonse objects have methods, you will need to treat them so kirin knows how to invoke the callback methods:

var transportableRequest = require('kirin-bridge').makeTransportable(request);
theScreen.displayRequest(transaportableRequest);