Creating headless WebWorks apps

As of the BlackBerry 10 WebWorks SDK version 2.1.0, you can create headless WebWorks apps. A headless WebWorks app is comprised of two component apps that are built together into a single application package:
  • web app: This component includes the UI, and is just like any other WebWorks app. It is developed using standard web technologies such as HTML, CSS, and JavaScript, and requires you to add the appropriate plugins and modify configuration settings as necessary. Once you have created the headless WebWorks project, the process to develop this component is the same as for any WebWorks app.
  • headless service: This component is a native app developed in C/C++ that is designed to run in the background on the device. It has no UI, and the user can't invoke or interact with it in any way. Typically, the headless service starts as a result of a defined trigger, performs some function (for example, generating a notification), and then stops, until it is triggered again. By using the _sys_headless_nostop permission, you can also create a headless service that runs continuously.

Although the two components are packaged together, they are designed to operate independently on the device. That is, the headless component doesn't require the web component of the app to be running in order to respond to a trigger.

The following diagram provides an overview of the headless app process:

Diagram showing the headless app structure.

For a thorough discussion of headless apps, see Headless apps in the BlackBerry 10 Native SDK documentation.

To understand how headless apps work, let's look at the template that is provided when you create a headless app using the BlackBerry 10 WebWorks SDK. When you create a headless app in WebWorks using the create-headless command, you receive a fully functional app that you can immediately build and deploy to a device or simulator. By deafult, the headless component of the app is configured with the bb.action.system.STARTED trigger, which triggers it to run as soon as it is installed on the device. Once triggered, the headless component immediately sends a notification to the BlackBerry Hub, which the user can click to invoke the web component of the app. The web component provides a button that resets the headless component of the app, causing it to send another notification.

The headless service supports various triggers; a trigger can be the receipt of pushed content or a port-directed SMS message, a change in location information, or some other event. For a full list of triggers, see Triggers in the BlackBerry 10 Native SDK documentation. The behavior of the headless component upon being triggered similarly depends on the requirements of your app.

Additional system requirements

The headless component that's provided when you create your WebWorks project is a native C/C++ application. It includes both the binary and the complete source code for the headless portion of the app.

The source code provides the complete project, which can be imported into the Momentics IDE for BlackBerry.

To modify and recompile the code, download and install the BlackBerry 10 Native SDK.

Creating a headless WebWorks project

You create headless apps from the command line using the create-headless command. You can't create a headless app using the SDK web tool.

When you create a headless app, the SDK creates a project containing the following:
  • All the basic web resources required for the web component
  • The compiled binary of the headless component (located in the www/assets folder)
  • The C/C++ project for the headless component (located in the HeadlessService folder), which you can import into the Momentics IDE

    When importing the project into the IDE, we recommend that you don't select the Copy into workspace option. The MakeFile included in the project automatically places the newly built binary into the www/assets folder of the WebWorks project. Copying the project into the workspace prevents the binary from being placed in the correct folder.

To create a WebWorks project with a headless service:

  1. On the command line, run the following command to create a WebWorks project with a headless service:
    webworks create-headless <path> 
For example, the following command creates a headless project in the c:\webworks-apps\myapp folder:
webworks create-headless c:\webworks-apps\MyApp

Check the table below for parameter details:

Parameter Description


The home folder for your project. The tool creates this folder for you and does not overwrite an existing folder; if you specify an existing folder, the project is not created.

Differences in a headless WebWorks app

A headless app project has two major differences from a regular WebWorks project:
  • There are some additional folders added to the project folder structure.
  • The config.xml file includes some nonstandard entries.

Folder structure

A WebWorks 2.0 project with a headless service has the following differences in the project folder structure:

Folder Description


The www folder includes an assets subfolder. The assets folder contains the compiled binary of the headless service component of your app.


The HeadlessService folder contains the complete C/C++ project for the headless portion of the app. You can import the project into the Momentics IDE for BlackBerry to modify the default headless app and add custom functionality.

For information on how to import the headless project, see Import your headless project into the Momentics IDE.

Changes to the config.xml file for headless apps

The config.xml file provided for a headless WebWorks app contains a <config-file> element. This element contains entries that are injected into the the bar-descriptor.xml file for the headless service component.

In a native app, the bar-descriptor.xml file specifies the parameters for identifying, installing, and launching the app on BlackBerry 10 OS. More importantly, the bar-descriptor.xml file defines the triggers that launch the headless service, and defines the elements required to launch and run both the WebWorks and headless components.

If you need to change bar-descriptor.xml values for your headless WebWorks app, you must edit those same values within the <config-file> element of config.xml file.

Modifying the template components

Once you've created the headless WebWorks project, you can modify the template web and headless components of the app.

Modifying the web component of a headless app is no different than creating and modifying a regular WebWorks app. You add plugins, modify configuration settings, set permissions, and so on.

To modify the headless component, you need some information about triggers, coding in C/C++, and the Momentics IDE. If you modify the source code, you also need to recompile the source code. As long as you import the project without copying it into your workspace, the MakeFile compiles and replaces the default binary in the www/assets folder with the newly built binary. You can find helpful information in the BlackBerry 10 Native SDK documentation. Before you start exploring, however, there is some information unique to headless WebWorks apps that you should know.

Defining triggers

For information on defining triggers for your headless service, see the Triggers section in the BlackBerry 10 Native SDK documentation.

While the syntax and structure are identical, remember that in a headless WebWorks app, the triggers are specified within the <config-file> element of the config.xml file, not in a bar-descriptor.xml file.

Modifying the headless component source code

The Creating a headless app section of the BlackBerry 10 Native SDK documentation provides a complete tutorial describing how to create a native headless app. You might find this information helpful as you modify your app.

In the template app, the service.cpp and service.hpp files correspond to the application.cpp and application.hpp files, respectively, that are described in the tutorial. Also, this tutorial describes how to create the UI component of the app; your headless WebWorks template already provides the UI portion, so you can disregard this information.

Import your headless project into the Momentics IDE

To customize the template headless app that was provided when you created your headless WebWorks project, you must first import the project into the Momentics IDE for BlackBerry.

When you import the project, do not copy it into your workspace. By not copying it, you make sure that the source for both the headless portion and the web portion are kept together. More importantly, when you compile the source code, the project's MakeFile automatically places the compiled binary into the www/assets folder. The binary file must be placed in this folder so that both the web and headless portions of the app are built together.

Once the project has been imported, you can modify the code and recompile it to generate the binary file for the headless service.

To import your headless project:

  1. Open the Momentics IDE for BlackBerry.
  2. Select File > Import. The IDE opens the Import wizard and displays the Select panel.
  3. In the Select panel, expand General, select Existing Projects into Workspace, and then click Next. The IDE displays the Import Projects panel.

    Import existing project

  4. In the Import Projects panel, next to the Select root directory field, click the Browse… button and navigate to your project's HeadlessService folder.
  5. In the Projects list, make sure that the HeadlessService project is selected.
  6. Make sure that the Copy projects into workspace check box is not selected.
  7. Click Finish to import the selected project into the IDE.

Last modified: 2014-10-09

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus