diff --git a/README.md b/README.md index 94c20e2..e9ae4c9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,145 @@ -Toast-PhoneGap-Plugin -===================== +# PhoneGap Toast plugin for Android and iOS -A Toast popup plugin for iOS and Android PhoneGap apps. +by [Eddy Verbruggen](@eddyverbruggen) + +## 0. Index + +1. [Description](#1-description) +2. [Screenshots](#2-screenshots) +3. [Installation](#3-installation) + 3. [Automatically (CLI / Plugman)](#automatically-cli--plugman) + 3. [Manually](#manually) + 3. [PhoneGap Build](#phonegap-build) +4. [Usage](#4-usage) +5. [Credits](#5-credits) +6. [License](#6-license) + +## 1. Description + +This plugin allows you to show a native Toast (a little text popup) on iOS and Android. +It's great for showing a non intrusive native notification which is guaranteed always in the viewport of the browser. + +* You can choose where to show the Toast: at the top, center or bottom of the screen. +* You can choose two durations: short (2 seconds), or long (5 seconds), after which the Toast automatically disappears. +* Compatible with [Cordova Plugman](https://github.com/apache/cordova-plugman). +* Pending official support by [PhoneGap Build](https://build.phonegap.com/plugins). + +## 2. Screenshots + +iOS 7 + +![ScreenShot](screenshot-ios-toast.png) + +Android + +![ScreenShot](screenshot-android-toast.png) + +## 3. Installation + +### Automatically (CLI / Plugman) +Toast is compatible with [Cordova Plugman](https://github.com/apache/cordova-plugman), compatible with [PhoneGap 3.0 CLI](http://docs.phonegap.com/en/3.0.0/guide_cli_index.md.html#The%20Command-line%20Interface_add_features), here's how it works with the CLI: + +``` +$ phonegap local plugin add https://github.com/EddyVerbruggen/Toast-PhoneGap-Plugin.git +``` +or +``` +$ cordova plugin add https://github.com/EddyVerbruggen/Toast-PhoneGap-Plugin.git +$ cordova prepare +``` + +Toast.js is brought in automatically. There is no need to change or add anything in your html. + +### Manually + +1\. Add the following xml to your `config.xml` in the root directory of your `www` folder: +```xml + + + + +``` +```xml + + + + +``` + +For iOS, you'll need to add the `QuartzCore.framework` to your project (it's for automatically removing the Toast after a few seconds). +Click your project, Build Phases, Link Binary With Libraries, search for and add `QuartzCore.framework`. + +2\. Grab a copy of Toast.js, add it to your project and reference it in `index.html`: +```html + +``` + +3\. Download the source files for iOS and/or Android and copy them to your project. + +iOS: Copy the two `.h` and two `.m` files to `platforms/ios//Plugins` + +Android: Copy `Toast.java` to `platforms/android/src/nl/xservices/plugins` (create the folders) + +### PhoneGap Build (pending approval!) + +Toast will soon work with PhoneGap build too, but only with PhoneGap 3.0 and up. + +Just add the following xml to your `config.xml` to always use the latest version of this plugin: +```xml + +``` +or to use this exact version: +```xml + +``` + +Toast.js is brought in automatically. There is no need to change or add anything in your html. + +## 4. Usage +You have two choices to make when showing a Toast: where to show it and for how long. +* toast.show(message, duration, position) +- duration: short / long +- position: top / center / bottom + +You can also use any of these convenience methods: +* toast.showShortTop(message) +* toast.showShortCenter(message) +* toast.showShortBottom(message) +* toast.showLongTop(message) +* toast.showLongCenter(message) +* toast.showLongBottom(message) + +You can copy-paste these lines of code for a quick test: +```html +

+

+

+``` + +## 5. CREDITS ## + +This plugin was enhanced for Plugman / PhoneGap Build by [Eddy Verbruggen](http://www.x-services.nl). +The Android code was entirely created by me. +I only has to slightly adjust [this excellent Toast project] (https://github.com/scalessec/Toast). + +## 6. License + +[The MIT License (MIT)](http://www.opensource.org/licenses/mit-license.html) + +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. \ No newline at end of file diff --git a/screenshot-android-toast.png b/screenshot-android-toast.png new file mode 100644 index 0000000..7692bff Binary files /dev/null and b/screenshot-android-toast.png differ diff --git a/screenshot-ios-toast.png b/screenshot-ios-toast.png new file mode 100644 index 0000000..894ea05 Binary files /dev/null and b/screenshot-ios-toast.png differ diff --git a/www/Toast.js b/www/Toast.js index 231e98f..2982b26 100755 --- a/www/Toast.js +++ b/www/Toast.js @@ -1,32 +1,32 @@ function Toast() { } -Toast.prototype._show = function (message, duration, position, successCallback, errorCallback) { +Toast.prototype.show = function (message, duration, position, successCallback, errorCallback) { cordova.exec(successCallback, errorCallback, "Toast", "show", [message, duration, position]); }; -Toast.prototype.shortTop = function (message, successCallback, errorCallback) { - this._show(message, "short", "top", successCallback, errorCallback); +Toast.prototype.showShortTop = function (message, successCallback, errorCallback) { + this.show(message, "short", "top", successCallback, errorCallback); }; -Toast.prototype.shortCenter = function (message, successCallback, errorCallback) { - this._show(message, "short", "center", successCallback, errorCallback); +Toast.prototype.showShortCenter = function (message, successCallback, errorCallback) { + this.show(message, "short", "center", successCallback, errorCallback); }; -Toast.prototype.shortBottom = function (message, successCallback, errorCallback) { - this._show(message, "short", "bottom", successCallback, errorCallback); +Toast.prototype.showShortBottom = function (message, successCallback, errorCallback) { + this.show(message, "short", "bottom", successCallback, errorCallback); }; -Toast.prototype.longTop = function (message, successCallback, errorCallback) { - this._show(message, "long", "top", successCallback, errorCallback); +Toast.prototype.showLongTop = function (message, successCallback, errorCallback) { + this.show(message, "long", "top", successCallback, errorCallback); }; -Toast.prototype.longCenter = function (message, successCallback, errorCallback) { - this._show(message, "long", "center", successCallback, errorCallback); +Toast.prototype.showLongCenter = function (message, successCallback, errorCallback) { + this.show(message, "long", "center", successCallback, errorCallback); }; -Toast.prototype.longBottom = function (message, successCallback, errorCallback) { - this._show(message, "long", "bottom", successCallback, errorCallback); +Toast.prototype.showLongBottom = function (message, successCallback, errorCallback) { + this.show(message, "long", "bottom", successCallback, errorCallback); }; Toast.install = function () {