Creating JS Service

Creating JS Service 

To create a JS service, you can use the ares-generate command that generates a JS service project from the template. If you do not have an app project where you call the service, you should create an app project before creating a JS Service. Note that JS Services cannot be packaged alone.

The service name must begin with the app name. If you do not follow this naming rule, the service packaging does not work correctly. For example,

  • App name: com.example.myapplication

  • Service name: com.example.myapplication.myservice

The usage of ares-generate command and options are as below. Depending on the app type, specify the -t option with the appropriate template. Here are some examples of different uses:

Create Dummy Web App from a Template with CLI

ares-generate -t basic -p "id=com.yourdomain.myapp" samplePrj

After you have created an app project, create a JS service project with a service name beginning with the app name.

Create JS Service from a Template with CLI

ares-generate -t js_service -s com.yourdomain.myapp.service samplePrjService

For usage of ares-generate command and options, see ares-generate

You can also use the Plugin for Sublime Text to create JS service. See Using Plugin for Sublime Text.

Structure of JS Service

Once you generated the JS service project, you should configure the JS service directory as below. 

Essential files and folder structure of app and service

  • APP_DIR: Directory of the application

  • SERVICE_DIR: Directory of the service where a subfolder named with the service name and JS Service files are located. You can locate multiple service folders in SERVICE_DIR.

For the description of the service sub-directory files, see the next section.

Registering JS Service

A JS service is made up of the following files:

  • package.json: Configures the service meta-data and points to the main service file. This file is used for packaging (Related with Node.js).

  • services.json: Defines the services and their methods. This file is used for registering JS service on the Luna bus.

  • JavaScript Service Source files: Service implementation files provide the various use case of JS service.

package.json File

As a service program is a Node.js module, the service must have a package.json file. The minimal package.json looks like this:

{
	"name": "com.mycom.helloworld.service",
	"main": "helloworld_webos_service.js"
}
  • In the name property, write your service name.

  • In the main property, write your main service JavaScript file name.

There are quite a few other values one can set in the package.json file. For the complete specification of package.json, see NPM (node package manager)

services.json File

This service configuration file describes what commands the service provides on the webOS bus. Define commands to be called from other apps and services. For more information, see services.json.

{
	"id": "com.mycom.helloworld.service",
	"description": "Sample helloworld service",
	"services": [{
		"name": "com.mycom.helloworld.service",
		"description": "Sample helloworld service"
	}]
}

Main Service JavaScript File

In the main service JavaScript file, you should define a single command assistant to execute the command defined in the services.json file.

Before registering a service into your code, you should load the webos-service module. The webos-service module for Node.js provides an interface to the system bus, wrapped in familiar Node.js idioms.

The following example shows how to loads the webos-service module. 

var Service = require('webos-service');

The following JavaScript example registers a service (luna://com.mycom.helloworld.service/hello) which responds to a request with a "Hello, World!" message.

var service = new Service("com.mycom.helloworld.service");

service.register("Hello", function(message) {        
	message.respond({
                Response: "Hello, World " + message.payload.name + "!"
       });
});

For more detail about the webos-service module, see webos-service API Reference.

Packaging JS Service

Once you finish registering service and implementing app and service, you need to package them into an .IPK file.

For packaging JS service, usage of ares-package command and options are as below. As mentioned in the figure above, APP_DIR and SERVICE mean app and service directories. You can use an absolute or relative path for both APP_DIR and SERVICE_DIR. 

ares-package APP_DIR SERVICE_DIR

Here are some examples of different uses:

Packaging service with an absolute path (in Windows)

ares-package c:\samples\app1 c:\samples\service1

Packaging service with an absolute path (in Linux/Mac OS)

ares-package ~/samples/app1 ~/samples/service1

Packaging service with a relative path (in Windows)

ares-package app1 service1

Packaging service with a relative path (in Linux/Mac OS)

ares-package ./app1 ./service1

Packaging multiple services an app (in Windows)

ares-package app1 service1 service2

Packaging multiple services an app (in Linux/Mac OS)

ares-package ./app1 ./service1 ./service2

For usage of ares-package command and options, see ares-package.

Navigation