<@ if isDirective @>Attr<@ else @>Param<@ endif @>
@@ -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 @>)`
+<$ fn.name $>(<@- for param in fn.params @><$ sep() $>
+ <@- if param.type.optional @>[<@ endif -@>
+ <$ param.name $>
+ <@- if param.type.optional @>]<@ endif -@>
+ <@ endfor @>)<@ if fn.alias @>(alias: <$ fn.alias $>)<@ endif @>
<@ endmacro -@>
<@- macro typeInfo(fn) -@>
diff --git a/docs/templates/lib/methods.template.html b/docs/templates/lib/methods.template.html
index ec8ee172fd..1833f2cd2e 100644
--- a/docs/templates/lib/methods.template.html
+++ b/docs/templates/lib/methods.template.html
@@ -3,7 +3,9 @@
<@- for method in doc.methods @>
-### <$ functionSyntax(method) $>
+
+ <$ functionSyntax(method) $>
+
<$ method.description $>
diff --git a/js/ext/angular/src/directive/ionicContent.js b/js/ext/angular/src/directive/ionicContent.js
index 95d58b34b2..1965f7e5c8 100644
--- a/js/ext/angular/src/directive/ionicContent.js
+++ b/js/ext/angular/src/directive/ionicContent.js
@@ -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
diff --git a/js/ext/angular/src/directive/ionicLoading.js b/js/ext/angular/src/directive/ionicLoading.js
index 712af9cfb1..145d696c01 100644
--- a/js/ext/angular/src/directive/ionicLoading.js
+++ b/js/ext/angular/src/directive/ionicLoading.js
@@ -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: '
' +
+ template: '
' +
'
' +
'
' +
'
'
diff --git a/js/ext/angular/src/directive/ionicRadio.js b/js/ext/angular/src/directive/ionicRadio.js
index 730aa057fc..934edcc601 100644
--- a/js/ext/angular/src/directive/ionicRadio.js
+++ b/js/ext/angular/src/directive/ionicRadio.js
@@ -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
diff --git a/js/ext/angular/src/directive/ionicSlideBox.js b/js/ext/angular/src/directive/ionicSlideBox.js
index 4d62dea1e4..8f7879b3b3 100644
--- a/js/ext/angular/src/directive/ionicSlideBox.js
+++ b/js/ext/angular/src/directive/ionicSlideBox.js
@@ -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:
*
diff --git a/js/ext/angular/src/directive/ionicViewState.js b/js/ext/angular/src/directive/ionicViewState.js
index ada4388e1b..5f70acb814 100644
--- a/js/ext/angular/src/directive/ionicViewState.js
+++ b/js/ext/angular/src/directive/ionicViewState.js
@@ -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
- * , which will create a topbar that updates as the application state changes.
+ * , which will create a topbar that updates as the application state changes.
* We can also add some styles and set up animations:
- *
+ *
* ```html
*
*
@@ -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">
- *
+ *
*
*
*
@@ -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
+ *
+ *
+ *
+ *
+ * Hello!
+ *
+ *
+ *
+ * ```
+ *
+ * @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:
- *
- *
*
* @param {string=} name A view name. The name should be unique amongst the other views in the
diff --git a/js/ext/angular/src/service/decorators/location.js b/js/ext/angular/src/service/decorators/location.js
index a1cbdf3f58..ebd23b4c57 100644
--- a/js/ext/angular/src/service/decorators/location.js
+++ b/js/ext/angular/src/service/decorators/location.js
@@ -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) {
diff --git a/js/ext/angular/src/service/delegates/ionicScrollDelegate.js b/js/ext/angular/src/service/delegates/ionicScrollDelegate.js
index 82222bd93e..9a12326dc4 100644
--- a/js/ext/angular/src/service/delegates/ionicScrollDelegate.js
+++ b/js/ext/angular/src/service/delegates/ionicScrollDelegate.js
@@ -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
+ *
+ *
+ *
+ * ```
+ * ```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
*/
diff --git a/js/ext/angular/src/service/ionicBind.js b/js/ext/angular/src/service/ionicBind.js
index a06ce69abd..f76eb8f81d 100644
--- a/js/ext/angular/src/service/ionicBind.js
+++ b/js/ext/angular/src/service/ionicBind.js
@@ -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) {
diff --git a/js/ext/angular/src/service/ionicGesture.js b/js/ext/angular/src/service/ionicGesture.js
index 0c222b6483..14bcbcab88 100644
--- a/js/ext/angular/src/service/ionicGesture.js
+++ b/js/ext/angular/src/service/ionicGesture.js
@@ -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);
}
diff --git a/js/ext/angular/src/service/ionicLoading.js b/js/ext/angular/src/service/ionicLoading.js
index f96523ea5d..2ca0aeff59 100644
--- a/js/ext/angular/src/service/ionicLoading.js
+++ b/js/ext/angular/src/service/ionicLoading.js
@@ -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 = {
diff --git a/js/ext/angular/src/service/ionicModal.js b/js/ext/angular/src/service/ionicModal.js
index 0c09c3e1a3..b60838c8e2 100644
--- a/js/ext/angular/src/service/ionicModal.js
+++ b/js/ext/angular/src/service/ionicModal.js
@@ -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
+ *
+ * ```
+ * ```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;
});
}
diff --git a/js/ext/angular/src/service/ionicPlatform.js b/js/ext/angular/src/service/ionicPlatform.js
index be9db1ae73..5855a73ba4 100644
--- a/js/ext/angular/src/service/ionicPlatform.js
+++ b/js/ext/angular/src/service/ionicPlatform.js
@@ -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();
diff --git a/js/ext/angular/src/service/ionicTemplateLoad.js b/js/ext/angular/src/service/ionicTemplateLoad.js
index 9ac74f82dc..a134b9b289 100644
--- a/js/ext/angular/src/service/ionicTemplateLoad.js
+++ b/js/ext/angular/src/service/ionicTemplateLoad.js
@@ -1,5 +1,8 @@
angular.module('ionic.service.templateLoad', [])
+/**
+ * @private
+ */
.factory('$ionicTemplateLoader', ['$q', '$http', '$templateCache', function($q, $http, $templateCache) {
return {
load: function(url) {
diff --git a/js/ext/angular/src/service/ionicView.js b/js/ext/angular/src/service/ionicView.js
index 8ace0d225e..6af752b871 100644
--- a/js/ext/angular/src/service/ionicView.js
+++ b/js/ext/angular/src/service/ionicView.js
@@ -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
diff --git a/js/utils/dom.js b/js/utils/dom.js
index 64bbb607d0..28e56a4851 100644
--- a/js/utils/dom.js
+++ b/js/utils/dom.js
@@ -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;
diff --git a/js/utils/events.js b/js/utils/events.js
index d2def899ec..68bce27d8c 100644
--- a/js/utils/events.js
+++ b/js/utils/events.js
@@ -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);
},
diff --git a/js/utils/platform.js b/js/utils/platform.js
index f50fdb08d7..64d5d2a500 100644
--- a/js/utils/platform.js
+++ b/js/utils/platform.js
@@ -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
diff --git a/js/utils/utils.js b/js/utils/utils.js
index 18867dcb79..5e2009e841 100644
--- a/js/utils/utils.js
+++ b/js/utils/utils.js
@@ -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
diff --git a/js/views/sliderView.js b/js/views/sliderView.js
index 159c2d5215..6a1fb66574 100644
--- a/js/views/sliderView.js
+++ b/js/views/sliderView.js
@@ -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) {