Using Native APIs in Sencha Desktop PackagerSencha Desktop Packager lets you to take an existing web application and deploy it as a desktop application. You can also integrate with the native platform by using additional APIs to create menus, show file dialogs, and access the file system. In this blog post, we’ll show a simple text editor to demonstrate the use of these native APIs.

If you’re new to Sencha Desktop Packager, watch the 3-minute walkthrough. If you don’t have Desktop Packager yet, download the 30-day trial edition, available for Windows, OS X, and Linux. At any time, you can always refer to the online documentation.

Basic Structure

A simple text editor is mainly comprised of a text field. This can be accomplished with the following simple index.html:

/**
* GeSHi (C) 2004 – 2007 Nigel McNie, 2007 – 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
*/
.html4strict .imp font-weight: bold; color: red;
.html4strict .kw2 color: #000000; font-weight: bold;
.html4strict .kw3 color: #000066;
.html4strict .es0 color: #000099; font-weight: bold;
.html4strict .br0 color: #66cc66;
.html4strict .sy0 color: #66cc66;
.html4strict .st0 color: #ff0000;
.html4strict .nu0 color: #cc66cc;
.html4strict .sc-1 color: #808080; font-style: italic;
.html4strict .sc0 color: #00bbdd;
.html4strict .sc1 color: #ddbb00;
.html4strict .sc2 color: #009900;
.html4strict span.xtra display:block;

To package it, we need a corresponding manifest file which looks like the following:

/**
* GeSHi (C) 2004 – 2007 Nigel McNie, 2007 – 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
*/
.javascript .imp font-weight: bold; color: red;
.javascript .kw1 color: #000066; font-weight: bold;
.javascript .kw2 color: #003366; font-weight: bold;
.javascript .kw3 color: #000066;
.javascript .co1 color: #006600; font-style: italic;
.javascript .co2 color: #009966; font-style: italic;
.javascript .coMULTI color: #006600; font-style: italic;
.javascript .es0 color: #000099; font-weight: bold;
.javascript .br0 color: #009900;
.javascript .sy0 color: #339933;
.javascript .st0 color: #3366CC;
.javascript .nu0 color: #CC0000;
.javascript .me1 color: #660066;
.javascript span.xtra display:block;

Assuming that the manifest file is called texteditor.json and index.html is placed under src/ subdirectory, building it as a desktop application is as easy as running:

/**
* GeSHi (C) 2004 – 2007 Nigel McNie, 2007 – 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
*/
.bash .imp font-weight: bold; color: red;
.bash .kw1 color: #000000; font-weight: bold;
.bash .kw2 color: #c20cb9; font-weight: bold;
.bash .kw3 color: #7a0874; font-weight: bold;
.bash .co0 color: #666666; font-style: italic;
.bash .co1 color: #800000;
.bash .co2 color: #cc0000; font-style: italic;
.bash .co3 color: #000000; font-weight: bold;
.bash .es1 color: #000099; font-weight: bold;
.bash .es2 color: #007800;
.bash .es3 color: #007800;
.bash .es4 color: #007800;
.bash .es5 color: #780078;
.bash .es_h color: #000099; font-weight: bold;
.bash .br0 color: #7a0874; font-weight: bold;
.bash .sy0 color: #000000; font-weight: bold;
.bash .st0 color: #ff0000;
.bash .st_h color: #ff0000;
.bash .nu0 color: #000000;
.bash .re0 color: #007800;
.bash .re1 color: #007800;
.bash .re2 color: #007800;
.bash .re4 color: #007800;
.bash .re5 color: #660033;
.bash span.xtra display:block;

The application is created under TextEditor/ subdirectory. Launch it and you will see a window with an empty text field, just as you would expect in a text editor.

Adding Native Menu

Obviously, a text editor is not very useful if the user cannot open an existing file. The first step towards this is to build an interface which allows the user to perform some actions. We will start by adding a menu bar and a File menu. This extra logic will be implemented in a JavaScript file, ui.js, which should be placed in the same src/ subdirectory. Here, we use Ion.ui.MenuBar (of the main window) to construct the menu bar and populate it.

/**
* GeSHi (C) 2004 – 2007 Nigel McNie, 2007 – 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
*/
.javascript .imp font-weight: bold; color: red;
.javascript .kw1 color: #000066; font-weight: bold;
.javascript .kw2 color: #003366; font-weight: bold;
.javascript .kw3 color: #000066;
.javascript .co1 color: #006600; font-style: italic;
.javascript .co2 color: #009966; font-style: italic;
.javascript .coMULTI color: #006600; font-style: italic;
.javascript .es0 color: #000099; font-weight: bold;
.javascript .br0 color: #009900;
.javascript .sy0 color: #339933;
.javascript .st0 color: #3366CC;
.javascript .nu0 color: #CC0000;
.javascript .me1 color: #660066;
.javascript span.xtra display:block;

