diff options
Diffstat (limited to 'www/lib/ionic-native-transitions/README.md')
| -rw-r--r-- | www/lib/ionic-native-transitions/README.md | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/www/lib/ionic-native-transitions/README.md b/www/lib/ionic-native-transitions/README.md new file mode 100644 index 00000000..119e3d61 --- /dev/null +++ b/www/lib/ionic-native-transitions/README.md @@ -0,0 +1,406 @@ +Native transitions for Ionic. Turn it on and enjoy native transitions. + + + +## Chat + +[](https://gitter.im/shprink/ionic-native-transitions) + +# Installation +## npm +[https://www.npmjs.com/package/ionic-native-transitions](https://www.npmjs.com/package/ionic-native-transitions) + +``` +npm install ionic-native-transitions --save +``` + +Then require the library + +```js +# ES5 +require('ionic-native-transitions'); + +# or ES6 +import 'ionic-native-transitions'; +``` + +## Bower + +``` +bower install shprink/ionic-native-transitions +``` + +Then insert the dist file + +``` +<script src="./PathToBowerLib/dist/ionic-native-transitions.min.js"></script> +``` + +## Cordova/Ionic +The recommended version for the Transition plugin is 0.6.5 or higher. + +``` +# Using Cordova +cordova plugin add https://github.com/Telerik-Verified-Plugins/NativePageTransitions#0.6.5 + +# Using Ionic CLI +ionic plugin add https://github.com/Telerik-Verified-Plugins/NativePageTransitions#0.6.5 +``` + +### iOS +Transitions on iOS9 can flicker sometimes. To prevent this from hapenning you can install this plugin: + +``` +# Using Cordova +cordova plugin add cordova-plugin-wkwebview + +# Using Ionic CLI +ionic plugin add cordova-plugin-wkwebview +``` + +### Android +if you are using Crosswalk > 1.3 please add the following to your `config.xml` + +``` +<preference name="CrosswalkAnimatable" value="true" /> +``` + +# Configuration + +```js +angular.module('yourApp', [ + 'ionic-native-transitions' +]); +``` + +## Set default options (optional) +**_Beware_**: Only use `setDefaultOptions` if you know what you are doing. + +```js +.config(function($ionicNativeTransitionsProvider){ + $ionicNativeTransitionsProvider.setDefaultOptions({ + duration: 400, // in milliseconds (ms), default 400, + slowdownfactor: 4, // overlap views (higher number is more) or no overlap (1), default 4 + iosdelay: -1, // ms to wait for the iOS webview to update before animation kicks in, default -1 + androiddelay: -1, // same as above but for Android, default -1 + winphonedelay: -1, // same as above but for Windows Phone, default -1, + fixedPixelsTop: 0, // the number of pixels of your fixed header, default 0 (iOS and Android) + fixedPixelsBottom: 0, // the number of pixels of your fixed footer (f.i. a tab bar), default 0 (iOS and Android) + triggerTransitionEvent: '$ionicView.afterEnter', // internal ionic-native-transitions option + backInOppositeDirection: false // Takes over default back transition and state back transition to use the opposite direction transition to go back + }); +}); +``` + +## Set default transition (optional) +[See the list of possible transitions](#transitions) + +```js +.config(function($ionicNativeTransitionsProvider){ + $ionicNativeTransitionsProvider.setDefaultTransition({ + type: 'slide', + direction: 'left' + }); +}); +``` + +## Set default back transition (optional) +[See the list of possible transitions](#transitions) + +```js +.config(function($ionicNativeTransitionsProvider){ + $ionicNativeTransitionsProvider.setDefaultBackTransition({ + type: 'slide', + direction: 'right' + }); +}); +``` + +## Enable/Disable (optional) +You can programatically disable the plugin for any reason: + +```js +# Within the config phase +# * @param {boolean} enabled +$ionicNativeTransitionsProvider.enable(false); + +# Anywhere else (controller, service etc.) +# * @param {boolean} enabled default true +# * @param {boolean} disableIonicTransitions default true +# * @param {string} ionicTransitionType default 'platform' + +# Disable plugin and enable ionic transitions (same as: enable(false, false)) +$ionicNativeTransitions.enable(false); + +# Enable plugin and disable ionic transitions (same as: enable(true, true)) +$ionicNativeTransitions.enable(true); + +# Disable plugin and disable ionic transitions +$ionicNativeTransitions.enable(false, true); + +# Enable plugin and enable ionic transitions +# in some cases it is useful <https://github.com/shprink/ionic-native-transitions/issues/23> +$ionicNativeTransitions.enable(true, false); +``` + +# Usage +By default any state transition will use the default transition (Defined in the configuration phase) but you can specify a different transition per state if you want using the UI router state definition: + +```js +.state('home', { + url: '/home', + nativeTransitions: { + "type": "flip", + "direction": "up" + } + templateUrl: "templates/home.html" +}) +``` + +You can also define a different transition (backward and forward) per device like this: + +```js +.state('home', { + url: '/home', + nativeTransitionsAndroid: { + "type": "flip", + "direction": "right" + }, + nativeTransitionsIOS: { + "type": "flip", + "direction": "left" + }, + nativeTransitionsWindowsPhone: { + "type": "flip", + "direction": "down" + }, + nativeTransitionsBackAndroid: { + "type": "flip", + "direction": "left" + }, + nativeTransitionsBackIOS: { + "type": "flip", + "direction": "right" + }, + nativeTransitionsBackWindowsPhone: { + "type": "flip", + "direction": "up" + }, + templateUrl: "templates/home.html" +}) +``` + +Overwrite just one device (here only android will be different) + +```js +.state('home', { + url: '/home', + nativeTransitions: { + "type": "flip", + "direction": "up" + }, + nativeTransitionsAndroid: { + "type": "flip", + "direction": "right" + } + templateUrl: "templates/home.html" +}) +``` + +Disable native transition for one state (for instance on tabs) + +```js +.state('home', { + url: '/home', + nativeTransitions: null, + templateUrl: "templates/home.html" +}) +``` + +## Programatically change page with native transitions + +### State + +```js +# * @description +# * Call state go and apply a native transition +# * @param {string|null} state default:null +# * @param {object} stateParams default:{} +# * @param {object} stateOptions default:{} +# * @param {object|null} transitionOptions default:null + +$ionicNativeTransitions.stateGo('yourState', {}, {}, { + "type": "slide", + "direction": "up", // 'left|right|up|down', default 'left' (which is like 'next') + "duration": 1500, // in milliseconds (ms), default 400 +}); +``` + +### Location.url + +```js +# * @description +# * Call location url and apply a native transition +# * @param {string|null} url default:null +# * @param {object|null} transitionOptions default:null + +$ionicNativeTransitions.locationUrl('/yourUrl', { + "type": "slide", + "direction": "down", // 'left|right|up|down', default 'left' (which is like 'next') + "duration": 1500, // in milliseconds (ms), default 400 +}); +``` + +## Using directives + +```html +<button native-ui-sref="tabs.home({param1: 'param1', param2: 'param2'})" native-ui-sref-opts="{reload: true}" native-options="{type: 'slide', direction:'down'}"></button> +``` + +## History back button + +Using the `<ion-nav-back-button>` directive automatically uses the default back transition if you have not added a specific `ng-click` on it. + +## Hadware back button (Android) + +The hardware back button on Android uses the default back transition + +## Swipe back (iOS) + +For now swipe back will trigger the state native transition (or the default). It does not use the back transition. + +You can disable swipe back like this: + +```js +$ionicConfigProvider.views.swipeBackEnabled(false); +``` + +<a name="transitions"></a> + +## Events +You can listen to success or error events + +```js +$rootScope.$on('ionicNativeTransitions.beforeTransition', function(){ + // Transition is about to happen +}); + +$rootScope.$on('ionicNativeTransitions.success', function(){ + // Transition success +}); + +$rootScope.$on('ionicNativeTransitions.error', function(){ + // Transition error +}); +``` + +# Possible transitions +## Slide (default animation) + +```js +{ + "type" : "slide", + "direction" : "left", // 'left|right|up|down', default 'left' (which is like 'next') + "duration" : 500, // in milliseconds (ms), default 400 +} +``` + +## Flip + +```js +{ + "type" : "flip", + "direction" : "up", // 'left|right|up|down', default 'right' (Android currently only supports left and right) + "duration" : 500, // in milliseconds (ms), default 400 +} +``` + +## Fade (iOS and Android only) + +```js +{ + "type" : "fade", + "duration" : 500, // in milliseconds (ms), default 400 +} +``` + +## Drawer (iOS and Android only) + +```js +{ + "type" : "drawer", + "origin" : "left", // 'left|right', open the drawer from this side of the view, default 'left' + "action" : "open", // 'open|close', default 'open', note that close is not behaving nicely on Crosswalk + } +``` + +## Curl (iOS only, direction up and down only) + +```js +{ + "type" : "curl", + "direction" : "up", // 'up|down', default 'up' +} +``` + +# FAQ + +## What's the best way to animate tabs? + +Use fade transition + +```js +.state('tabs.contact', { + url: "/contact", + nativeTransitions: { + type: "fade" + } +}) +``` + +if you to use slide, use it with the `fixedPixelsTop` option. + +```js +.state('tabs.contact', { + url: "/contact", + nativeTransitions: { + type: "slide", + direction: "left", + fixedPixelsTop: 93 + } +}) +``` + +# Contribute +## Development + +``` +npm install + +# Open two terminals +# and run watch to build on the lib files changes +npm run watch + +# in the other terminal run following to build the test page and the doc +npm start +``` + +Open `http://localhost:8080` + +## Tests on device + +``` +npm run platformAddAndroid +npm run platformAddIOS +npm run pluginAddAll + +# run iOS devices +npm run runIosDevice + +# run iOS devices +npm run runAndroid +``` + +# Thanks +- Eddy Verbruggen for his amazing job on: [https://github.com/Telerik-Verified-Plugins/NativePageTransitions](https://github.com/Telerik-Verified-Plugins/NativePageTransitions) +- GAJOTRES for his great post: [http://www.gajotres.net/handling-native-view-animations-with-ionic-framework/](http://www.gajotres.net/handling-native-view-animations-with-ionic-framework/) |