javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2026-03-13 10:22:08 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add services, utilities

Browse Source
This commit is contained in:
Andy Joslin
2014-03-11 13:02:36 -06:00
parent a8e1524ce8
commit e9625ded9d
25 changed files with 629 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/tag-defs/index.js
View File

@@ -18,5 +18,8 @@ module.exports = [
},
{
name: 'codepen'
},
{
name: 'alias'
}
];

31
docs/templates/api/api.template.html vendored
View File

@@ -3,22 +3,23 @@
<@ block content @>
<@ block header @>
<@ if doc.docType == "directive" @>
<h2><$ doc.name | dashCase $>
<@ if doc.parent @>
<small>
(child of <$ doc.parent $>)
</small>
<@ endif @>
<@ if doc.controller @>
<small>
(controller: <$ doc.controller $>)
</small>
<@ endif @>
<h2>
<@ if doc.docType == "directive" @>
<$ doc.name | dashCase $>
<@ else @>
<$ doc.name $>
<@ endif @>
<@ if doc.parent @>
<small>
(child of <$ doc.parent $>)
</small>
<@ endif @>
<@ if doc.controller @>
<small>
(controller: <$ doc.controller $>)
</small>
<@ endif @>
</h2>
<@ else @>
## <$ doc.name $>
<@ endif @>
<@ if doc.codepen @>
{% include codepen.html id="<$ doc.codepen $>" %}

4
docs/templates/api/directive.template.html vendored
View File

@@ -46,12 +46,10 @@
<@- endif @>
<@ endblock -@>
<h2 id="api" style="clear:both;">API</h2>
<@ if doc.params @>
<h2 id="api" style="clear:both;">API</h2>
<$ paramTable(doc.params, true) $>
<@ else @>
No options available.
<@ endif @>
<@ include "lib/events.template.html" @>

9
docs/templates/api/utility.template.html vendored Normal file
View File

@@ -0,0 +1,9 @@
<@ extends "api/object.template.html" @>
<@ block related_components @>
<@ if doc.providerDoc -@>
<li>
<a href="<$ doc.providerDoc.path $>">- <$ doc.providerDoc.name $></a>
</li>
<@- endif @>
<@ endblock @>

12
docs/templates/lib/macros.html vendored
View File

@@ -4,7 +4,7 @@
<@- endmacro -@>
<@ macro paramTable(params, isDirective) @>
<table class="table">
<table class="table" style="margin:0;">
<thead>
<tr>
<th><@ if isDirective @>Attr<@ else @>Param<@ endif @></th>
@@ -42,11 +42,11 @@
<@- macro functionSyntax(fn) @>
<@- set sep = joiner(', ') -@>
`<$ fn.name $>(<@- for param in fn.params @><$ sep() $>
<@- if param.type.optional @>[<@ endif -@>
<$ param.name $>
<@- if param.type.optional @>]<@ endif -@>
<@ endfor @>)`
<code><$ fn.name $>(<@- for param in fn.params @><$ sep() $>
<@- if param.type.optional @>[<@ endif -@>
<$ param.name $>
<@- if param.type.optional @>]<@ endif -@>
<@ endfor @>)</code><@ if fn.alias @><small>(alias: <$ fn.alias $>)</small><@ endif @>
<@ endmacro -@>
<@- macro typeInfo(fn) -@>

4
docs/templates/lib/methods.template.html vendored
View File

@@ -3,7 +3,9 @@
<@- for method in doc.methods @>
<div id="<$ method.name $>"></div>
### <$ functionSyntax(method) $>
<h2>
<$ functionSyntax(method) $>
</h2>
<$ method.description $>

11
js/ext/angular/src/directive/ionicContent.js vendored
View File

