Creating headless WebWorks apps
- 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:
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.
- 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
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:
- On the command line, run the following command to create a
WebWorks project with a headless
webworks create-headless <path>
webworks create-headless c:\webworks-apps\MyApp
Check the table below for parameter details:
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
- There are some additional folders added to the project folder structure.
- The config.xml file includes some nonstandard entries.
A WebWorks 2.0 project with a headless service has the following differences in the project folder structure:
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.
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:
- Open the Momentics IDE for BlackBerry.
- Select Select panel. . The IDE opens the Import wizard and displays the
- In the Select panel, expand General, select Existing
Projects into Workspace, and then click Next. The IDE displays the Import
- In the Import Projects panel, next to the Select root directory field, click the Browse… button and navigate to your project's HeadlessService folder.
- In the Projects list, make sure that the HeadlessService project is selected.
- Make sure that the Copy projects into workspace check box is not selected.
- Click Finish to import the selected project into the IDE.
Last modified: 2014-10-09