This app is now out of date and not supported.
jQuery Mobile +
Traditionally when developing Sencha Touch apps on mobile and tablet devices you need to minify and repackage the Sencha source code, then recompile that with the PhoneGap framework with each platform SDK compiler and then redeploy each native app to mobile devices and emulators for testing (For Sencha apps this is done by
sencha app build -run native). For native app development this can be a slow process that you have to repeat for each code change before you can test the change on a native device or emulator.
This tool allows you to massively speed up development of your PhoneGap and Sencha Touch native apps by skipping all of these steps!
This means you can place any number of devices/emulators in front of you and instantly see the effect of your last code change one or more Android, iOS and WP8 devices! You can even serve up your source code from your local computer onto a cloud device testing labs to test your app on hundreds of different mobile devices.
We've even added integrated a SASS -> CSS compiler so you can now live edit your SASS files (
*.scss) and they will be auto compiled and resulting
app.css file auto reloaded. So you can now instantly review each styling change on multiple real devices or emulators.
The PhoneGap team recently released PhoneGap Developer App that supports live updating of source code in a PhoneGap 3.x project. The current PhoneGap Developer App is available as a download from the app stores. It's great for trying out PhoneGap with a standard set of core plugins but unfortunately it is unusable for many production projects as you're locked into a fixed set of PhoneGap plugins as deployed in their app store application. These plugins typically don't match types of plugins or plugin versions or internal customisations required by your app. You also can't use any internally developed plugins.
What you really need is a live update client and server that have identical plugins to your final mobile app. For Sencha Touch development you also need additional features and optimisations not supported by the current PhoneGap Developer App project.
To solve this, I created stlive to create, modify and serve live editable Sencha Touch or other PhoneGap based JS framework projects.
This tool allows you to instrument a new or existing mobile project to support live updating. On startup your instrumented mobile app will offer you options to either (a) run your existing fully compiled and minified native app or (b) start up a live update client that connects to an
stlive server then watches for any changes in your source code files and will notify the client to reload your project source code and restart your app whenever you change a source file.
Unlike the current PhoneGap Developer App, the live update client and server components and your final native app are now running identically configured Cordova plugins since they are all using the same PhoneGap project instance to do so. For testing purposes you can be assured that the native app and live update client will be running identical PhoneGap configurations since they are now compiled and deployed as one app and the server is dispatching the same plugin source code.
Using this tool you should be able to complete most of your development and testing using the live update client, only needing to rebuild and redeploy when your project's Cordova plugin configuration is changed.
Supported Frameworks and Versions:
This tool is based on open source technology developed by the PhoneGap team but it's been modified to support the Sencha Touch 2.x framework. It should also work for hybrid frameworks like jQuery Mobile that store their original HTML5 source in the
www subdirectory of a PhoneGap or Cordova project. The server can be run from either a Sencha Touch project folder OR the
cordova project folders and will it adapt the file paths dispatched accordingly.
It should support the following project types:
- Sencha Touch 2.x + PhoneGap 3.x + Cordova 3.x (Tested for ST 2.3.2, PG 3.4.0 on Windows 7)
- jQuery Mobile + PhoneGap 3.x (not yet tested)
- jQuery Mobile + Cordova 3.x (not yet tested)
- PhoneGap 3.x standalone (not yet tested)
- Cordova 3.x standalone (not yet tested)
Testers welcome! Please log your +ve/-ve test results as issues.
If you're already developing Sencha Touch native apps with PhoneGap you probably won't have much to install. Most existing Sencha Touch / PhoneGap developers will only need to run ...
$ [sudo] npm install -g stlive
Step 1. Configure your
stlive user settings file.
$ stlive settings show
The first time you run
stlive, it will create a copy of the
.stlive.json file that ships with the app to your local settings file
stlive merges settings from
.stlive.json files it finds in your current, ancestor and home directories. This allows you to configure settings for a group of projects by placing a copy in a parent folder contains the related project as subfolders. You can then override and version control settings for a specific project by adding an
.stlive.json file to the project subfolder.
.stlive.json files configure preferences including:
sdk- Location of your Sencha Touch SDK (e.g. "~/bin/Sencha/touch-2.3.2").
cmd: Version specific Sencha Command (e.g.
"sencha"which will get the last installed)
appDomain: Your company's domain name in reverse (e.g.
wp8platforms to add to new projects.
build.remote: Set to
trueto enable PhoneGap Build service and update
build.password. These settings are copied into new projects and then read from each project.
Step 2. Start your simulators / emulators / devices
"But hang on ... We don't even have an app yet!" ... Trust me ... You soon will.
Step 3. Create, Compile, Deploy and Run a new live editable Sencha Touch / PhoneGap app:
Open a terminal widow. For OSX, you may need to change the background color to black (or a dark color) to view colored text.
$ stlive create --run DemoApp
As this runs you will see the highlighted Sencha and Cordova commands it's using to generate your new new app based on your settings. If all is well, at the end of this process you should have a new mobile app deployed and running on your devices/emulators/simulator. If you need to fix any configuration issues and perform a rebuild you can run
stlive build --run in the new
DemoApp project subdirectory.
Step 4. Now run a live update server from your new
DemoApp project folder. The server will then display the IP Address and Port number it's listened on.
$ cd DemoApp $ stlive serve listening on 192.168.0.17:3000 Hit Control-C to stop
Step 5. Make sure the app has started on your device and select the Live Update link then key in the IP Address and Port number to connect to the server.
- You should see the server display the source files the client app is requesting.
- For Cordova platform and plugin files, it will also display the actual file path dispatched (in green).
- You can use this to identify and fix any network or project configuration issues.
- Finally you should see 'Welcome to Sencha Touch 2' displayed as the app title bar on your device or emulator.
Step 6. Now live edit the view that is displayed:
DemoApp/app/views/Main.jsand edit the Welcome message and save the file.
- You should see the app instantly reload itself from the server.
- App now displays the new Welcome message on the device.
- Connect multiple devices of mixed types (iOS, Android, WP8)
- They should all reload in response to a source file change.
- Each will load the Cordova JS files for their platform.
Step 7. Connect to the app using a remote debugger
- iOS: Follow these instructions
- Android 4.4+: Follow these instructions. Needs Chrome v32 or later on desktop computer.
Step 8. Rebuilding and Redeployment
If you've added new Sencha classes or changed class dependencies you probably only need to run:
$ sencha app refresh
This will just rebuild the
bootstrap.json files (not perform a recompile). These files are watched by
stlive serve and so you can do this during a live edit session using a separate terminal window.
If you need to rebuild and redeploy your app (e.g. after adding/removing plugins or changing the
config.xml file) you can run ...
$ stlive build --run
This is basically the same as running
sencha app build --run native but it uses the version of Sencha Command configured in your settings file which you can define as a local version controlled file in your project folder. It should stop your device app and deploy and run the recompiled app.
In the future we may add additional environment variable settings so for example could might select other SDK version and settings as well. This will make it easy to switch between projects without having to reconfigure your build environment.
Live Edit SASS style sheet files
Step 1. Install Ruby, SASS and Compass compiler as per Installation Guide instructions.
Step 2. Configure the SASS compiler in your
.stlive.json setting files.
NOTE: You must configure the full path to the compass compiler in the
Test that the SASS compiler starts and resolve any configuration issues ...
$ stlive sass [sass] Compass SASS Compiler starting [sass] >>> Compass is polling for changes. Hit Control-C to stop
Ctrl-C to Stop the SASS compiler.
Step 3. Now start the SASS compiler as part of the ST Live server ...
$ stlive serve --sass [sass] Compass SASS Compiler starting [sass] >>> Compass is polling for changes. listening on 192.168.0.17:3000 Hit Control-C to stop
Ctrl-C will now stop both the ST Live server and the SASS Compiler.
Step 4. Start your emulator or device and load your mobile app and begin Live Update editing.
Step 5. Change the base color theme for your app by adding this line to the top of
resources/sass/app.scss and save the file.
You should see the compass compiler detect the change and recompile your SASS file and then the ST Live server detect the resulting change to the
resources/css/app.css file and it reload your app with a new theme color.
For more information on theming Sencha Touch apps refer to ...
- An Introduction to Theming Sencha Touch
- Video Tutorial.
- Getting Started with Sencha Touch 2: Build a Weather Utility App: Part1, Part 2
Live Edit using a Desktop or Mobile Browser
You don't even need a mobile device to use
stlive. Just open the URL in Chrome or Safari mobile or desktop browsers. The browser will similarly auto-reload as you edit source code.
NOTE: Your app should work provided you're not calling any PhoneGap plugin APIs directly. Sencha Touch provides wrapper classes that can emulate some of the PhoneGap APIs when your app is run in a desktop browser (See devices in Sencha Touch API. Example: Ext.device.FileSystem.
Live Internet Demo or Live Testing (Cool Feature!)
Often you need to demo or test development versions of your app to friends, beta testers or customers who live outside your firewall. Normally you'd have to setup external web hosting to host your app.
--localtunnel option creates an encrypted socket connection from your
stlive server to new host name that is a random subdomain of localtunnel.me. This will expose your
stlive server server with a random subdomain that is accessible on the Internet if you know the new name.
$ stlive serve --localtunnel
You can now use this external URL for browser or device testing, or to demo or test development versions of your app to friends, testers or customers. You can even connect your app server to cloud based mobile device testing lab to test your app on hundreds of different mobile devices or use it when you visit an Open Device Lab.
SECURITY WARNING: While the node app server is generally regarded as secure, enabling this feature effectively punches a hole in your firewall. In theory it only exposes your source files as read only and the random domain name provides some additional protection however there is some small risk that a security vulnerability exists. NO penetration testing has been conducted. This feature is intended for brief demoes and testing only. Not recommended for a production service or prolonged or frequent use. As per Apache 2.0 License - No liability is accepted. Use at your own risk!
Example 1 - Create a named URL endpoint outside your firewall:
$ cd MyApp $ stlive serve --localtunnel Starting in d:\Projects\STLIVE-Sandbox\MyApp ... listening on 192.168.7.54:3000 localtunnel : https://jgwpgspbip.localtunnel.me <<<== Random Internet URL
On successful connection, the server will report its URL endpoint as: http://random.localtunnel.me . You can now key in this endpoint to the Live Update app on your mobile devices.
Example 2 - Serve Compiled Sencha Code:
localtunnel connection can be rather slow so let's compile it first and then serve the compressed JS/CSS files:
$ cd MyApp
Compile Sencha project code into
$ sencha app build native
IMPORTANT: Change to the
phonegap subdirectory of your Sencha project. The server will now load the files from
phonegap/www/ and your app will load much faster as it's now loading a single
app.js file containing your compressed version of all of your Sencha Touch class files and their dependent framework classes.
$ cd phonegap
Now show an external demo of your app using compressed code:
$ stlive serve --localtunnel Starting in d:\Projects\STLIVE-Sandbox\MyApp ... listening on 192.168.7.54:3000 localtunnel : https://jgwpgspbip.localtunnel.me
Example 3 - Use a QR Code to connect devices.
This will display a QR code of the server IP address and port so you can connect local devices:
$ stlive serve --qr
This will display QR codes on the terminal for both local IP address and the remote localtunnel.me subdomain.
$ stlive serve --localtunnel --qr
If you're demoing your app to friends, they will need to first install your compiled app on their devices but provided the plugins don't change you then just share your screen over Skype or Google+ and they can use the 2nd QR code on your screen to connect their local devices to your app and load the latest version via the localtunnel subdomain.
NOTE: Each time you restart the server the localtunnel host name will change.
Preparing for MDM or App Store deployment
AppStores or your corporate MDM server are unlikely to accept your mobile app with "live edit" instrumentation so we've made it easy to remove this prior to rebuilding for final release and add it back later so you can continue development. You also want to run
stlive remove as part of your CI build service.
To remove the live editing and rebuild and test ...
$ cd MyApp $ stlive remove $ stlive build --run
Add live editing back you can easily add it back in and redeploy ... You can also use this for an existing Sench Touch app:
$ stlive add $ stlive build --run
stlive add and
stlive remove do to my project files?
stlive create and
stlive add Perform the following:
phonegap/www/live/directory containing the live edit app.
config.xml: Changes the start up page to be
config.xml: Sets access origin to be
stlive remove Performs the following:
- Deletes the
- Deletes the
config.xml: Changes the start up page to be
config.xml: Reverts access origin to original origin
config.xml and you'll see that
stlive create and
stlive add inserts XML comments that are used to enable/disable XML elements when live editing is added or removed by adjusting these comment headers:
<!-- LIVE:ON:BEGIN --> ... elements used when live editting is ON ... <!-- LIVE:ON:END -->` <!-- LIVE:OFF:BEGIN ... elements used when live editting is OFF ... LIVE:OFF:END -->`
You can use these to manage plugin, access origin constraints or other property differences between live editting and production builds. Do not insert additional XML comments between these BEGIN/END markers or they will not work.
NOTE: Prior to version 0.2.2,
config.orig.xml files to manage these differences. These files are no longer used.
Adding/Removing Cordova/PhoneGap plugins
When adding and removing project plugins you should
$ cd phonegap $ cordova plugin add <plugin URL>
config.xml with any additional XML elements as required by your new plugin.
For Sencha Touch projects, you should update the
config.xml file in your Sencha Touch project folder. It will be copied over the
phonegap/www/config.xml file when you perform a
stlive build. Other projects like jQuery Mobile can just maintain the
Create & Build new Sencha Touch app with "Live Edit".
Create a new Sencha Touch 2.x + PhoneGap 3.x app with an embedded "live edit" client.
$ stlive create [--run] [appDomain] [appName]
$ stlive create --run au.com.mycompany MyCoolApp
--run option will deploy and run the new app on attached devices.
TIP: The domain or app name can be specified or use a default from your
.stlive.json files. If you create all your Sencha projects under a common parent folder you can create a
.stlive.json in that parent folder and setup common defaults like
appDomain for all your projects.
Builds a Sencha Touch app
sencha app build native but it uses the version of Sencha Command configured in
.stlive.json in your home directory or current/ancestor directories of your project.
$ stlive build [--run]
--run option will deploy and run the app on attached devices.
TIP: This is basically the same as running
sencha app build --run native but it uses the version of Sencha Command configured in your settings file. So you may wish to add a
.stlive.json file as part of your project, so you can auto select the right version of Sencha Command and Sencha Touch.
A future version may support settings environment variables prior to running Sencha Command so that the build process (and all the related build tools) can be customised on a per project basis. This would make it fast and easy to switch build parameters and tools just by changing projects directory and ensure that it's all version controlled.
I recommend that your project
.stlive.json files only contain project specific settings and that it inherit other settings from config files in your home or ancestor folders. When we roll out new releases of
stlive that have new features and settings you will likely avoid the need to update each of your project's config files. You should always include the "_schema" property in your config files so the app can report schema version changes.
Compile and Deploy PhoneGap app
These commands will not recompile your Sencha code, just the PhoneGap code. But it will redeploy to the device which can be quicker than doing this manually:
$ stlive run [platform ...]- Recompiles and deploys your app to devices/emulators/simulators.
Instrumenting existing mobile apps for "Live Edit"
Run these command in a Sencha Touch, PhoneGap or Cordova project folder:
$ stlive add- Add a live client to an existing Sencha Touch or PhoneGap project.
$ stlive remove- Removes the live client from a project (pre app store or production MDM deployment).
$ stlive update- Updates project live client to latest version after upgrading
Run SASS Compass Compiler
$ stlive sass
Starts the SASS Compass compiler configured in your
.stlive.json settings file.
Refer to Installation Guide for details of how to install and configure the SASS compiler.
Run "Live Edit" App Server
Run these command in a Sencha Touch, PhoneGap or Cordova project folder: Runs a live update server in your Sencha Touch or PhoneGap project folder:
$ stlive serve [--port number] [--localtunnel] [--sass]
--port number- Changes default server port number
--localtunnel- Connects your server to a random subdomain of localtunnel.me
--sass- Starts a SASS Compass compiler with the Live Edit server.
- Your Sench Touch SASS files in
resources/sass/*.scssare now also live editable.
"sass": truein your settings file to always auto start/stop this compiler as a background task.
- Your Sench Touch SASS files in
--qr- Displays a QR Code for server URL and localtunnel URL.
All these options can be preconfigured in a settings file.
$ stlive --version- Displays app version
$ stlive settings show- Shows settings merged from
.stlive.jsonfiles in $HOME, current or ancestor directories.
$ stlive settings diff- Compares settings to the default settings file
.stlive.jsonthat ships with the app.
Configuration & Command Line Options
- All configuration options can be overridded using corresponding command line options.
You'll find it helpful in speeding up creating new apps and ensuring they are consistently configured. The
.stlive.json file contains a list of all the options and their default settings. The properties are all documented with comments inside this file.
The first time you run the app, it will create a copy of the
.stlive.json file to
~/.stlive.json. You can then edit this user settings file to configure your preferences.
Setting & command line properties for
stlive create include:
- Your company's reversed domain name (com.mycompany)
- Set of PhoneGap plugins added to new projects.
- Enable/Disable PhoneGap Build service.
- PhoneGap build service user name and password
- Many other options.
Configuration properties for
stlive create include:
- Server port number
- Enable/Disable live edit reloading
- Enable/Disable external tunnel to localtunnel.me
- Set files/directories that trigger reloads for Sencha Touch projects.
- Set files/directories that trigger reloads for Cordova/PhoneGap projects.
- Enable/Disable Background SASS Compiler and configure command line and directory.
The first time you run this app it will create a ~/.stlive.json file in your home directory that allows you to override these defaults. This file is a copy of the
.stlive.json that ships with the app. At this stlive is updated with new versions you may need to maintain the settings in this file.
Navigating back to the start page and then re-selecting the Live Update link often fails to restart the Live Update client. Workaround: Stop and restart the mobile app or redeploy it using
Refer to the Issues List for more info.
A huge Thank You to the PhoneGap project team and Abobe Inc. who sponsored them; without their having open sourced the PhoneGap Developer App this app would not exist.
- Apache 2.0
Additional Sencha Projects:
Other Sencha tools I've developed ...
Sencha Ico Moon - Quickly create and install your custom icons from ICO Moon into your Sencha Touch or ExtJS project. Converts Ico Moon project files into Sencha SASS icon files. Includes Step by Step instructions.
Coming Soon: AutoLogger - Automated rule based logging API for Sencha ExtJS & Sencha Touch. Performance optimised call logging that records: class and method name, call arguments, response, exceptions, timing and nested call depth for any pattern of namespace, class or method name. Significantly reduces diagnostic logging coding effort and speeds up defect diagnosis. Entire classes or namespaces can be logged with a single line rule. Displays as collapsible regions and hyperlinked to log calls in Chrome console. Zero overheads when disabled so ideal for diagnosing faults in both development and production builds. Additional rules can select manual logging level based on class or method patterns.