@@ -202,16 +202,15 @@ function($parse, $timeout, $ionicScrollDelegate, $controller, $ionicBind) {
* @restrict E
*
* @description
* The ionInfiniteScroll directive, when placed inside of
* {@link ionic.directive:ionContent}, allows you to call a function whenever
* The ionInfiniteScroll directive allows you to call a function whenever
* the user gets to the bottom of the page or near the bottom of the page.
*
* The expression you pass in for `on-infinite` is called when the user scrolls
* The expression you pass in for `on-infinite` is called when the user scrolls
* greater than `distance` away from the bottom of the content.
*
* @param {expression} on-infinite What to call when the scroller reaches the
* @param {expression} on-infinite What to call when the scroller reaches the
* bottom.
* @param {string=} distance The distance from the bottom that the scroll must
* @param {string=} distance The distance from the bottom that the scroll must
* reach to trigger the on-infinite expression. Default 1%.
*
* @usage
@@ -235,7 +234,7 @@ function($parse, $timeout, $ionicScrollDelegate, $controller, $ionicBind) {
* }
* ```
*
* An easy to way to stop infinite scroll once there is no more data to load
* An easy to way to stop infinite scroll once there is no more data to load
* is to use angular's `ng-if` directive:
*
* ```html

6
js/ext/angular/src/directive/ionicLoading.js vendored
View File

@@ -3,6 +3,10 @@
angular.module('ionic.ui.loading', [])
/**
* @private
* $ionicLoading service is documented
*/
.directive('ionLoading', function() {
return {
restrict: 'E',
@@ -11,7 +15,7 @@ angular.module('ionic.ui.loading', [])
link: function($scope, $element){
$element.addClass($scope.animation || '');
},
template: '<div class="loading-backdrop" ng-class="{enabled: showBackdrop}">' +
template: '<div class="loading-backdrop" ng-class="{enabled: showBackdrop}">' +
'<div class="loading" ng-transclude>' +
'</div>' +
'</div>'

2
js/ext/angular/src/directive/ionicRadio.js vendored
View File

@@ -3,8 +3,6 @@
angular.module('ionic.ui.radio', [])
// The radio button is a radio powered element with only
// one possible selection in a set of options.
/**
* @ngdoc directive
* @name ionRadio

1
js/ext/angular/src/directive/ionicSlideBox.js vendored
View File

@@ -12,6 +12,7 @@ angular.module('ionic.ui.slideBox', [])
* @name ionSlideBox
* @module ionic
* @restrict E
* @controller ionicSlideBox
* @description
* The Slide Box is a multi-page container where each page can be swiped or dragged between:
*

103
js/ext/angular/src/directive/ionicViewState.js vendored
View File

@@ -1,22 +1,6 @@
(function() {
'use strict';
/**
* @description
* The NavController is a navigation stack View Controller modelled off of
* UINavigationController from Cocoa Touch. With the Nav Controller, you can
* "push" new "pages" on to the navigation stack, and then pop them off to go
* back. The NavController controls a navigation bar with a back button and title
* which updates as the pages switch.
*
* The NavController makes sure to not recycle scopes of old pages
* so that a pop will still show the same state that the user left.
*
* However, once a page is popped, its scope is destroyed and will have to be
* recreated then next time it is pushed.
*
*/
angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gesture', 'ngSanitize'])
/**
@@ -27,9 +11,9 @@ angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gestu
*
* @usage
* If have an {@link ionic.directive:ionNavView} directive, we can also create an
* <ion-nav-bar>, which will create a topbar that updates as the application state changes.
* <ion-nav-bar>, which will create a topbar that updates as the application state changes.
* We can also add some styles and set up animations:
*
*
* ```html
* <body ng-app="starter">
* <!-- The nav bar that will be updated as we navigate -->
@@ -37,7 +21,7 @@ angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gestu
* type="bar-positive"
* back-button-type="button-icon"
* back-button-icon="ion-arrow-left-c"></ion-nav-bar>
*
*
* <!-- where the initial view template will be rendered -->
* <ion-nav-view animation="slide-left-right"></ion-nav-view>
* </body>
@@ -46,7 +30,7 @@ angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gestu
* @param {string=} back-button-type The type of the back button's icon. Available: 'button-icon' or just 'button'.
* @param {string=} back-button-icon The icon to use for the back button. For example, 'ion-arrow-left-c'.
* @param {string=} back-button-label The label to use for the back button. For example, 'Back'.
* @param animation {string=} The animation used to transition between titles.
* @param animation {string=} The animation used to transition between titles.
* @param type {string=} The className for the navbar. For example, 'bar-positive'.
* @param align {string=} Where to align the title of the navbar. Available: 'left', 'right', 'center'. Defaults to 'center'.
*/
@@ -210,39 +194,37 @@ angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gestu
};
}])
.directive('ionNavBarTitle', function() {
return {
restrict: 'A',
require: '^ionNavBar',
link: function($scope, $element, $attr, navBarCtrl) {
$scope.headerBarView && $scope.headerBarView.align();
$element.on('$animate:close', function() {
$scope.headerBarView && $scope.headerBarView.align();
});
}
};
})
/*
* Directive to put on an element that has 'invisible' class when rendered.
* This removes the visible class one frame later.
* Fixes flickering in iOS7 and old android.
* Used in title and back button
*/
.directive('ionAsyncVisible', function() {
return function($scope, $element) {
ionic.requestAnimationFrame(function() {
$element[0].classList.remove('invisible');
});
};
})
/**
* @ngdoc directive
* @name ionView
* @module ionic
* @restrict E
*/
* @ngdoc directive
* @name ionView
* @module ionic
* @restrict E
* @parent ionNavBar
*
* @description
* A container for content, used to tell a parent {@link ionic.directive:ionNavBar}
* about the current view.
*
* @usage
* Below is an example where our page will load with a navbar containing "My Page" as the title.
*
* ```html
* <ion-nav-bar></ion-nav-bar>
* <ion-nav-view>
* <ion-view title="My Page">
* <ion-content>
* Hello!
* </ion-content>
* </ion-view>
* </ion-nav-view>
* ```
*
* @param {expression=} left-buttons The leftButtons to display on the parent {@link ionic.directive:ionNavBar}.
* @param {expression=} right-buttons The rightButtons to display on the parent {@link ionic.directive:ionNavBar}.
* @param {string=} title The title to display on the parent {@link ionic.directive:ionNavBar}.
* @param {boolean=} hideBackButton Whether to hide the back button on the parent {@link ionic.directive:ionNavBar}.
* @param {boolean=} hideNavBar Whether to hide the parent {@link ionic.directive:ionNavBar}.
*/
.directive('ionView', ['$ionicViewService', '$rootScope', '$animate',
function( $ionicViewService, $rootScope, $animate) {
return {
@@ -251,15 +233,9 @@ angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gestu
scope: {
leftButtons: '=',
rightButtons: '=',
title: '=',
icon: '@',
iconOn: '@',
iconOff: '@',
type: '@',
alignTitle: '@',
title: '@',
hideBackButton: '@',
hideNavBar: '@',
animation: '@'
},
compile: function(tElement, tAttrs, transclude) {
@@ -301,6 +277,9 @@ angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gestu
}])
/**
* @private
*/
.directive('ionNavBackButton', ['$ionicViewService', '$rootScope',
function($ionicViewService, $rootScope) {
@@ -412,10 +391,10 @@ angular.module('ionic.ui.viewState', ['ionic.service.view', 'ionic.service.gestu
* having to fetch them from the network.
*
* Please visit [AngularUI Router's docs](https://github.com/angular-ui/ui-router/wiki) for
* more info. Below is a great video by the AngularUI Router guys that may help to explain
* more info. Below is a great video by the AngularUI Router guys that may help to explain
* how it all works:
*
* <iframe width="560" height="315" src="//www.youtube.com/embed/dqJRoh8MnBo"
*
* <iframe width="560" height="315" src="//www.youtube.com/embed/dqJRoh8MnBo"
* frameborder="0" allowfullscreen></iframe>
*
* @param {string=} name A view name. The name should be unique amongst the other views in the

5
js/ext/angular/src/service/decorators/location.js vendored
View File

@@ -1,5 +1,8 @@
angular.module('ionic.decorator.location', [])
/**
* @private
*/
.config(['$provide', function($provide) {
$provide.decorator('$location', ['$delegate', '$timeout', $LocationDecorator]);
}]);
@@ -7,7 +10,7 @@ angular.module('ionic.decorator.location', [])
function $LocationDecorator($location, $timeout) {
$location.__hash = $location.hash;
//Fix: first time window.location.hash is set, the scrollable area
//Fix: when window.location.hash is set, the scrollable area
//found nearest to body's scrollTop is set to scroll to an element
//with that ID.
$location.hash = function(value) {

69
js/ext/angular/src/service/delegates/ionicScrollDelegate.js vendored
View File

@@ -3,26 +3,85 @@
angular.module('ionic.ui.service.scrollDelegate', [])
/**
* @ngdoc service
* @name $ionicScrollDelegate
* @module ionic
* @description
* Allows you to have some control over a scrollable area (created by an
* {@link ionic.directive:ionContent} or {@link ionic.directive:ionScroll}
* directive).
*
* Inject it into a controller, and its methods will send messages to the nearest scrollView and all of its children.
*
* @usage
* ```html
* <ion-content ng-controller="MyController">
* <button class="button" ng-click="scrollToTop()">
* Scroll To Top
* </button>
* </ion-content>
* ```
* ```js
* function MyController($scope, $ionicScrollDelegate) {
* $scope.scrollToTop = function() {
* $ionicScrollDelegate.scrollTop();
* };
* }
* ```
*/
.factory('$ionicScrollDelegate', ['$rootScope', '$timeout', '$q', '$anchorScroll', '$location', '$document', function($rootScope, $timeout, $q, $anchorScroll, $location, $document) {
return {
/**
* Trigger a scroll-to-top event on child scrollers.
* @ngdoc method
* @name $ionicScrollDelegate#scrollTop
* @param {boolean=} shouldAnimate Whether the scroll should animate.
*/
scrollTop: function(animate) {
$rootScope.$broadcast('scroll.scrollTop', animate);
},
/**
* @ngdoc method
* @name $ionicScrollDelegate#scrollBottom
* @param {boolean=} shouldAnimate Whether the scroll should animate.
*/
scrollBottom: function(animate) {
$rootScope.$broadcast('scroll.scrollBottom', animate);
},
/**
* @ngdoc method
* @name $ionicScrollDelegate#scroll
* @param {number} left The x-value to scroll to.
* @param {number} top The y-value to scroll to.
* @param {boolean=} shouldAnimate Whether the scroll should animate.
*/
scrollTo: function(left, top, animate) {
$rootScope.$broadcast('scroll.scrollTo', left, top, animate);
},
resize: function() {
$rootScope.$broadcast('scroll.resize');
},
/**
* @ngdoc method
* @name $ionicScrollDelegate#anchorScroll
* @description Tell the scrollView to scroll to the element with an id
* matching window.location.hash.
*
* If no matching element is found, it will scroll to top.
*
* @param {boolean=} shouldAnimate Whether the scroll should animate.
*/
anchorScroll: function(animate) {
$rootScope.$broadcast('scroll.anchorScroll', animate);
},
/**
* @ngdoc method
* @name $ionicScrollDelegate#resize
* @description Tell the scrollView to recalculate the size of its container.
*/
resize: function() {
$rootScope.$broadcast('scroll.resize');
},
/**
* @private
*/
tapScrollToTop: function(element, animate) {
var _this = this;
if (!angular.isDefined(animate)) {
@@ -50,6 +109,7 @@ angular.module('ionic.ui.service.scrollDelegate', [])
},
/**
* @private
* Attempt to get the current scroll view in scope (if any)
*
* Note: will not work in an isolated scope context.
@@ -59,6 +119,7 @@ angular.module('ionic.ui.service.scrollDelegate', [])
},
/**
* @private
* Register a scope and scroll view for scroll event handling.
* $scope {Scope} the scope to register and listen for events
*/

3
js/ext/angular/src/service/ionicBind.js vendored
View File

@@ -1,4 +1,7 @@
angular.module('ionic.service.bind', [])
/**
* @private
*/
.factory('$ionicBind', ['$parse', '$interpolate', function($parse, $interpolate) {
var LOCAL_REGEXP = /^\s*([@=&])(\??)\s*(\w*)\s*$/;
return function(scope, attrs, bindDefinition) {

24
js/ext/angular/src/service/ionicGesture.js vendored
View File

@@ -1,10 +1,34 @@
angular.module('ionic.service.gesture', [])
/**
* @ngdoc service
* @name $ionicGesture
* @module ionic
* @description An angular service exposing ionic
* {@link ionic.utility:ionic.EventController}'s gestures.
*/
.factory('$ionicGesture', [function() {
return {
/**
* @ngdoc method
* @name $ionicGesture#on
* @description Add an event listener for a gesture on an element. See {@link ionic.utility:ionic.EventController#onGesture}.
* @param {string} eventType The gesture event to listen for.
* @param {function(e)} callback The function to call when the gesture
* happens.
* @param {element} $element The angular element to listen for the event on.
*/
on: function(eventType, cb, $element) {
return window.ionic.onGesture(eventType, cb, $element[0]);
},
/**
* @ngdoc method
* @name $ionicGesture#on
* @description Remove an event listener for a gesture on an element. See {@link ionic.utility:ionic.EventController#offGesture}.
* @param {string} eventType The gesture event to remove the listener for.
* @param {function(e)} callback The listener to remove.
* @param {element} $element The angular element that was listening for the event.
*/
off: function(gesture, eventType, cb) {
return window.ionic.offGesture(gesture, eventType, cb);
}

43
js/ext/angular/src/service/ionicLoading.js vendored
View File

@@ -1,14 +1,45 @@
angular.module('ionic.service.loading', ['ionic.ui.loading'])
/**
* @ngdoc service
* @name $ionicLoading
* @module ionic
* @description
* An overlay that can be used to indicate activity while blocking user
* interaction.
*
* @usage
* ```js
* angular.module('LoadingApp', ['ionic'])
* .controller('LoadingCtrl', function($scope, $ionicLoading) {
* $scope.show = function() {
* $scope.loading = $ionicLoading.show({
* content: 'Loading',
* });
* };
* $scope.hide = function(){
* $scope.loading.hide();
* };
* });
* ```
*/
.factory('$ionicLoading', ['$rootScope', '$document', '$compile', function($rootScope, $document, $compile) {
return {
/**
* Load an action sheet with the given template string.
*
* A new isolated scope will be created for the
* action sheet and the new element will be appended into the body.
*
* @param {object} opts the options for this ActionSheet (see docs)
* @ngdoc method
* @name $ionicLoading#show
* @param {object} opts The options for the indicator. Available properties:
* - `{string=}` `content` The content of the indicator. Default: none.
* - `{string=}` `animation` The animation of the indicator.
* Default: 'fade-in'.
* - `{boolean=}` `showBackdrop` Whether to show a backdrop. Default: true.
* - `{number=}` `maxWidth` The maximum width of the indicator, in pixels.
* Default: 200.
* - `{number=}` `showDelay` How many milliseconds to delay showing the
* indicator. Default: 0.
* @returns {object} A shown loader with the following methods:
* - `hide()` - Hides the loader.
* - `show()` - Shows the loader.
*/
show: function(opts) {
var defaults = {

118
js/ext/angular/src/service/ionicModal.js vendored
View File

@@ -1,16 +1,83 @@
angular.module('ionic.service.modal', ['ionic.service.templateLoad', 'ionic.service.platform', 'ionic.ui.modal'])
/**
* @ngdoc service
* @name $ionicModal
* @module ionic
* @controller ionicModal
* @description
* The Modal is a content pane that can go over the user's main view
* temporarily. Usually used for making a choice or editing an item.
*
* @usage
* ```html
* <script id="my-modal.html" type="text/ng-template">
* <div class="modal">
* <ion-header-bar title="My Modal Title"></ion-header-bar>
* <ion-content>
* Hello!
* </ion-content>
* </div>
* </script>
* ```
* ```js
* angular.module('testApp', ['ionic'])
* .controller('MyController', function($scope, $ionicModal) {
* $ionicModal.fromTemplateUrl('modal.html', {
* scope: $scope,
* animation: 'slide-in-up'
* }).then(function(modal) {
* $scope.modal = modal;
* });
* $scope.openModal = function() {
* $scope.modal.show();
* };
* $scope.closeModal = function() {
* $scope.modal.hide();
* };
* //Cleanup the modal when we're done with it!
* $scope.$on('$destroy', function() {
* $scope.modal.remove();
* });
* });
* ```
*/
.factory('$ionicModal', ['$rootScope', '$document', '$compile', '$timeout', '$ionicPlatform', '$ionicTemplateLoader',
function( $rootScope, $document, $compile, $timeout, $ionicPlatform, $ionicTemplateLoader) {
/**
* @ngdoc controller
* @name ionicModal
* @module ionic
* @description
* Instantiated by the {@link ionic.service:$ionicModal} service.
*
* Hint: Be sure to call [remove()](#remove) when you are done with each modal
* to clean it up and avoid memory leaks.
*/
var ModalView = ionic.views.Modal.inherit({
/**
* @ngdoc method
* @name ionicModal#initialize
* @description Creates a new modal controller instance.
* @param {object} options An options object with the following properties:
* - `{object=}` `scope` The scope to be a child of.
* Default: creates a child of $rootScope.
* - `{string=}` `animation` The animation to show & hide with.
* Default: 'slide-in-up'
* - `{boolean=}` `focusFirstInput` Whether to autofocus the first input of
* the modal when shown. Default: false.
*/
initialize: function(opts) {
ionic.views.Modal.prototype.initialize.call(this, opts);
this.animation = opts.animation || 'slide-in-up';
},
// Show the modal
/**
* @ngdoc method
* @name ionicModal#show
* @description Show this modal instance.
*/
show: function() {
var self = this;
var modalEl = angular.element(self.modalEl);
@@ -38,7 +105,11 @@ angular.module('ionic.service.modal', ['ionic.service.templateLoad', 'ionic.serv
},
// Hide the modal
/**
* @ngdoc method
* @name ionicModal#hide
* @description Hide this modal instance.
*/
hide: function() {
this._isShown = false;
var modalEl = angular.element(this.modalEl);
@@ -61,7 +132,11 @@ angular.module('ionic.service.modal', ['ionic.service.templateLoad', 'ionic.serv
this._deregisterBackButton && this._deregisterBackButton();
},
// Remove and destroy the modal scope
/**
* @ngdoc method
* @name ionicModal#remove
* @description Remove this modal instance from the DOM and clean up.
*/
remove: function() {
var self = this;
self.hide();
@@ -73,6 +148,11 @@ angular.module('ionic.service.modal', ['ionic.service.templateLoad', 'ionic.serv
}, 750);
},
/**
* @ngdoc method
* @name ionicModal#isShown
* @returns boolean Whether this modal is currently shown.
*/
isShown: function() {
return !!this._isShown;
}
@@ -102,19 +182,37 @@ angular.module('ionic.service.modal', ['ionic.service.templateLoad', 'ionic.serv
return {
/**
* Load a modal with the given template string.
*
* A new isolated scope will be created for the
* modal and the new element will be appended into the body.
* @ngdoc method
* @name $ionicModal#fromTemplate
* @param {string} templateString The template string to use as the modal's
* content.
* @param {object} options Options to be passed {@link ionic.controller:ionicModal#initialize ionicModal#initialize} method.
* @returns {object} An instance of an {@link ionic.controller:ionicModal}
* controller.
*/
fromTemplate: function(templateString, options) {
var modal = createModal(templateString, options || {});
return modal;
},
fromTemplateUrl: function(url, cb, options) {
/**
* @ngdoc method
* @name $ionicModal#fromTemplateUrl
* @param {string} templateUrl The url to load the template from.
* @param {object} options Options to be passed {@link ionic.controller:ionicModal#initialize ionicModal#initialize} method.
* options object.
* @returns {promise} A promise that will be resolved with an instance of
* an {@link ionic.controller:ionicModal} controller.
*/
fromTemplateUrl: function(url, options) {
var cb;
//Deprecated: allow a callback as second parameter. Now we return a promise.
if (arguments.length === 3) {
cb = arguments[1];
options = arguments[2] || {};
}
return $ionicTemplateLoader.load(url).then(function(templateString) {
var modal = createModal(templateString, options || {});
cb ? cb(modal) : null;
cb && cb(modal);
return modal;
});
}

62
js/ext/angular/src/service/ionicPlatform.js vendored
View File

@@ -3,11 +3,14 @@
angular.module('ionic.service.platform', [])
/**
* The platformProvider makes it easy to set and detect which platform
* the app is currently running on. It has some auto detection built in
* for PhoneGap and Cordova. This provider also takes care of
* initializing some defaults that depend on the platform, such as the
* height of header bars on iOS 7.
* @ngdoc service
* @name $ionicPlatform
* @module ionic
* @description
* An angular abstraction of {@link ionic.utility:ionic.Platform}.
*
* Used to detect the current platform, as well as do things like override the
* Android back button in PhoneGap/Cordova.
*/
.provider('$ionicPlatform', function() {
@@ -15,9 +18,12 @@ angular.module('ionic.service.platform', [])
$get: ['$q', '$rootScope', function($q, $rootScope) {
return {
/**
* Some platforms have hardware back buttons, so this is one way to bind to it.
*
* @param {function} cb the callback to trigger when this event occurs
* @ngdoc method
* @name $ionicPlatform#onHardwareBackButton
* @description
* Some platforms have a hardware back button, so this is one way to
* bind to it.
* @param {function} callback the callback to trigger when this event occurs
*/
onHardwareBackButton: function(cb) {
ionic.Platform.ready(function() {
@@ -26,9 +32,12 @@ angular.module('ionic.service.platform', [])
},
/**
* @ngdoc method
* @name $ionicPlatform#offHardwareBackButton
* @description
* Remove an event listener for the backbutton.
*
* @param {function} fn the listener function that was originally bound.
* @param {function} callback The listener function that was
* originally bound.
*/
offHardwareBackButton: function(fn) {
ionic.Platform.ready(function() {
@@ -37,14 +46,24 @@ angular.module('ionic.service.platform', [])
},
/**
* Register a hardware back button action. Only one action will execute when
* the back button is clicked, so this method decides which of the registered
* back button actions has the highest priority. For example, if an actionsheet
* is showing, the back button should close the actionsheet, but it should not
* also go back a page view or close a modal which may be open.
* @ngdoc method
* @name $ionicPlatform#registerBackButtonAction
* @description
* Register a hardware back button action. Only one action will execute
* when the back button is clicked, so this method decides which of
* the registered back button actions has the highest priority.
*
* @param {function} fn the listener function that was originally bound.
* For example, if an actionsheet is showing, the back button should
* close the actionsheet, but it should not also go back a page view
* or close a modal which may be open.
*
* @param {function} callback Called when the back button is pressed,
* if this listener is the highest priority.
* @param {number} priority Only the highest priority will execute.
* @param {*=} actionId The id to assign this action. Default: a
* random unique id.
* @returns {function} A function that, when called, will deregister
* this backButtonAction.
*/
registerBackButtonAction: function(fn, priority, actionId) {
var self = this;
@@ -69,6 +88,9 @@ angular.module('ionic.service.platform', [])
};
},
/**
* @private
*/
hardwareBackButtonClick: function(e){
// loop through all the registered back button actions
// and only run the last one of the highest priority
@@ -89,8 +111,12 @@ angular.module('ionic.service.platform', [])
},
/**
* Trigger a callback once the device is ready, or immediately if the device is already
* ready.
* @ngdoc method
* @name $ionicPlatform#ready
* @description
* Trigger a callback once the device is ready,
* or immediately if the device is already ready.
* @param {function} callback The function to call.
*/
ready: function(cb) {
var q = $q.defer();

3
js/ext/angular/src/service/ionicTemplateLoad.js vendored
View File

@@ -1,5 +1,8 @@
angular.module('ionic.service.templateLoad', [])
/**
* @private
*/
.factory('$ionicTemplateLoader', ['$q', '$http', '$templateCache', function($q, $http, $templateCache) {
return {
load: function(url) {

6
js/ext/angular/src/service/ionicView.js vendored
View File

@@ -1,7 +1,11 @@
angular.module('ionic.service.view', ['ui.router', 'ionic.service.platform'])
.run( ['$rootScope', '$state', '$location', '$document', '$animate', '$ionicPlatform',
/**
* @private
* TODO document
*/
.run(['$rootScope', '$state', '$location', '$document', '$animate', '$ionicPlatform',
function( $rootScope, $state, $location, $document, $animate, $ionicPlatform) {
// init the variables that keep track of the view history

109
js/utils/dom.js
View File

@@ -23,23 +23,39 @@
};
})();
/**
* @ngdoc utility
* @name ionic.DomUtil
* @module ionic
*/
ionic.DomUtil = {
//Call with proper context
/**
* @ngdoc method
* @name ionic.DomUtil#requestAnimationFrame
* @alias ionic.requestAnimationFrame
* @description Calls [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window.requestAnimationFrame), or a polyfill if not available.
* @param {function} callback The function to call when the next frame
* happens.
*/
requestAnimationFrame: function(cb) {
window._rAF(cb);
},
/*
/**
* @ngdoc method
* @name ionic.DomUtil#animationFrameThrottle
* @alias ionic.animationFrameThrottle
* @description
* When given a callback, if that callback is called 100 times between
* animation frames, Throttle will make it only call the last of 100tha call
* animation frames, adding Throttle will make it only run the last of
* the 100 calls.
*
* It returns a function, which will then call the passed in callback. The
* passed in callback will receive the context the returned function is called with.
*
* @example
* this.setTranslateX = ionic.animationFrameThrottle(function(x) {
* this.el.style[ionic.CSS.TRANSFORM] = 'translate3d(' + x + 'px, 0, 0)';
* })
* @param {function} callback a function which will be throttled to
* requestAnimationFrame
* @returns {function} A function which will then call the passed in callback.
* The passed in callback will receive the context the returned function is
* called with.
*/
animationFrameThrottle: function(cb) {
var args, isQueued, context;
@@ -56,10 +72,15 @@
};
},
/*
* Find an element's offset, then add it to the offset of the parent
* until we are at the direct child of parentEl
* use-case: find scroll offset of any element within a scroll container
/**
* @ngdoc method
* @name ionic.DomUtil#getPositionInParent
* @description
* Find an element's scroll offset within its container.
* @param {DOMElement} element The element to find the offset of.
* @returns {object} A position object with the following properties:
* - `{number}` `left` The left offset of the element.
* - `{number}` `top` The top offset of the element.
*/
getPositionInParent: function(el) {
return {
@@ -68,6 +89,14 @@
};
},
/**
* @ngdoc method
* @name ionic.DomUtil#ready
* @description
* Call a function when the dom is ready, or if it is already ready
* call the function immediately.
* @param {function} callback The function to be called.
*/
ready: function(cb) {
if(document.readyState === "complete") {
ionic.requestAnimationFrame(cb);
@@ -76,6 +105,20 @@
}
},
/**
* @ngdoc method
* @name ionic.DomUtil#getTextBounds
* @description
* Get a rect representing the bounds of the given textNode.
* @param {DOMElement} textNode The textNode to find the bounds of.
* @returns {object} An object representing the bounds of the node. Properties:
* - `{number}` `left` The left positton of the textNode.
* - `{number}` `right` The right positton of the textNode.
* - `{number}` `top` The top positton of the textNode.
* - `{number}` `bottom` The bottom position of the textNode.
* - `{number}` `width` The width of the textNode.
* - `{number}` `height` The height of the textNode.
*/
getTextBounds: function(textNode) {
if(document.createRange) {
var range = document.createRange();
@@ -100,6 +143,16 @@
return null;
},
/**
* @ngdoc method
* @name ionic.DomUtil#getChildIndex
* @description
* Get the first index of a child node within the given element of the
* specified type.
* @param {DOMElement} element The element to find the index of.
* @param {string} type The nodeName to match children of element against.
* @returns {number} The index, or -1, of a child with nodeName matching type.
*/
getChildIndex: function(element, type) {
if(type) {
var ch = element.parentNode.children;
@@ -116,11 +169,20 @@
}
return Array.prototype.slice.call(element.parentNode.children).indexOf(element);
},
/**
* @private
*/
swapNodes: function(src, dest) {
dest.parentNode.insertBefore(src, dest);
},
/**
* {returns} the closest parent matching the className
* @ngdoc method
* @name ionic.DomUtil#getParentWithClass
* @param {DOMElement} element
* @param {string} className
* @returns {DOMElement} The closest parent of element matching the
* className, or null.
*/
getParentWithClass: function(e, className) {
while(e.parentNode) {
@@ -132,7 +194,12 @@
return null;
},
/**
* {returns} the closest parent or self matching the className
* @ngdoc method
* @name ionic.DomUtil#getParentWithClass
* @param {DOMElement} element
* @param {string} className
* @returns {DOMElement} The closest parent or self matching the
* className, or null.
*/
getParentOrSelfWithClass: function(e, className) {
while(e) {
@@ -144,6 +211,18 @@
return null;
},
/**
* @ngdoc method
* @name ionic.DomUtil#rectContains
* @param {number} x
* @param {number} y
* @param {number} x1
* @param {number} y1
* @param {number} x2
* @param {number} y2
* @returns {boolean} Whether {x,y} fits within the rectangle defined by
* {x1,y1,x2,y2}.
*/
rectContains: function(x, y, x1, y1, x2, y2) {
if(x < x1 || x > x2) return false;
if(y < y1 || y > y2) return false;

56
js/utils/events.js
View File

@@ -44,9 +44,25 @@
})();
}
/**
* @ngdoc utility
* @name ionic.EventController
* @module ionic
*/
ionic.EventController = {
VIRTUALIZED_EVENTS: ['tap', 'swipe', 'swiperight', 'swipeleft', 'drag', 'hold', 'release'],
/**
* @ngdoc method
* @name ionic.EventController#trigger
* @alias ionic.trigger
* @param {string} eventType The event to trigger.
* @param {object} data The data for the event. Hint: pass in
* `{target: targetElement}`
* @param {boolean=} bubbles Whether the event should bubble up the DOM.
* @param {boolean=} cancelable Whether the event should be cancelable.
*/
// Trigger a new event
trigger: function(eventType, data, bubbles, cancelable) {
var event = new CustomEvent(eventType, {
@@ -60,7 +76,15 @@
data && data.target && data.target.dispatchEvent(event) || window.dispatchEvent(event);
},
// Bind an event
/**
* @ngdoc method
* @name ionic.EventController#on
* @alias ionic.on
* @description Listen to an event on an element.
* @param {string} type The event to listen for.
* @param {function} callback The listener to be called.
* @param {DOMElement} element The element to listen for the event on.
*/
on: function(type, callback, element) {
var e = element || window;
@@ -77,18 +101,44 @@
e.addEventListener(type, callback);
},
/**
* @ngdoc method
* @name ionic.EventController#off
* @alias ionic.off
* @description Remove an event listener.
* @param {string} type
* @param {function} callback
* @param {DOMElement} element
*/
off: function(type, callback, element) {
element.removeEventListener(type, callback);
},
// Register for a new gesture event on the given element
/**
* @ngdoc method
* @name ionic.EventController#onGesture
* @alias ionic.onGesture
* @description Add an event listener for a gesture on an element.
* @param {string} eventType The gesture event to listen for.
* @param {function(e)} callback The function to call when the gesture
* happens.
* @param {DOMElement} element The angular element to listen for the event on.
*/
onGesture: function(type, callback, element) {
var gesture = new ionic.Gesture(element);
gesture.on(type, callback);
return gesture;
},
// Unregister a previous gesture event
/**
* @ngdoc method
* @name ionic.EventController#offGesture
* @alias ionic.offGesture
* @description Remove an event listener for a gesture on an element.
* @param {string} eventType The gesture event.
* @param {function(e)} callback The listener that was added earlier.
* @param {DOMElement} element The element the listener was added on.
*/
offGesture: function(gesture, type, callback) {
gesture.off(type, callback);
},

97
js/utils/platform.js
View File

@@ -1,13 +1,46 @@
(function(ionic) {
/**
* @ngdoc utility
* @name ionic.Platform
* @module ionic
*/
ionic.Platform = {
/**
* @ngdoc property
* @name ionic.Platform#isReady
* @returns {boolean} Whether the device is ready.
*/
isReady: false,
/**
* @ngdoc property
* @name ionic.Platform#isFullScreen
* @returns {boolean} Whether the device is fullscreen.
*/
isFullScreen: false,
/**
* @ngdoc property
* @name ionic.Platform#platforms
* @returns {Array(string)} An array of all platforms found.
*/
platforms: null,
/**
* @ngdoc property
* @name ionic.Platform#grade
* @returns {string} What grade the current platform is.
*/
grade: null,
ua: navigator.userAgent,
/**
* @ngdoc method
* @name ionic.Platform#ready
* @description
* Trigger a callback once the device is ready,
* or immediately if the device is already ready.
* @param {function} callback The function to call.
*/
ready: function(cb) {
// run through tasks to complete now that the device is ready
if(this.isReady) {
@@ -19,6 +52,9 @@
}
},
/**
* @private
*/
detect: function() {
var i, bodyClass = document.body.className;
@@ -34,6 +70,12 @@
document.body.className = bodyClass.trim();
},
/**
* @ngdoc method
* @name ionic.Platform#device
* @description Return the current device (given by cordova).
* @returns {object} The device object.
*/
device: function() {
if(window.device) return window.device;
if(this.isCordova()) console.error('device plugin required');
@@ -69,26 +111,53 @@
}
},
// Check if we are running in Cordova
/**
* @ngdoc method
* @name ionic.Platform#isCordova
* @returns {boolean} Whether we are running on Cordova.
*/
isCordova: function() {
return !(!window.cordova && !window.PhoneGap && !window.phonegap);
},
/**
* @ngdoc method
* @name ionic.Platform#isiPad
* @returns {boolean} Whether we are running on iPad.
*/
isIPad: function() {
return this.ua.toLowerCase().indexOf('ipad') >= 0;
},
/**
* @ngdoc method
* @name ionic.Platform#isiOS
* @returns {boolean} Whether we are running on iOS.
*/
isIOS: function() {
return this.is('ios');
},
/**
* @ngdoc method
* @name ionic.Platform#isAndroid
* @returns {boolean} Whether we are running on Android.
*/
isAndroid: function() {
return this.is('android');
},
/**
* @ngdoc method
* @name ionic.Platform#platform
* @returns {string} The name of the current platform.
*/
platform: function() {
// singleton to get the platform name
if(platformName === null) this.setPlatform(this.device().platform);
return platformName;
},
/**
* @private
*/
setPlatform: function(n) {
if(typeof n != 'undefined' && n !== null && n.length) {
platformName = n.toLowerCase();
@@ -101,12 +170,20 @@
}
},
/**
* @ngdoc method
* @name ionic.Platform#version
* @returns {string} The version of the current device platform.
*/
version: function() {
// singleton to get the platform version
if(platformVersion === null) this.setVersion(this.device().version);
return platformVersion;
},
/**
* @private
*/
setVersion: function(v) {
if(typeof v != 'undefined' && v !== null) {
v = v.split('.');
@@ -152,12 +229,23 @@
return this.ua.toLowerCase().indexOf(type) >= 0;
},
/**
* @ngdoc method
* @name ionic.Platform#exitApp
* @description Exit the app.
*/
exitApp: function() {
this.ready(function(){
navigator.app && navigator.app.exitApp && navigator.app.exitApp();
});
},
/**
* @ngdoc method
* @name ionic.Platform#showStatusBar
* @description Shows or hides the device status bar (in Cordova).
* @param {boolean} shouldShow Whether or not to show the status bar.
*/
showStatusBar: function(val) {
// Only useful when run within cordova
this._showStatusBar = val;
@@ -175,6 +263,13 @@
});
},
/**
* @ngdoc method
* @name ionic.Platform#fullScreen
* @description
* Sets whether the app is fullscreen or not (in Cordova).
* @param {boolean} showFullScreen Whether or not to set the app to fullscreen.
*/
fullScreen: function(showFullScreen, showStatusBar) {
// fullScreen( [showFullScreen[, showStatusBar] ] )
// showFullScreen: default is true if no param provided

4
js/utils/utils.js
View File

@@ -2,7 +2,7 @@
/* for nextUid() function below */
var uid = ['0','0','0'];
/**
* Various utilities used throughout Ionic
*
@@ -33,7 +33,7 @@
/**
* Only call a function once in the given interval.
*
*
* @param func {Function} the function to call
* @param wait {int} how long to wait before/after to allow function calls
* @param immediate {boolean} whether to call immediately or after the wait interval

2
js/views/sliderView.js
View File

@@ -11,7 +11,7 @@
* @name ionicSlideBox
* @module ionic
* @description
* Controller for the {@link ionic.directive:ionTabs} directive.
* Controller for the {@link ionic.directive:ionSlideBox} directive.
*/
(function(ionic) {