Desktop Packager Sencha Docs

Advanced Configuration of Run-Time Behaviors

This guide describes various ways to configure the run-time behavior of your packaged applications.

Configuration settings

Run-time application behavior can be configured with additional settings in the configuration file that are applied when the application is packaged. As an illustration, let's look at the following example:

   {
        "applicationName": "HelloWorld",
        "applicationIconPaths": ["HelloWorld.ico", "HelloWorld.icns"],
        "versionString": "1.0",
        "outputPath": "HelloApp",
        "webAppPath": "hello/",
        "settings": {
            "remoteDebuggingPort": 9100,
            "security": {
                "allowCrossSite": true,
                "allowFileSystemAccess": true,
                "allowJavaScriptClipboardAccess": true
            },
            "mainWindow": {
                "autoShow": true
            }
        }
   }

settings

The additional group settings can be used to change the run-time behavior in different ways.

  • remoteDebuggingPort allows debugging of the application from another browser (See Remote Debugging section below)
  • security controls the security aspects of the application.
  • mainWindow alters how the application main window has to be displayed.

security

The security subgroup accepts the following options:

  • allowCrossSite -- By default the application cannot access any remote resources, e.g. from an HTTP server. When allowCrossSite is set to true, such requests will be permitted. This is useful when using XMLHttpRequest for loading remote data.

  • allowFileSystemAccess -- By default the application cannot access local resources located on the file system, i.e. file:// URLs. When allowFileSystemAccess is set to true, such requests will be permitted. This is useful when using XMLHttpRequest to load local data.

  • allowJavaScriptClipboardAccess -- By default the application may not execute the HTML editing commands "Cut", "Copy" and "Paste", e.g. document.execCommand('Paste'); When allowJavaScriptClipboardAccess is set to true, your application will be permitted access to the clipboard by enabling these editing commands.

mainWindow

For the mainWindow subgroup, autoShow can be used to automatically show the main window when the application is launched. If this value is set to false, the main window will remain hidden until Ion.ui.mainWindow.show() is invoked.

The default value for autoShow is false, allowing the application to perform any user-interface initialization (sizing and placement, for example) prior to the application window becoming visible. Once the user-interface is ready togo, the application should call Ion.ui.mainWindow.show(). This prevents the application's users from seeing the window while it is being initialized.

When autoShow is set to true, the application window will be made visible as soon as it is created. There is no guarentee of what, if any, application code will execute prior to the window being displayed. If you have code that needs to run prior to the window being displayed, set autoShow to false and call Ion.ui.mainWindow.show() explicitly.

Remote debugging

Since an application packaged with Sencha Desktop Packager does not in a web browser, debugging the application is not possible using standard web debugging techniques. While in development, the remote debugging feature can be enabled by modifying the application configuration. This is possible thanks to WebKit support for remote debugging.

As an example, if we want to debug the AreaChart example, its areachartconfig.json needs to be edited to enable remote debugging:

    {
        "organizationName": "Sencha",
        "applicationName": "Area Chart",
        "versionString": "1.0",
        "outputPath": "AreaChart",
        "webAppPath": "src/",
        "settings": {
            "remoteDebuggingPort": 9100
        }
    }

The key remoteDebuggingPort is added to the settings configuration, which specifies the debug port and enables the remote debugger.

After the application is repackaged again, launch it as usual. Open a WebKit-based web browser such as Google Chrome and Apple Safari and navigate to http://localhost:9100. The port number is the same as the one specified in the remoteDebuggingPort configuration. Choose AreaChart from the list and now the browser should display the familiar Chrome Developer Tools or Safari Web Inspector debugging the example.

Note: Remote debugging is always disabled by default. It is activated only by explicity setting the port in the configuration file. For security reasons, do not deploy an application with remote debugging enabled since anyone can get alter the behavior of the application and get access to the application code. We suggest never checking in to your source control a application configuration file that enables remote debugging and only enabling it during active development.