Desktop Packager 1.1 Sencha Docs

Getting Started With Sencha Desktop Packager

Contents

  1. System Requirements
  2. Installation
  3. Registration
  4. Packaging a Simple App
  5. Next steps

The primary goal of Sencha Desktop Packager is to wrap an application written in HTML, CSS, and JavaScript with a native shell so it will launch, look, and behave like a normal desktop application. The converted application will run directly on the operating system without a web browser. This permits easy deployment and installation. Additional APIs from the native shell run-time enables you to add an application menu, invoke file dialogs, and create many user interaction features that usually are not available if the application runs in a web browser.

This guide describes the system requirements for Sencha Desktop Packager, how to install it, and how to use it to package an application.

System Requirements

Sencha Desktop Packager is available for these platforms:

  • Microsoft Windows XP or newer (32-bit and 64-bit)
  • Apple Mac OS X Snow Leopard or newer (32-bit and 64-bit)
  • Ubuntu Linux 10.04 or newer, other equivalent Linux distributions (32-bit and 64-bit)

Installation

The process to install Sencha Desktop Packager is the same for all platforms:

  1. Download the Sencha Desktop Packager .zip file.
  2. Create a directory, giving it a name without spaces or special characters, and unzip Sencha Desktop Packager to the new directory.
  3. Add the directory to the PATH environment variable.

The installation directory should now have the following files:

  • examples/ directory for all the included example code
  • docs/ directory for the documentation
  • ionpackage, the main packaging command-line tool (ionpackage.exe on Windows)
  • ionruntime.dat, the packaging library

Registration

You are required to register Sencha Desktop Packager and obtain a license before you can use it. The first time you run ionpackage you will be prompted to provide the information required.

See the Licensing Guide for details.

Running For the First Time

After installation, run the command ionpackage in the Windows Command Prompt.

Running the command should display the program information, as shown below. Here's the program information on a Windows system:

And here's the program information on an OS X system:

And here's how it looks on Linux:

Packaging a Simple App

Converting a web app into a desktop app involves a few simple steps. After installing Sencha Desktop Packager, create a manifest file using JSON that describes the application. Here's an example of a simple manifest file called helloconfig.json:

   {
       "applicationName": "Hello World",
       "applicationIconPaths": ["HelloWorld.ico", "HelloWorld.icns"],
       "versionString": "1.0",
       "outputPath": "HelloWorld",
       "webAppPath": "hello/",
       "settings": {
           "mainWindow": {
               "autoShow": true
           }
       }
   }

The key-value pairs used in this example are:

  • applicationName denotes the name of the application, which will be visible to the user.
  • applicationIconPaths denotes an array of paths to the application's default icon files. These must be an .ico or an .icns icon file for Windows and Mac OS X respectively. If any of the provided paths are not absolute, they will be relative to your configuration file.
  • versionString sets the version number of the application.
  • outputPath points to a location where the application will be generated.
  • webAppPath points to the source directory of the application.
  • settings.mainWindow.autoShow Ensures that the application window is displayed on the screen.

outputPath and webAppPath can be relative or absolute. If relative they will be interpreted relative to the location of the manifest file.

autoShow is set to true in this simple example to make the window visible without writing any JavaScript to explicitly show it. This is not the default behavior. See mainWindow in the Advanced Configuration Guide for details on how and when to use autoShow.

The Quick Reference Guide contains documentation all of the key-value pairs that can be specified in the manifest file.

Next let's look at the content of a simple Hello, world! HTML application. The app is stored in a file called index.html under the hello/ subdirectory specified in the above example. Here's what the code looks like:

    <html>
    <head>
        <title>Hello</title>
    </head>
    <body>
        <p>Hello, world!</p>
    </body>
    </html>

Now, using the manifest file and the HTML application, we can create the desktop application with Sencha Desktop Packager using the following command:

> ionpackage helloconfig.json

Note: If this is the very first time you run ionpackage, you will be prompted to register the product. See the Licensing Guide for details.

Packaging a simple app like our Hello World example will only take a few seconds. If the directory specified by outputPath (./HelloWorld in this example) does not exist, ionpackage will create it. If it does exist, ionpackage will prompt asking whether or not to overwrite it. Be careful though, because opting to overwrite will delete any previous contents of outputPath.

...
Output path already exists. Overwrite (Y/N)? y
Output path will be overwritten.
...

When ionpackage finishes running, the newly packaged app will be in outputPath.

If you open the HelloApp directory in Windows, you'll see the following:

Note that the main application created by Sencha Desktop Packager is HelloWorld.exe. Double-click this file to launch the application.

Here's the HelloApp directory open in OS X:

Here's the application running in Windows:

And here's our Hello, World! app running in OS X:

Next steps

Sencha Desktop Packager documentation includes the following, and we recommend you look at them in this order: