A lightweight extension for AngularJS $route service which supports tree-like nested views and routes hierarchy, and advanced loading flow handling.
Example site is located here:
The sources of this example can be found in the folder /example.
You can install the library via Bower:
bower install angular-route-segment
Or using npm:
npm install angular-route-segment
Or using this CDN link (thanks to cdnjs.com):
<script src="//cdnjs.cloudflare.com/ajax/libs/angular-route-segment/1.5.0/angular-route-segment.min.js"></script>Tested with AngularJS 1.2.21, 1.3.16, 1.4.9, 1.5.0.
This library is intended to provide the lacking functionality of nested routing to AngularJS applications. It is widely known, there are no ways to keep the parent state unchanged when children are updated via routing mechanics - the $route service re-creates the whole scope after a route is changed, losing its state completely. route-segment gives you a way to handle this.
The library provides two pieces of code: $routeSegment service and app-view-segment directive. Both are placed in their own modules which you must include as dependencies in your app module:
var app = angular.module('app', ['ngRoute', 'route-segment', 'view-segment']);$routeSegment is a layer on top of built-in Angular $route service and is meant to be used instead of it. Its provider exposes configuration methods which can be used to traverse the tree of route segments and setup it properly.
app.config(function ($routeSegmentProvider) {
$routeSegmentProvider.
when('/section1', 's1').
when('/section1/prefs', 's1.prefs').
when('/section1/:id', 's1.itemInfo').
when('/section1/:id/edit', 's1.itemInfo.edit').
when('/section2', 's2').
segment('s1', {
templateUrl: 'templates/section1.html',
controller: MainCtrl}).
within().
segment('home', {
default: true,
templateUrl: 'templates/section1/home.html'}).
segment('itemInfo', {
templateUrl: 'templates/section1/item.html',
controller: Section1ItemCtrl,
dependencies: ['id']}).
within().
segment('overview', {
default: true
templateUrl: 'templates/section1/item/overview.html'}).
segment('edit', {
templateUrl: 'templates/section1/item/edit.html'}).
up().
segment('prefs', {
templateUrl: 'templates/section1/prefs.html'}).
up().
segment('s2', {
templateUrl: 'templates/section2.html',
controller: MainCtrl});Alternatively, you can use this syntax instead of traversing (useful if you want modules to have their own separately defined routes):
$routeSegmentProvider.segment('s1', {
templateUrl: 'templates/section1.html',
controller: MainCtrl});
$routeSegmentProvider.within('s1').segment('home', {
templateUrl: 'templates/section1/home.html'});
$routeSegmentProvider.within('s1').segment('itemInfo', {
templateUrl: 'templates/section1/item.html',
controller: Section1ItemCtrl,
dependencies: ['id']});
$routeSegmentProvider.within('s1').within('itemInfo').segment('overview', {
templateUrl: 'templates/section1/item/overview.html'});Then, any app-view-segment tags (which are similar to built-in ng-view) in the DOM will be populated with the corresponding route segment item. You must provide a segment index as an argument to this directive to make it aware about which segment level in the tree it should be linked to.
index.html:
<ul>
<li ng-class="{active: $routeSegment.startsWith('s1')}">
<a href="/section1">Section 1</a>
</li>
<li ng-class="{active: $routeSegment.startsWith('s2')}">
<a href="/section2">Section 2</a>
</li>
</ul>
<div id="contents" app-view-segment="0"></div>section1.html: (it will be loaded to div#contents in index.html)
<h4>Section 1</h4>
Section 1 contents.
<div app-view-segment="1"></div>...etc. You can reach any nesting level here. Every view will be handled independently, keeping the state of top-level views.
You can also use filters to define link hrefs. It will resolve segment URLs automatically:
<ul>
<li ng-class="{active: ('s1' | routeSegmentStartsWith)}">
<a href="{{ 's1' | routeSegmentUrl }}">Section 1</a>
</li>
<li ng-class="{active: ('s2' | routeSegmentStartsWith)}">
<a href="{{ 's2' | routeSegmentUrl }}">Section 2</a>
</li>
</ul>While it seems that this library has very similar goal to what UI-Router provides, there are some important differences between their implementations, though.
UI-Router implements its own URL routing mechanics with its own "state" concept on top of it. angular-route-segment doesn't try to replace something in AngularJS. It is based on built-in $route engine, so that it tries to extend it rather than to replace. $routeSegmentProvider.when method is just a shorthand to $routeProvider.when with the simplified syntax. Inner segment-handling logic is built on top of events propagated by $route service, with internal usage of some route params from it.
Such approach makes it possible to accomplish the desired nested routing task in more simpler manner, which produces less code, less complexity and potential bugs, provides better cohesion with Angular core engine and is easier to understand, use and debug.
Please note that you may read the test specs to learn features usage.
A hash object which can be used to set up the service on config stage:
-
options.autoLoadTemplates
When true, it will resolve
templateUrlautomatically via $http service and put its contents intotemplate. -
options.strictMode
When true, all attempts to call
withinmethod on non-existing segments will throw an error (you would usually want this behavior in production). When false, it will transparently create new empty segment (can be useful in isolated tests).
The shorthand for $routeProvider.when() method with specified fully qualified route name.
-
path
Route URL, e.g.
/foo/bar -
name
Fully qualified route name, e.g.
foo.bar -
route
Mapping information object to be assigned to
$route.currenton route match.
Adds new segment at current pointer level.
-
name
Name of a segment item, e.g.
bar -
params
Segment's parameters hash. The following params are supported:
templateprovides HTML for the given segment view; iftemplateis a function, it will be called with injectable arguments;templateUrlis a template which should be fetched from the network via this URL; iftemplateUrlis a function, it will be called with injectable arguments; if neithertemplatenortemplateUrlparameters are defined, the DOM element's transcluded content will be used;controlleris attached to the given segment view when compiled and linked, this can be any controller definition AngularJS supports;controllerAsis a controller alias name, if present the controller will be published to scope under the controllerAs name;dependenciesis an array of route param names which are forcing the view to recreate when changed;watcheris a $watch-function for recreating the view when its returning value is changed;resolveis a hash of functions or injectable names which should be resolved prior to instantiating the template and the controller;untilResolvedis the alternate set of params (e.g.templateandcontroller) which should be used before resolving is completed;resolveFailedis the alternate set of params which should be used if resolving failed;defaultis a boolean value which can be set to true if this child segment should be loaded by default when no child is specified in the route.
Traverses into an existing segment, so that subsequent segment calls will add new segments as its descendants.
-
childName
An existing segment's name. An optional argument. If undefined, then the last added segment is selected.
Traverses up in the tree.
Traverses to the root.
Fully qualified name of current active route.
A copy of $routeParams in its state of the latest successful segment update. It may be not equal to $routeParams
while some resolving is not completed yet. Should be used instead of original $routeParams in most cases.
An array of segments splitted by each level separately. Each item contains the following properties:
nameis the name of a segment;paramsis the config params hash of a segment;localsis a hash which contains resolve results if any;reloadis a function to reload a segment (restart resolving, reinstantiate a controller, etc)
Helper method for checking whether current route starts with the given string.
Helper method for checking whether current route contains the given string.
A method for reverse routing which can return the route URL for the specified segment name.
-
segmentName
The name of a segment as defined in
when(). -
routeParams
Route params hash to be put into route URL template. Standard
$routeParamsobject is used first; it is extended (overrided) with this provided object then.
$routeSegment.getSegmentUrl('s1'); // -> '/section1'
$routeSegment.getSegmentUrl('s1.prefs'); // -> '/section1/prefs'
$routeSegment.getSegmentUrl('s1.itemInfo', {id: 123}); // -> '/section1/123'
$routeSegment.getSegmentUrl('s1.itemInfo.edit', {id: 123}); // -> '/section1/123/edit'ATTENTION: filters are not stateless. While they are not intended to work with complex data structures, it can impact performance anyway. See more info at angular.js commit fca6be71.
A wrapper for $routeSegment.name == value.
<li ng-class="{active: ('s1' | routeSegmentEqualsTo)}">A wrapper for $routeSegment.startsWith(value).
<li ng-class="{active: ('s1' | routeSegmentStartsWith)}">A wrapper for $routeSegment.contains(value).
<li ng-class="{active: ('s1' | routeSegmentContains)}">A wrapper for $routeSegment.$routeParams[value].
<li ng-class="{active: ('s1.itemInfo' | routeSegmentEqualsTo) && ('id' | routeSegmentParam) == 123}">A wrapper for $routeSegment.getSegmentUrl.
<a ng-href="{{ 's1.home' | routeSegmentUrl }}">
<a ng-href="{{ 's1.itemInfo.edit' | routeSegmentUrl: {id: 123} }}">The MIT License (MIT)
Copyright (c) 2013 Artem Chivchalov
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent