Saturday, July 20, 2013

PhoneGap Android CacheCleaner Plugin

Update: Changed to be compatible with PhoneGap 3 and higher.

Here is a small blog about how to clear the cache of a PhoneGap app on the Android platform.

What does it do


It sends a command to the plugin to initiate the cache clean in Android.

PhoneGap plugin


The above is done by creating a phonegap plugin. Create the class (.java file) in the package "org.apache.cordova.plugins"

CacheCleaner.java



Create the javascript file "cachecleaner.js" and include it in your HTML AFTER the include of the phonegap/cordova javascript files.

cachecleaner.js



Add the following line to the "config.xml" file in your res folder of your Android project.

And from that point you can call the plugin in your application by using the statement below.

In your app (javascript)


The  script above can be adjusted to your liking of course.

If you have questions please let me know.

Copyright (c) 2015 Joram Teusink

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

A guide to PhoneGap 3 development for Android on Windows.

This is a guide to start developing with PhoneGap 3 for Android on a Windows machine. It has everything included, but only the basics. See the supplied URLs for more information. If you have any questions, enhancements, comments or complaints, please feel free to let me know.

Important message: I do not know the impact of the dropped support by Google of the Eclipse tools for developing for Android with PhoneGap. I do not have any plans at the moment to check if Android Studio can be used in combination with PhoneGap.

Overview, what you need

You need the following platforms / software packages:
  • Java JDK 6 or 7
  • Android SDK tools
  • Integrated Development Environment (IDE): Eclipse and Eclipse Plugin
  • Apache Ant
  • GitHub
  • Node.js
  • Cordova PhoneGap
Skip the parts below if you already have installed / configured them.

Install the tools

Java JDK 6 or 7


Make sure you download the JDK. Eclipse can build against Java 6 with Java 7, so it is fine to have only 7 on board. Officially, Android supports only Java 6, so it is not possible to compile/build against Java 7.

Just install the download as you go (next, next... finish). Make sure that you make you have the following set in your advanced system properties, environment variables.

System variables:
  • JAVA_HOME: C:\Program Files\Java\jdk1.7.0_25
    • The "1.7.0_25" part might be different, depending on which version you are installing.
  • Path: %JAVA_HOME%\bin
    • Add the line above at the end of the rest of the paths and make sure it precedes with an ;

Android SDK tools


Download the SDK (adt-bundle) from the link above and extract it to a folder you like. In this case: "D:\AndroidDev\android-sdk\". Make sure that you make you have the following set in your advanced system properties, environment variables.

System variables:
  • Path: D:\AndroidDev\android-sdk\platform-tools;D:\AndroidDev\android-sdk\tools
    • Add the line above at the end of the rest of the paths and make sure it precedes with an ;
Start the SDK manager and download the API levels you need (I did Gingerbread, Ice Cream Sandwich and Jelly Bean versions).

Eclipse and Eclipse Plugin


Eclipse is integrated in the download from the SDK tools. Extract the contents (eclipse) in this case to D:\AndroidDev\eclipse\

When you start Eclipse add the plugins like it is described in the link above. When Eclipse asks for the Android SDK, select folder "D:\AndroidDev\android-sdk\".

User variables:
  • HOME:  %USERPROFILE%

Android Studio


Important note: As of this moment it is not possible to build PhoneGap apps with Android Studio.

Apache Ant


Download the file and extract it to (in this case): "D:\AndroidDev\apache-ant"

Make sure that you make you have the following set in your advanced system properties, environment variables.

System variables:
  • ANT_HOME: D:\AndroidDev\apache-ant
  • Path: %ANT_HOME%\bin
    • Add the line above at the end of the rest of the paths and make sure it precedes with an ;

GitHub


Download and install GitHub. Start GitHub and configure anything if needed.

Node.js


Download the installer from the link above and install it the standard way (next, next.... finish).

It will automatically add it self to the path variables. For reference they are mentioned below here anyway.

User variables:
  • Path: C:\Users\Joram\AppData\Roaming\npm
    • Where as Joram is my username and should be yours.
System variables:
  • Path: C:\Program Files\nodejs\

Cordova PhoneGap

PhoneGap information (install): https://github.com/mwbrooks/phonegap-cli

You can now download PhoneGap using the Command Line Interface (CLI). Using this method you can select which platform you need, which plugins you need and then build the sources.

The commands below are done with cordova, in stead of phonegap. It is possible to them with phonegap also. Personally, I advice to use the phonegap version, in stead of cordova. Somehow using cordova the needed files are not generated properly.

Difference between Cordova CLI and PhoneGap CLI, according to the FAQ

The PhoneGap CLI is built on top of the Cordova CLI. It has all of the functionality that the Cordova CLI has. The main difference is that the PhoneGap CLI has PhoneGap Build integration. So if you don’t have the native SDK installed, you can delegate compilation to the PhoneGap Build cloud service and get app-store ready mobile apps. Both tools are completely interoperable.
The steps (execute either the Cordova or PhoneGap command, not both), for reference I list them both:
  • Download Cordova or PhoneGap, open Command Prompt (cmd), and type the command below.
    • npm install -g cordova
    • npm install -g phonegap

Create App