This particular function, createUI, needs to be invoked from the main index.html. For this example, it is enough to call that from the document’s onLoad handler. Of course, do not forget to add a new script tag to include ui.js.

If you now repackage the application by running ionpackage texteditor.json again, the main window will have a menu bar. Clicking on the File menu will show its items, each with its corresponding shortcut as we specified in our createUI() function. Pretty straightforward, isn’t it?

Using Native APIs with Sencha Desktop Packager

Using File Dialogs

Unfortunately, the new menu items are still useless since they don’t perform any meaningful action. This can be changed by having a real handler for both menu items. We need to tweak our JavaScript logic to look like this:

/**
* GeSHi (C) 2004 – 2007 Nigel McNie, 2007 – 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
*/
.javascript .imp font-weight: bold; color: red;
.javascript .kw1 color: #000066; font-weight: bold;
.javascript .kw2 color: #003366; font-weight: bold;
.javascript .kw3 color: #000066;
.javascript .co1 color: #006600; font-style: italic;
.javascript .co2 color: #009966; font-style: italic;
.javascript .coMULTI color: #006600; font-style: italic;
.javascript .es0 color: #000099; font-weight: bold;
.javascript .br0 color: #009900;
.javascript .sy0 color: #339933;
.javascript .st0 color: #3366CC;
.javascript .nu0 color: #CC0000;
.javascript .me1 color: #660066;
.javascript span.xtra display:block;

Instead of an empty function, now pass handleOpen and handleSave for the Open and Save menu items, respectively. As the first step, we can invoke the native file dialog whenever the user wants to open a file. This is implemented via Ion.ui.browseFiles as follows (the same can be done for the Save menu item, it is left as an exercise for the reader).

/**
* GeSHi (C) 2004 – 2007 Nigel McNie, 2007 – 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
*/
.javascript .imp font-weight: bold; color: red;
.javascript .kw1 color: #000066; font-weight: bold;
.javascript .kw2 color: #003366; font-weight: bold;
.javascript .kw3 color: #000066;
.javascript .co1 color: #006600; font-style: italic;
.javascript .co2 color: #009966; font-style: italic;
.javascript .coMULTI color: #006600; font-style: italic;
.javascript .es0 color: #000099; font-weight: bold;
.javascript .br0 color: #009900;
.javascript .sy0 color: #339933;
.javascript .st0 color: #3366CC;
.javascript .nu0 color: #CC0000;
.javascript .me1 color: #660066;
.javascript span.xtra display:block;

When the Open menu item is clicked, a file dialog pops up to allow the user to choose a file, as illustrated in the following screenshot.

Using Native APIs with Sencha Desktop Packager

Accessing Files

A file dialog in and of itself does not do much. While the application now knows which file the user selected, it still needs to do something with it. Thanks to the Desktop Packager file system API, we can add some more logic to read the file contents. For this particular case, we use Ion.io.readFile.

/**
* GeSHi (C) 2004 – 2007 Nigel McNie, 2007 – 2008 Benny Baumann
* (http://qbnz.com/highlighter/ and http://geshi.org/)
*/
.javascript .imp font-weight: bold; color: red;
.javascript .kw1 color: #000066; font-weight: bold;
.javascript .kw2 color: #003366; font-weight: bold;
.javascript .kw3 color: #000066;
.javascript .co1 color: #006600; font-style: italic;
.javascript .co2 color: #009966; font-style: italic;
.javascript .coMULTI color: #006600; font-style: italic;
.javascript .es0 color: #000099; font-weight: bold;
.javascript .br0 color: #009900;
.javascript .sy0 color: #339933;
.javascript .st0 color: #3366CC;
.javascript .nu0 color: #CC0000;
.javascript .me1 color: #660066;
.javascript span.xtra display:block;

With the above new implementation of handleOpen, our little text editor finally has a fully functional user interface to load the contents from a text file selected by the user via the open file dialog.

Last but not least, if you need to troubleshoot your packaged app, take advantage of the Desktop Packager remote debugging feature. Having a console in the debugger allows you to analyze the application logic as well as play with the native APIs.

Happy packaging!

.right, .alignright float: right; margin: 0 0 10px 10px;
.left, .alignleft float: left; margin: 0 10px 10px 0;

View original article – 

Using Native APIs in Sencha Desktop Packager