From 1d7adac7a5546603fd42c1e581c696cb88324b8f Mon Sep 17 00:00:00 2001 From: Igor Minar Date: Fri, 8 Apr 2011 09:54:29 -0700 Subject: fix $location service docs and examples --- src/service/location.js | 114 +++++++++++++++++++++++++++++------------------- 1 file changed, 68 insertions(+), 46 deletions(-) (limited to 'src') diff --git a/src/service/location.js b/src/service/location.js index a5875b72..f80cd697 100644 --- a/src/service/location.js +++ b/src/service/location.js @@ -8,31 +8,61 @@ var URL_MATCH = /^(file|ftp|http|https):\/\/(\w+:{0,1}\w*@)?([\w\.-]*)(:([0-9]+) * @name angular.service.$location * @requires $browser * - * @property {string} href - * @property {string} protocol - * @property {string} host - * @property {number} port - * @property {string} path - * @property {Object.} search - * @property {string} hash - * @property {string} hashPath - * @property {Object.} hashSearch + * @property {string} href The full URL of the current location. + * @property {string} protocol The protocol part of the URL (e.g. http or https). + * @property {string} host The host name, ip address or FQDN of the current location. + * @property {number} port The port number of the current location (e.g. 80, 443, 8080). + * @property {string} path The path of the current location (e.g. /myapp/inbox). + * @property {Object.} search Map of query parameters (e.g. {user:"foo", page:23}). + * @property {string} hash The fragment part of the URL of the current location (e.g. #foo). + * @property {string} hashPath Similar to `path`, but located in the `hash` fragment + * (e.g. ../foo#/some/path => /some/path). + * @property {Object.} hashSearch Similar to `search` but located in `hash` + * fragment (e.g. .../foo#/some/path?hashQuery=param => {hashQuery: "param"}). * * @description * Parses the browser location url and makes it available to your application. - * Any changes to the url are reflected into $location service and changes to - * $location are reflected to url. + * Any changes to the url are reflected into `$location` service and changes to + * `$location` are reflected in the browser location url. + * * Notice that using browser's forward/back buttons changes the $location. * * @example - clear hash | - test hash
- - 
$location = {{$location}}
+
+ test hash| + reset hash
+ + 
$location = {{$location}}
+
+ it('should initialize the input field', function() { + expect(using('.doc-example-live').element('input[name=$location.hash]').val()). + toBe('!angular.service.$location'); + }); + + + it('should bind $location.hash to the input field', function() { + using('.doc-example-live').input('$location.hash').enter('foo'); + expect(browser().location().hash()).toBe('foo'); + }); + + + it('should set the hash to a test string with test link is presed', function() { + using('.doc-example-live').element('#ex-test').click(); + expect(using('.doc-example-live').element('input[name=$location.hash]').val()). + toBe('myPath?name=misko'); + }); + + it('should reset $location when reset link is pressed', function() { + using('.doc-example-live').input('$location.hash').enter('foo'); + using('.doc-example-live').element('#ex-reset').click(); + expect(using('.doc-example-live').element('input[name=$location.hash]').val()). + toBe('!angular.service.$location'); + }); + */ @@ -61,22 +91,18 @@ angularServiceInject("$location", function($browser) { * @methodOf angular.service.$location * * @description - * Update location object - * Does not immediately update the browser - * Browser is updated at the end of $eval() + * Updates the location object. * - * @example - - - scope.$location.update('http://www.angularjs.org/path#hash?search=x'); - scope.$location.update({host: 'www.google.com', protocol: 'https'}); - scope.$location.update({hashPath: '/path', hashSearch: {a: 'b', x: true}}); - - - - + * Does not immediately update the browser. Instead the browser is updated at the end of $eval() + * cycle. * - * @param {(string|Object)} href Full href as a string or object with properties + * 
+       $location.update('http://www.angularjs.org/path#hash?search=x');
+       $location.update({host: 'www.google.com', protocol: 'https'});
+       $location.update({hashPath: '/path', hashSearch: {a: 'b', x: true}});
+
+ * + * @param {string|Object} href Full href as a string or object with properties */ function update(href) { if (isString(href)) { @@ -103,24 +129,20 @@ angularServiceInject("$location", function($browser) { * @methodOf angular.service.$location * * @description - * Update location hash part + * Updates the hash fragment part of the url. + * * @see update() * - * @example - - - scope.$location.updateHash('/hp') + * 
+       scope.$location.updateHash('/hp')
          ==> update({hashPath: '/hp'})
-        scope.$location.updateHash({a: true, b: 'val'})
+       scope.$location.updateHash({a: true, b: 'val'})
          ==> update({hashSearch: {a: true, b: 'val'}})
-        scope.$location.updateHash('/hp', {a: true})
+       scope.$location.updateHash('/hp', {a: true})
          ==> update({hashPath: '/hp', hashSearch: {a: true}})
-      
-      
-      
-    
+
* - * @param {(string|Object)} path A hashPath or hashSearch object + * @param {string|Object} path A hashPath or hashSearch object * @param {Object=} search A hashSearch object */ function updateHash(path, search) { @@ -152,11 +174,11 @@ angularServiceInject("$location", function($browser) { * - `$location.hash` * - everything else * - * @example - * 
-   *   scope.$location.href = 'http://www.angularjs.org/path#a/b'
-   *
- * immediately after this call, other properties are still the old ones... + * Keep in mind that if the following code is executed: + * + * scope.$location.href = 'http://www.angularjs.org/path#a/b' + * + * immediately afterwards all other properties are still the old ones... * * This method checks the changes and update location to the consistent state */ -- cgit v1.2.3