Merge pull request #348 from angular-ui/update-sample

timkindberg · timkindberg · commit 8a6f2ee9f3e5 · 2013-08-22T18:18:38.000-07:00
More comments in the html files
diff --git a/sample/contacts.detail.html b/sample/contacts.detail.html
@@ -2,7 +2,11 @@
   <h2>{{contact.name}}</h2>
   <ul>
     <li ng-repeat="item in contact.items">
-      <a ui-sref="contacts.detail.item({contactId:contact.id, itemId:item.id})">{{item.type}}</a>
+
+      <!-- Here's another ui-sref except THIS time we are passing parameters
+           AND inheriting parameters from active ancestor states. So we don't
+           need to resupply the contactId parameter. -->
+      <a ui-sref="contacts.detail.item({itemId:item.id})">{{item.type}}</a>
     </li>
   </ul>
   <div ui-view ng-animate="{enter:'fade-enter'}">
diff --git a/sample/contacts.html b/sample/contacts.html
@@ -4,15 +4,24 @@
       <ul class="nav nav-list">
         <li ng-class="{ active: $state.includes('contacts.list') }"><a ui-sref="contacts.list">All Contacts</a></li>
         <li class="nav-header">Top Contacts</li>
+
+        <!-- This <li> will only add the 'active' class if 'contacts.detail' or its descendants are active
+             AND if it is the link for the active contact (aka contactId) -->
         <li ng-repeat="contact in contacts | limitTo:2"
             ng-class="{ active: $state.includes('contacts.detail') && $stateParams.contactId == contact.id }">
+
+          <!-- Here's a ui-sref that is also providing necessary parameters -->
           <a ui-sref="contacts.detail({contactId:contact.id})">{{contact.name}}</a>
         </li>
       </ul>
       <hr>
       <button class="btn" ng-click="goToRandom()">Show random contact</button>
+
+      <!-- Another named view -->
       <div ui-view="menuTip"></div>
     </div>
   </div>
-  <div class="span9" ui-view ng-animate="{enter:'fade-enter'}"></div>
+
+  <!-- Our unnamed main ui-view for this template -->
+  <div ui-view class="span9" ng-animate="{enter:'fade-enter'}"></div>
 </div>
diff --git a/sample/index.html b/sample/index.html
@@ -1,15 +1,23 @@
 <!doctype html>
+<!-- Our uiRouterSample module defined here -->
 <html lang="en" ng-app="uiRouterSample">
   <head>
     <meta charset="utf-8">
 
+    <!-- using twitter bootstrap, but of course -->
     <link rel="stylesheet" type="text/css" href="bootstrap.min.css">
+    <!-- styles for ng-animate are located here -->
     <link rel="stylesheet" type="text/css" href="styles.css">
 
+    <!-- Include both angular.js and angular-ui-router.js-->
     <script src="../lib/angular-1.1.4.js"></script>
     <script src="../build/angular-ui-router.js"></script>
+
+    <!-- module.js declares the uiRouterSample module and adds items to $rootScope-->
     <script src="module.js"></script>
+    <!-- factory.js defines a 'contacts' http service and a 'utils' global functions service -->
     <script src="factory.js"></script>
+    <!-- state.js takes care of all the state configuration, where all the magic's at-->
     <script src="states.js"></script>
 
     <!-- could easily use a custom property of the state here instead of 'name' -->
@@ -18,17 +26,36 @@
   <body>
     <div class="navbar navbar-fixed-top">
       <div class="navbar-inner"><div class="container">
+
+        <!-- ui-sref is a great directive for linking a state location with an anchor link.
+             You should almost always use ui-sref instead of href on your links when you want
+             then to navigate to a state. When this link is clicked it will take the application
+             to the 'home' state. Behind the scenes the directive also adds the correct href attr
+             and url. -->
         <a class="brand" ui-sref="home">ui-router</a>
         <ul class="nav">
+
+        <!-- Here you can see ui-sref in action again. Also notice the use of $state.includes, which
+             will set the links to 'active' if, for example on the first link, 'contacts' or any of
+             its descendant states are activated. -->
           <li ng-class="{ active: $state.includes('contacts') }"><a ui-sref="contacts.list">Contacts</a></li>
           <li ng-class="{ active: $state.includes('about') }"><a ui-sref="about">About</a></li>
         </ul>
-        <p class="navbar-text pull-right" ui-view="hint"></p>
+
+        <!-- Here is a named ui-view. ui-views don't have to be named, but we'll be populate this
+             on from various different child states and we want a name to help us target. -->
+        <p ui-view="hint" class="navbar-text pull-right"></p>
       </div></div>
     </div>
-    <div class="container" style="margin-top:60px" ui-view ng-animate="{enter:'fade-enter'}"></div>
+
+    <!-- Here is the main ui-view (unnamed) and will be populate by its immediate children's templates
+         unless otherwise explicitly named views are targeted. It's also employing ng-animate. -->
+    <div ui-view class="container" style="margin-top:60px" ng-animate="{enter:'fade-enter'}"></div>
+
+
     <hr>
     <pre>
+      <!-- Here's some values to keep an eye on in the sample in order to understand $state and $stateParams -->
       $state = {{$state.current.name}}
       $stateParams = {{$stateParams}}
       $state full url = {{ $state.$current.url.source }}
