/** * State-based routing for AngularJS * @version v0.2.0-dev-2013-10-05 * @link http://angular-ui.github.com/ * @license MIT License, http://www.opensource.org/licenses/MIT */ (function (window, angular, undefined) { /*jshint globalstrict:true*/ /*global angular:false*/ 'use strict'; var isDefined = angular.isDefined, isFunction = angular.isFunction, isString = angular.isString, isObject = angular.isObject, isArray = angular.isArray, forEach = angular.forEach, extend = angular.extend, copy = angular.copy; function inherit(parent, extra) { return extend(new (extend(function() {}, { prototype: parent }))(), extra); } function merge(dst) { forEach(arguments, function(obj) { if (obj !== dst) { forEach(obj, function(value, key) { if (!dst.hasOwnProperty(key)) dst[key] = value; }); } }); return dst; } /** * Finds the common ancestor path between two states. * * @param {Object} first The first state. * @param {Object} second The second state. * @return {Array} Returns an array of state names in descending order, not including the root. */ function ancestors(first, second) { var path = []; for (var n in first.path) { if (first.path[n] === "") continue; if (!second.path[n]) break; path.push(first.path[n]); } return path; } /** * Merges a set of parameters with all parameters inherited between the common parents of the * current state and a given destination state. * * @param {Object} currentParams The value of the current state parameters ($stateParams). * @param {Object} newParams The set of parameters which will be composited with inherited params. * @param {Object} $current Internal definition of object representing the current state. * @param {Object} $to Internal definition of object representing state to transition to. */ function inheritParams(currentParams, newParams, $current, $to) { var parents = ancestors($current, $to), parentParams, inherited = {}, inheritList = []; for (var i in parents) { if (!parents[i].params || !parents[i].params.length) continue; parentParams = parents[i].params; for (var j in parentParams) { if (inheritList.indexOf(parentParams[j]) >= 0) continue; inheritList.push(parentParams[j]); inherited[parentParams[j]] = currentParams[parentParams[j]]; } } return extend({}, inherited, newParams); } angular.module('ui.router.util', ['ng']); angular.module('ui.router.router', ['ui.router.util']); angular.module('ui.router.state', ['ui.router.router', 'ui.router.util']); angular.module('ui.router', ['ui.router.state']); angular.module('ui.router.compat', ['ui.router']); /** * Service (`ui-util`). Manages resolution of (acyclic) graphs of promises. * @module $resolve * @requires $q * @requires $injector */ $Resolve.$inject = ['$q', '$injector']; function $Resolve( $q, $injector) { var VISIT_IN_PROGRESS = 1, VISIT_DONE = 2, NOTHING = {}, NO_DEPENDENCIES = [], NO_LOCALS = NOTHING, NO_PARENT = extend($q.when(NOTHING), { $$promises: NOTHING, $$values: NOTHING }); /** * Studies a set of invocables that are likely to be used multiple times. * $resolve.study(invocables)(locals, parent, self) * is equivalent to * $resolve.resolve(invocables, locals, parent, self) * but the former is more efficient (in fact `resolve` just calls `study` internally). * See {@link module:$resolve/resolve} for details. * @function * @param {Object} invocables * @return {Function} */ this.study = function (invocables) { if (!isObject(invocables)) throw new Error("'invocables' must be an object"); // Perform a topological sort of invocables to build an ordered plan var plan = [], cycle = [], visited = {}; function visit(value, key) { if (visited[key] === VISIT_DONE) return; cycle.push(key); if (visited[key] === VISIT_IN_PROGRESS) { cycle.splice(0, cycle.indexOf(key)); throw new Error("Cyclic dependency: " + cycle.join(" -> ")); } visited[key] = VISIT_IN_PROGRESS; if (isString(value)) { plan.push(key, [ function() { return $injector.get(key); }], NO_DEPENDENCIES); } else { var params = $injector.annotate(value); forEach(params, function (param) { if (param !== key && invocables.hasOwnProperty(param)) visit(invocables[param], param); }); plan.push(key, value, params); } cycle.pop(); visited[key] = VISIT_DONE; } forEach(invocables, visit); invocables = cycle = visited = null; // plan is all that's required function isResolve(value) { return isObject(value) && value.then && value.$$promises; } return function (locals, parent, self) { if (isResolve(locals) && self === undefined) { self = parent; parent = locals; locals = null; } if (!locals) locals = NO_LOCALS; else if (!isObject(locals)) { throw new Error("'locals' must be an object"); } if (!parent) parent = NO_PARENT; else if (!isResolve(parent)) { throw new Error("'parent' must be a promise returned by $resolve.resolve()"); } // To complete the overall resolution, we have to wait for the parent // promise and for the promise for each invokable in our plan. var resolution = $q.defer(), result = resolution.promise, promises = result.$$promises = {}, values = extend({}, locals), wait = 1 + plan.length/3, merged = false; function done() { // Merge parent values we haven't got yet and publish our own $$values if (!--wait) { if (!merged) merge(values, parent.$$values); result.$$values = values; result.$$promises = true; // keep for isResolve() resolution.resolve(values); } } function fail(reason) { result.$$failure = reason; resolution.reject(reason); } // Short-circuit if parent has already failed if (isDefined(parent.$$failure)) { fail(parent.$$failure); return result; } // Merge parent values if the parent has already resolved, or merge // parent promises and wait if the parent resolve is still in progress. if (parent.$$values) { merged = merge(values, parent.$$values); done(); } else { extend(promises, parent.$$promises); parent.then(done, fail); } // Process each invocable in the plan, but ignore any where a local of the same name exists. for (var i=0, ii=plan.length; i} invocables functions to invoke or `$injector` services to fetch. * @param {Object.} [locals] values to make available to the injectables * @param {Promise.} [parent] a promise returned by another call to `$resolve`. * @param {Object} [self] the `this` for the invoked methods * @return {Promise.} Promise for an object that contains the resolved return value * of all invocables, as well as any inherited and local values. */ this.resolve = function (invocables, locals, parent, self) { return this.study(invocables)(locals, parent, self); }; } angular.module('ui.router.util').service('$resolve', $Resolve); /** * Service. Manages loading of templates. * @constructor * @name $templateFactory * @requires $http * @requires $templateCache * @requires $injector */ $TemplateFactory.$inject = ['$http', '$templateCache', '$injector']; function $TemplateFactory( $http, $templateCache, $injector) { /** * Creates a template from a configuration object. * @function * @name $templateFactory#fromConfig * @methodOf $templateFactory * @param {Object} config Configuration object for which to load a template. The following * properties are search in the specified order, and the first one that is defined is * used to create the template: * @param {string|Function} config.template html string template or function to load via * {@link $templateFactory#fromString fromString}. * @param {string|Function} config.templateUrl url to load or a function returning the url * to load via {@link $templateFactory#fromUrl fromUrl}. * @param {Function} config.templateProvider function to invoke via * {@link $templateFactory#fromProvider fromProvider}. * @param {Object} params Parameters to pass to the template function. * @param {Object} [locals] Locals to pass to `invoke` if the template is loaded via a * `templateProvider`. Defaults to `{ params: params }`. * @return {string|Promise.} The template html as a string, or a promise for that string, * or `null` if no template is configured. */ this.fromConfig = function (config, params, locals) { return ( isDefined(config.template) ? this.fromString(config.template, params) : isDefined(config.templateUrl) ? this.fromUrl(config.templateUrl, params) : isDefined(config.templateProvider) ? this.fromProvider(config.templateProvider, params, locals) : null ); }; /** * Creates a template from a string or a function returning a string. * @function * @name $templateFactory#fromString * @methodOf $templateFactory * @param {string|Function} template html template as a string or function that returns an html * template as a string. * @param {Object} params Parameters to pass to the template function. * @return {string|Promise.} The template html as a string, or a promise for that string. */ this.fromString = function (template, params) { return isFunction(template) ? template(params) : template; }; /** * Loads a template from the a URL via `$http` and `$templateCache`. * @function * @name $templateFactory#fromUrl * @methodOf $templateFactory * @param {string|Function} url url of the template to load, or a function that returns a url. * @param {Object} params Parameters to pass to the url function. * @return {string|Promise.} The template html as a string, or a promise for that string. */ this.fromUrl = function (url, params) { if (isFunction(url)) url = url(params); if (url == null) return null; else return $http .get(url, { cache: $templateCache }) .then(function(response) { return response.data; }); }; /** * Creates a template by invoking an injectable provider function. * @function * @name $templateFactory#fromUrl * @methodOf $templateFactory * @param {Function} provider Function to invoke via `$injector.invoke` * @param {Object} params Parameters for the template. * @param {Object} [locals] Locals to pass to `invoke`. Defaults to `{ params: params }`. * @return {string|Promise.} The template html as a string, or a promise for that string. */ this.fromProvider = function (provider, params, locals) { return $injector.invoke(provider, null, locals || { params: params }); }; } angular.module('ui.router.util').service('$templateFactory', $TemplateFactory); /** * Matches URLs against patterns and extracts named parameters from the path or the search * part of the URL. A URL pattern consists of a path pattern, optionally followed by '?' and a list * of search parameters. Multiple search parameter names are separated by '&'. Search parameters * do not influence whether or not a URL is matched, but their values are passed through into * the matched parameters returned by {@link UrlMatcher#exec exec}. * * Path parameter placeholders can be specified using simple colon/catch-all syntax or curly brace * syntax, which optionally allows a regular expression for the parameter to be specified: * * * ':' name - colon placeholder * * '*' name - catch-all placeholder * * '{' name '}' - curly placeholder * * '{' name ':' regexp '}' - curly placeholder with regexp. Should the regexp itself contain * curly braces, they must be in matched pairs or escaped with a backslash. * * Parameter names may contain only word characters (latin letters, digits, and underscore) and * must be unique within the pattern (across both path and search parameters). For colon * placeholders or curly placeholders without an explicit regexp, a path parameter matches any * number of characters other than '/'. For catch-all placeholders the path parameter matches * any number of characters. * * ### Examples * * * '/hello/' - Matches only if the path is exactly '/hello/'. There is no special treatment for * trailing slashes, and patterns have to match the entire path, not just a prefix. * * '/user/:id' - Matches '/user/bob' or '/user/1234!!!' or even '/user/' but not '/user' or * '/user/bob/details'. The second path segment will be captured as the parameter 'id'. * * '/user/{id}' - Same as the previous example, but using curly brace syntax. * * '/user/{id:[^/]*}' - Same as the previous example. * * '/user/{id:[0-9a-fA-F]{1,8}}' - Similar to the previous example, but only matches if the id * parameter consists of 1 to 8 hex digits. * * '/files/{path:.*}' - Matches any URL starting with '/files/' and captures the rest of the * path into the parameter 'path'. * * '/files/*path' - ditto. * * @constructor * @param {string} pattern the pattern to compile into a matcher. * * @property {string} prefix A static prefix of this pattern. The matcher guarantees that any * URL matching this matcher (i.e. any string for which {@link UrlMatcher#exec exec()} returns * non-null) will start with this prefix. */ function UrlMatcher(pattern) { // Find all placeholders and create a compiled pattern, using either classic or curly syntax: // '*' name // ':' name // '{' name '}' // '{' name ':' regexp '}' // The regular expression is somewhat complicated due to the need to allow curly braces // inside the regular expression. The placeholder regexp breaks down as follows: // ([:*])(\w+) classic placeholder ($1 / $2) // \{(\w+)(?:\:( ... ))?\} curly brace placeholder ($3) with optional regexp ... ($4) // (?: ... | ... | ... )+ the regexp consists of any number of atoms, an atom being either // [^{}\\]+ - anything other than curly braces or backslash // \\. - a backslash escape // \{(?:[^{}\\]+|\\.)*\} - a matched set of curly braces containing other atoms var placeholder = /([:*])(\w+)|\{(\w+)(?:\:((?:[^{}\\]+|\\.|\{(?:[^{}\\]+|\\.)*\})+))?\}/g, names = {}, compiled = '^', last = 0, m, segments = this.segments = [], params = this.params = []; function addParameter(id) { if (!/^\w+(-+\w+)*$/.test(id)) throw new Error("Invalid parameter name '" + id + "' in pattern '" + pattern + "'"); if (names[id]) throw new Error("Duplicate parameter name '" + id + "' in pattern '" + pattern + "'"); names[id] = true; params.push(id); } function quoteRegExp(string) { return string.replace(/[\\\[\]\^$*+?.()|{}]/g, "\\$&"); } this.source = pattern; // Split into static segments separated by path parameter placeholders. // The number of segments is always 1 more than the number of parameters. var id, regexp, segment; while ((m = placeholder.exec(pattern))) { id = m[2] || m[3]; // IE[78] returns '' for unmatched groups instead of null regexp = m[4] || (m[1] == '*' ? '.*' : '[^/]*'); segment = pattern.substring(last, m.index); if (segment.indexOf('?') >= 0) break; // we're into the search part compiled += quoteRegExp(segment) + '(' + regexp + ')'; addParameter(id); segments.push(segment); last = placeholder.lastIndex; } segment = pattern.substring(last); // Find any search parameter names and remove them from the last segment var i = segment.indexOf('?'); if (i >= 0) { var search = this.sourceSearch = segment.substring(i); segment = segment.substring(0, i); this.sourcePath = pattern.substring(0, last+i); // Allow parameters to be separated by '?' as well as '&' to make concat() easier forEach(search.substring(1).split(/[&?]/), addParameter); } else { this.sourcePath = pattern; this.sourceSearch = ''; } compiled += quoteRegExp(segment) + '$'; segments.push(segment); this.regexp = new RegExp(compiled); this.prefix = segments[0]; } /** * Returns a new matcher for a pattern constructed by appending the path part and adding the * search parameters of the specified pattern to this pattern. The current pattern is not * modified. This can be understood as creating a pattern for URLs that are relative to (or * suffixes of) the current pattern. * * ### Example * The following two matchers are equivalent: * ``` * new UrlMatcher('/user/{id}?q').concat('/details?date'); * new UrlMatcher('/user/{id}/details?q&date'); * ``` * * @param {string} pattern The pattern to append. * @return {UrlMatcher} A matcher for the concatenated pattern. */ UrlMatcher.prototype.concat = function (pattern) { // Because order of search parameters is irrelevant, we can add our own search // parameters to the end of the new pattern. Parse the new pattern by itself // and then join the bits together, but it's much easier to do this on a string level. return new UrlMatcher(this.sourcePath + pattern + this.sourceSearch); }; UrlMatcher.prototype.toString = function () { return this.source; }; /** * Tests the specified path against this matcher, and returns an object containing the captured * parameter values, or null if the path does not match. The returned object contains the values * of any search parameters that are mentioned in the pattern, but their value may be null if * they are not present in `searchParams`. This means that search parameters are always treated * as optional. * * ### Example * ``` * new UrlMatcher('/user/{id}?q&r').exec('/user/bob', { x:'1', q:'hello' }); * // returns { id:'bob', q:'hello', r:null } * ``` * * @param {string} path The URL path to match, e.g. `$location.path()`. * @param {Object} searchParams URL search parameters, e.g. `$location.search()`. * @return {Object} The captured parameter values. */ UrlMatcher.prototype.exec = function (path, searchParams) { var m = this.regexp.exec(path); if (!m) return null; var params = this.params, nTotal = params.length, nPath = this.segments.length-1, values = {}, i; if (nPath !== m.length - 1) throw new Error("Unbalanced capture group in route '" + this.source + "'"); for (i=0; i} An array of parameter names. Must be treated as read-only. If the * pattern has no parameters, an empty array is returned. */ UrlMatcher.prototype.parameters = function () { return this.params; }; /** * Creates a URL that matches this pattern by substituting the specified values * for the path and search parameters. Null values for path parameters are * treated as empty strings. * * ### Example * ``` * new UrlMatcher('/user/{id}?q').format({ id:'bob', q:'yes' }); * // returns '/user/bob?q=yes' * ``` * * @param {Object} values the values to substitute for the parameters in this pattern. * @return {string} the formatted URL (path and optionally search part). */ UrlMatcher.prototype.format = function (values) { var segments = this.segments, params = this.params; if (!values) return segments.join(''); var nPath = segments.length-1, nTotal = params.length, result = segments[0], i, search, value; for (i=0; i= 0) throw new Error("State must have a valid name"); if (states[name]) throw new Error("State '" + name + "'' is already defined"); for (var key in stateBuilder) { state[key] = stateBuilder[key](state); } states[name] = state; // Register the state in the global state list and with $urlRouter if necessary. if (!state['abstract'] && state.url) { $urlRouterProvider.when(state.url, ['$match', '$stateParams', function ($match, $stateParams) { if ($state.$current.navigable != state || !equalForKeys($match, $stateParams)) { $state.transitionTo(state, $match, false); } }]); } return state; } // Implicit root state that is always active root = registerState({ name: '', url: '^', views: null, 'abstract': true }); root.navigable = null; // .state(state) // .state(name, state) this.state = state; function state(name, definition) { /*jshint validthis: true */ if (isObject(name)) definition = name; else definition.name = name; registerState(definition); return this; } // $urlRouter is injected just to ensure it gets instantiated this.$get = $get; $get.$inject = ['$rootScope', '$q', '$view', '$injector', '$resolve', '$stateParams', '$location', '$urlRouter']; function $get( $rootScope, $q, $view, $injector, $resolve, $stateParams, $location, $urlRouter) { var TransitionSuperseded = $q.reject(new Error('transition superseded')); var TransitionPrevented = $q.reject(new Error('transition prevented')); root.locals = { resolve: null, globals: { $stateParams: {} } }; $state = { params: {}, current: root.self, $current: root, transition: null }; $state.go = function go(to, params, options) { return this.transitionTo(to, params, extend({ inherit: true, relative: $state.$current }, options)); }; $state.transitionTo = function transitionTo(to, toParams, options) { if (!isDefined(options)) options = (options === true || options === false) ? { location: options } : {}; toParams = toParams || {}; options = extend({ location: true, inherit: false, relative: null }, options); var toState = findState(to, options.relative); if (!isDefined(toState)) { if (options.relative) throw new Error("Could not resolve '" + to + "' from state '" + options.relative + "'"); throw new Error("No such state '" + to + "'"); } if (toState['abstract']) throw new Error("Cannot transition to abstract state '" + to + "'"); if (options.inherit) toParams = inheritParams($stateParams, toParams || {}, $state.$current, toState); to = toState; var toPath = to.path, from = $state.$current, fromParams = $state.params, fromPath = from.path; // Starting from the root of the path, keep all levels that haven't changed var keep, state, locals = root.locals, toLocals = []; for (keep = 0, state = toPath[keep]; state && state === fromPath[keep] && equalForKeys(toParams, fromParams, state.ownParams); keep++, state = toPath[keep]) { locals = toLocals[keep] = state.locals; } // If we're going to the same state and all locals are kept, we've got nothing to do. // But clear 'transition', as we still want to cancel any other pending transitions. // TODO: We may not want to bump 'transition' if we're called from a location change that we've initiated ourselves, // because we might accidentally abort a legitimate transition initiated from code? if (to === from && locals === from.locals) { $state.transition = null; return $q.when($state.current); } // Normalize/filter parameters before we pass them to event handlers etc. toParams = normalize(to.params, toParams || {}); // Broadcast start event and cancel the transition if requested var evt = $rootScope.$broadcast('$stateChangeStart', to.self, toParams, from.self, fromParams); if (evt.defaultPrevented) return TransitionPrevented; // Resolve locals for the remaining states, but don't update any global state just // yet -- if anything fails to resolve the current state needs to remain untouched. // We also set up an inheritance chain for the locals here. This allows the view directive // to quickly look up the correct definition for each view in the current state. Even // though we create the locals object itself outside resolveState(), it is initially // empty and gets filled asynchronously. We need to keep track of the promise for the // (fully resolved) current locals, and pass this down the chain. var resolved = $q.when(locals); for (var l=keep; l=keep; l--) { exiting = fromPath[l]; if (exiting.self.onExit) { $injector.invoke(exiting.self.onExit, exiting.self, exiting.locals.globals); } exiting.locals = null; } // Enter 'to' states not kept for (l=keep; l