Part 1: Write the Native Java Interface
- Open your favorite editor and define a class called Calendar.java that extends the CordovaPluginclass. This file should be created in a src folder within your custom plugin root (for example under
Add the following new static variable to your Calendar class. The result looks as follows:
- Still in Calendar.java, add the following execute function signature. This method is inherited from the CordovaPlugin class so we’ll add the @Override annotation as well:
- Before going further we should add the necessary imports for the Java classes used so far and add a package name to Calendar.java
***Updated for PhoneGap 3.0
- Within the execute() method, add code to check the action passed in and add a calendar entry via native code using the Intent and Activity classes Android provides. Intent will set up the type of activity and some other data (our custom parameters) and then get the Activity object to start a new Activity based on the Intent data. See the links on Activity and Intent classes within this paragraph for details.
For more details on extras that can be used with the Android calendar intent, see this tutorial.
- Lastly, add the following imports for the Activity and Intent android classes needed for adding our native calendar entry to the top of Calendar.java just below the
import org.json.JSONException;line added previously:
- Now save your file and move on to Part 2.
Open your editor and create a new file called calendar.js. This file should be created within a www folder. The www and the src folders should be at the same level within your custom plugin root (~/CalendarPlugin/www).
In calendar.js, code a new calendar variable with a function named createEvent which will take the required custom parameters and callback functions needed for creating our calendar entry on the native side.
We then add the code to the createEvent function to make the required call to cordova.exec() passing the following:
- Success Callback Function
- Error Callback Function
- Service Name
- Action Name
- Array of arguments
The calendar.js file should look like the following once the cordova.exec() code is added:
Lastly export your calendar variable so it’s available for use with the following line of code:
Failing to do the export above will result in an error such as the following one below in the console (such as when running adb logcat), since the calendar object is not available.
Uncaught TypeError: Object #<Object> has no method 'createEvent' at file:///android_asset/www/js/index.js:62
Your final calendar.js file should look like the following:
***Updated for PhoneGap 3.0
Part 3: Configure your Plugin to be installable with the PhoneGap CLI
To use the PhoneGap CLI to install your plugin, you must create it according to the plugin specification. Here are the steps to take:
- Create a file named plugin.xml file within your custom plugin root (~/CalendarPlugin/) with the following:
- Check your custom plugin into a git repository. The final structure should match what is found here in my github account.
Part 4: Implement it!
Start with a basic PhoneGap starter project using the PhoneGap Command Line Interface. It’s a quick way to create a project that could later have more platforms added to it besides android and also gives you an easy way to upload your project from the command line to PhoneGap Build if desired.
Once you have the PhoneGap CLI installed, run the following command:
$ phonegap create MyPhoneGapApp
This will create a base PhoneGap 3.0 project in a folder MyPhoneGapApp within the current directory. TheMyPhoneGapApp folder will contain a sample www folder in the root but no supported platforms have been added as of yet.
Next run the following commands:
$ cd MyPhoneGapApp
$ phonegap local run android
The first ensures we’re within the root of the project directory just created. The phonegap local run android command will actually add the android platform to the project, then build and automatically deploy it to your connected Android device or emulator.
You should see the following messages when your environment is configured successfully as well as have a base PhoneGap application running on your Android device or emulator at this point.:
phonegap detecting Android SDK environment...
phonegap using the local environment
phonegap adding the Android platform...
phonegap compiling Android...
phonegap successfully compiled Android app
phonegap installing app onto Android device and falling back on emulator
***Updated for PhoneGap 3.0
Add the Plugin to your App
- Run the following command to install the CalendarPlugin by pointing to your git repository or github location such as mine in the following:
$ phonegap local plugin add https://github.com/hollyschinsky/CalendarPlugin
Note: Ensure you see the message:
[phonegap] successfully added the plugin
- Now open the newly created project you created with the CLI command in your favorite editor.
- Open the www/js/index.js file and add the following function directly beneath the receivedEventfunction:
And then add the following line to call it from the onDeviceReady function:
Part 5: Try it!
Go back to the command line and run the following command from your project root folder:
phonegap local run android
When your application opens you should see a native calendar displayed on your device or emulator with the parameters specified in your code for the title, date, notes, location etc. Here’s a screenshot of it running on a Nexus 7:
- Type phonegap help for the PhoneGap CLI command options
- Type adb logcat to show the android console for debugging (requires the android tools and platform tools in path)
*** Part 6: Optional – Implement multi-threading
If your native code is interacting with the UI, then in Calendar.java you may want to specify it to run directly on the native UI thread such as follows after the action is checked:
If you’re not interacting with the UI but if you have extensive functionality that you want to run on a separate thread, use the following after the action is checked:
*** Part 7: Optional: Final Touches…
- Create a readme for your plugin and explain how it’s used.
- Also consider contributing it to the open source repository of plugins. ** UPDATE: Also check outhttp://plugins.cordova.io/ for the latest plugin repository.
- If you’re considering submitting it for PhoneGap Build support, ensure you’ve created a plugin.xmlfor your new plugin.
- PhoneGap Plugin Development Guide
- Ray Camden on Working with Plugins in PhoneGap 3.0
- PhoneGap Command Line Interface
- iOS Calendar Plugin Option
- Android Calendar Plugin Option
- Another Android Calendar Plugin Option