mirror of
https://github.com/EddyVerbruggen/Toast-PhoneGap-Plugin.git
synced 2025-02-24 18:52:51 +08:00
157 lines
6.0 KiB
Markdown
157 lines
6.0 KiB
Markdown
# PhoneGap Toast plugin
|
|
|
|
for Android and iOS, by [Eddy Verbruggen](http://www.x-services.nl/phonegap-toast-plugin/796)
|
|
|
|
## 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 (approx. 2 seconds), or long (approx. 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).
|
|
|
|
Example usages:
|
|
* "There were validation errors"
|
|
* "Account created successfully"
|
|
* "The record was deleted"
|
|
* "Login successful"
|
|
* "The battery is almost dead"
|
|
* "You are now logged out"
|
|
* "Connection failure, please try again later"
|
|
|
|
## 2. Screenshots
|
|
|
|
iOS
|
|
|
|
|
|
|
|
Android
|
|
|
|
|
|
|
|
## 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
|
|
<!-- for iOS -->
|
|
<feature name="Toast">
|
|
<param name="ios-package" value="Toast" />
|
|
</feature>
|
|
```
|
|
```xml
|
|
<!-- for Android -->
|
|
<feature name="Toast">
|
|
<param name="android-package" value="nl.xservices.plugins.Toast" />
|
|
</feature>
|
|
```
|
|
|
|
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
|
|
<script type="text/javascript" src="js/Toast.js"></script>
|
|
```
|
|
|
|
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/<ProjectName>/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
|
|
<gap:plugin name="nl.x-services.plugins.toast" />
|
|
```
|
|
or to use this exact version:
|
|
```xml
|
|
<gap:plugin name="nl.x-services.plugins.toast" version="1.0" />
|
|
```
|
|
|
|
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.
|
|
* show(message, duration, position)
|
|
* duration: 'short', 'long'
|
|
* position: 'top', 'center', 'bottom'
|
|
|
|
You can also use any of these convenience methods:
|
|
* showShortTop(message)
|
|
* showShortCenter(message)
|
|
* showShortBottom(message)
|
|
* showLongTop(message)
|
|
* showLongCenter(message)
|
|
* showLongBottom(message)
|
|
|
|
You can copy-paste these lines of code for a quick test:
|
|
```html
|
|
<button onclick="window.plugins.toast.showShortTop('Hello there!', function(a){console.log('toast success: ' + a)}, function(b){alert('toast error: ' + b)})">Toast showShortTop</button>
|
|
<button onclick="window.plugins.toast.showLongBottom('Hello there!', function(a){console.log('toast success: ' + a)}, function(b){alert('toast error: ' + b)})">Toast showLongBottom</button>
|
|
<button onclick="window.plugins.toast.show('Hello there!', 'long', 'center', function(a){console.log('toast success: ' + a)}, function(b){alert('toast error: ' + b)})">Toast show long center</button>
|
|
```
|
|
|
|
## 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.
|
|
For iOS most credits go to this excellent [Toast for iOS project by Charles Scalesse] (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.
|
|
|
|
[](https://bitdeli.com/free "Bitdeli Badge")
|
|
|