Create project

  • In Command Prompt (cmd) go to the folder in which you maintain your source code and type the command below. This will create a HelloWorld app (change the name if needed).
    • cordova create HelloWorld com.example.hello "Hello World"
    • phonegap create D:\HelloWorld
    • cd HelloWorld
  • Then add the Android platform with the following command in the Command Prompt (cmd).
    • cordova platform add android
    • <not needed for PhoneGap as far as I know.>
  • Want to remove the Android platform? Highly doubt that, but you'll never know.
    • cordova platform remove android

Install plugins

  • If you need any plugins (be specific!) execute the following commands in Git Shell (installed with GitHub)
    • Commands in CLI:
      • cordova plugin add <git-url>
      • phonegap local plugin add <git-url>
      • Replace <git-url> with the addresses here below (replace also the < and >)
    • Basic device information:
      • device: https://git-wip-us.apache.org/repos/asf/cordova-plugin-device.git
    • Network and battery status:
      • network-information: https://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information.git
      • battery-status: https://git-wip-us.apache.org/repos/asf/cordova-plugin-battery-status.git
    • Accelerometer, compass, and geolocation:
      • device-motion: https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-motion.git
      • device-orientation: https://git-wip-us.apache.org/repos/asf/cordova-plugin-device-orientation.git
      • geolocation: https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git
    • Camera, media capture, and media playback:
      • camera: https://git-wip-us.apache.org/repos/asf/cordova-plugin-camera.git
      • media-capture: https://git-wip-us.apache.org/repos/asf/cordova-plugin-media-capture.git
      • media: https://git-wip-us.apache.org/repos/asf/cordova-plugin-media.git
    • Access files on device or network:
      • file: https://git-wip-us.apache.org/repos/asf/cordova-plugin-file.git
      • file-transfer: https://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer.git
    • Notifications via dialog box or vibration:
      • dialogs: https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git
      • vibration: https://git-wip-us.apache.org/repos/asf/cordova-plugin-vibration.git
    • Contacts:
      • contacts: https://git-wip-us.apache.org/repos/asf/cordova-plugin-contacts.git
    • Globalization:
      • globalization: https://git-wip-us.apache.org/repos/asf/cordova-plugin-globalization.git
    • Splash Screen:
      • splashscreen: https://git-wip-us.apache.org/repos/asf/cordova-plugin-splashscreen.git
    • In-app browser:
      • inappbrowser: https://git-wip-us.apache.org/repos/asf/cordova-plugin-inappbrowser.git
    • Debug console:
      • console: https://git-wip-us.apache.org/repos/asf/cordova-plugin-console.git
    • Dialogs:
      • dialogs: https://git-wip-us.apache.org/repos/asf/cordova-plugin-dialogs.git
  • If you want to see which plugins have been added, execute the following commands.
    • cordova plugin list
    • phonegap local plugin list

Removing plugins

  • If you need to remove any plugins (be specific!) execute the following commands in Git Shell (installed with GitHub)
    • Commands in CLI:
      • cordova plugin remove org.apache.cordova.<plugin name>
      • phonegap local plugin remove org.apache.cordova.<plugin name>
      • Replace <plugin name> with a name above (replace also the < and >)

Build and compile the app

  • Make the build with the following command (in Command Prompt).
    • cordova build android (it does a prepare and compile command in one)
    • phonegap local build android
  • Then you can run it (or add it to Eclipse or Android Studio).
    • cordova emulate android
    • phonegap local run android
All the sources should be ready now and you can start using PhoneGap and building your app.

Debug Console

More information about debugging webapps on Android: https://developer.android.com/guide/webapps/debugging.html

Send information to the console

In your JavaScript use one of the following commands below.
  • console.log(String)
  • console.info(String)
  • console.warn(String)
  • console.error(String)

Debug console

  • To see the logcat in a Command Prompt (cmd), execute the following command.
    • adb logcat
  • If you want to have (way) more options, make use of eclipse. Execute the following command.
    • monitor

Debugging through Chrome

You can also debug your PhoneGap application through the Chrome Developer tools. This also includes live editing of code and see instant results of that. Much easier tweaking and improving your code!

Use this example below to adjust your project to support Chrome remote debugging.

Updating

Cordova PhoneGap


Updating to a newer PhoneGap version is done in a couple of steps. See below. Also in this part, for the moment, go for the phonegap-cli commands.
  • Check your current version
    • cordova -v
    • phonegap -v
  • Update Cordova or PhoneGap, open Command Prompt (cmd), and type the command below.
    • npm update -g cordova
    • npm update -g phonegap

Update your project

Create new project...

  • Create a new project.
  • Add all the necessary plugins.
  • Add your assets content (HTML, CSS, JavaScript and other files, basically your entire web-app).
  • Make the new build with the following command.
    • cordova build android (it does a prepare and compile command in one)
    • phonegap local build android
  • Then you can run it (or add it to Eclipse or Android Studio).
    • cordova emulate android
  • cordova emulate android
    • phonegap local run android

Update current project...

  • cordova platform update android
  • phonegap platform update android

Easy CLI commands for PhoneGap and Cordova


More...

End-word

I have to say, it is not as easy as PhoneGap 2.9.0 and below, but perhaps the speed of your app increases by this way. The supplied documentation with PhoneGap is, in my honest opinion, bit too short to get you started quickly. I have spent two and a half hours just to go through all the steps (reading, tools and configuration) and make a HelloWorld app. Once you know the drill it is not difficult though.

Sources

Other informational sources and blogs about PhoneGap 3 installment and CLI
Thank you for reading my blog!