Creating JS Services

Version added 09-Oct-2016| Modified 15-Oct-2018

External JS services must be packaged in a web app. Therefore, before creating a JS service, make sure you have a web app from where the service can be called. If the calling web app is not available, create a web app as described in Creating Web App.

JS services can be created and deployed using CLI commands that are provided by webOS OSE SDK. This topic describes the steps to create an external JS service. For detailed information on the commands, see Command Line Interface.

Once you generate the service, JS service directory should be configured as below.

 

JSservice_creation.png

 

  • APP_DIR: Directory of the web app.

  • SERVICE_DIR: Directory of the service. This directory will include sub-directories of the services that are included in the web app.

Step 1: Create JS Service Project

You must start by creating a project using the available JS service template. 

To create a basic JS service, execute the following command:

ares-generate -t js_service sampleService

In the above command:

  • <js_service> is the name of the template that creates a basic JS service.

  • <sampleService> is the JS service directory which is created in the current directory.

When prompted to enter the service name, make sure the service name begins with the app ID. If you do not follow this naming rule, the service packaging does not work normally. So, for example:

If web app ID is: com.domain.app

Then, service name must be: com.domain.app.myservice

The JS service directory (SampleService) has the following files:

File

Description

helloclient.js

Sample JS service which subscribes helloworld_webos_service.js service. This sample shows how to communicate between services.

helloworld_webos_service.js

Sample JS service which provides several simple commands. These commands are specified in the services.json file.

package.json

Configuration file of NPM. For details, see https://docs.npmjs.com/getting-started/using-a-package.json

services.json

Configuration file that defines what commands the service provides on the webOS bus. For details, see Creating & Using JavaScript Services.

Step 2: Configure JS Service

A 'package.json' file configures the service metadata and points to the main service file. This file is needed for packaging (related with Node.js).

A minimal package.json looks like this:

{
	"name": "com.domain.app.myservice",
	"main": "helloworld_webos_service.js"
}

A brief explanation of the above file:

  • name - Specify the name of the service. The service name must begin with the web app ID. So, if web app ID is com.domain.app, the service name must be com.domain.app.myservice.

  • main - Specify the name of the main service JavaScript file.

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

Step 3: Register JS Service

A 'services.json' file defines the services that must be registered on the Luna bus. The methods of these services can be called from other apps and services. For more information, see services.json.

A services.json file looks like this:

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

Step 4: Develop JS Service

Service implementation files provide various use cases of JS service.

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.

This loads the webos-service module. 

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

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

var service = new Service("com.domain.app.myservice");

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

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

Step 5: Package JS Service

The JS service must be packaged along with the web app that calls this service.

For details on packaging the web app, see Create Web App.

Except as noted, this content is licensed under Creative Commons Attribution 4.0 and sample code is licensed under Apache License 2.0.