Developing External QML Apps

External QML apps are 3rd party QML apps that must be installed on the webOS target device. External QML apps can be created and deployed using the Command-Line Interface (CLI) tool that are provided by the webOS Open Source Edition (OSE) SDK.

This page describes the steps to develop an external QML app using CLI. For detailed information on the commands used in this tutorial, see CLI commands.

Developing an external QML app requires the following steps:

• Step 1: Create a QML App
• Step 2: Implement the QML App
• Step 3: Configure the QML App
• Step 4: Package the QML App
• Step 5: Install the QML App
• Step 6: Launch the QML App

Step 1: Create a QML App

Start by creating a QML app using one of the available QML app templates. These templates provide a starting point for developing the QML app.

To create a basic QML app, execute the following command:

$ ares-generate -t qmlapp sampleApp

In the above command:

• qmlapp is the name of template that creates a basic QML app.
• sampleApp is the QML app directory which is created in the current directory.

The following shows an example directory structure of the sample app.

sampleApp/
├── appinfo.json
├── icon.png
└── main.qml

The QML app directory (sampleApp) has the following files:

If you already have an existing QML app that you want to deploy on a webOS OSE device, you must add the appinfo.json file to the app root directory. To create this file, enter the following CLI command:

$ ares-generate -t qmlappinfo sampleApp

Step 2: Implement the QML App

Design and implement the source code for the QML app.

By default, the basic QML app template includes some basic code that prints a “Hello, QML Application!!” message. Therefore, if you want to create a demo QML app to test this process, you can skip this step and proceed.

If you want to use a webOS service in the QML app, check the information provided in the Implement the QML App section in Developing Built-in QML Apps.

Step 3: Configure the QML App

The details or metadata of the QML app must be specified in the appinfo.json file. This file is automatically created when you create a QML app on CLI using a template. For details, see appinfo.json.

CLI provides the appinfo.json file template as below.

{
    "id": "com.domain.app",
    "version": "1.0.0",
    "vendor": "My Company",
    "type": "qml",
    "main": "main.qml",
    "title": "new app",
    "icon": "icon.png",
    "requiredPermissions" : ["time.query", "applications.operation"]
}

Step 4: Package the QML App

After implementing and configuring the QML app, it must be packaged as an IPK file. Make sure the appinfo.json file is available, because it is required when packaging a QML app for webOS OSE.

To package the QML app, use the ares-package command. The packaged file is generated in the current directory.

$ ares-package sampleApp

In the above command, sampleApp is the QML app directory. You can use an absolute or relative path. Also you can package the app with a service. For more details on using ares-package, see ares-package.

Step 5: Install the QML App

To install the QML app on the target device, execute the following command:

$ ares-install --device <TARGET_DEVICE> ./com.domain.app_1.0.0_all.ipk

In the above command:

• <TARGET_DEVICE> is the name of the target device.
• ./com.domain.app_1.0.0_all.ipk is the name of the IPK file that is generated after packaging the app in the previous step.

If the installation is successful, a Success message will appear.

To verify the installation, check if the QML app ID (in this case, com.domain.app) is available in the output of the following command:

$ ares-install --device <TARGET_DEVICE> --list

To remove the app from the device, use the ares-install command as follows:

$ ares-install --device <TARGET_DEVICE> --remove com.domain.app

Step 6: Launch the QML App

To launch the QML app on the target device, execute the following command:

$ ares-launch --device <TARGET_DEVICE> com.domain.app

In the above command:

• <TARGET_DEVICE> is the name of the target device. This is the same device on which the app was installed in the previous step.
• com.domain.app is the app ID that is available after installing the app.

After executing the above command, check the target device to see if the app is running.

To close the app, use the ares-launch command as follows:

$ ares-launch --device <TARGET_DEVICE> --close com.domain.app