From 13f92de6246a0af8450fde84b209211a56397fda Mon Sep 17 00:00:00 2001
From: Vojta Jina
Date: Tue, 30 Aug 2011 11:47:24 +0200
Subject: feat(docs): use html5 history api for all routing in the docs app

- Configure our docs app to use new $location with html5 history api!

- Update simple node web server to serve index.html for all links
  (rewritting).

- Update .htaccess file to serve index.html for all links (rewritting).

- At runtime determine the base href path and attach it to the DOM. We
  needed the absolute URL to get all browsers to work well.

- Because of the above, we also need to dynamically determine all needed
  js/css resources and add them to the DOM. This was needed because FF6
  would eagerly fetch resources with wrong URL since the base element is
  added to the dom at runtime.

- All content html files were moved to the partials directory, because
  with the new html5 urls it was impossible to tell if request for
  http://domain/api/angular.filter.html was an html5 url for the html
  filter doc page, or an xhr/appcache request for the content html file
  for the html filter.

f
---
 docs/src/appCache.js          |  4 +-
 docs/src/gen-docs.js          | 21 +++--------
 docs/src/ngdoc.js             | 12 +++---
 docs/src/templates/.htaccess  |  6 ++-
 docs/src/templates/docs.js    | 11 +++---
 docs/src/templates/index.html | 86 +++++++++++++++++++++++++++++++------------
 6 files changed, 88 insertions(+), 52 deletions(-)

(limited to 'docs/src')

diff --git a/docs/src/appCache.js b/docs/src/appCache.js
index ed35eb79..7b21624e 100644
--- a/docs/src/appCache.js
+++ b/docs/src/appCache.js
@@ -29,7 +29,7 @@ function appCache(path) {
 
     var resultPostfix = ["",
                          "FALLBACK:",
-                         "/offline.html",
+                         "/ /build/docs/index.html",
                          "",
                          "# allow access to google analytics and twitter when we are online",
                          "NETWORK:",
@@ -68,7 +68,7 @@ function appCacheTemplate() {
           "img/yellow_bkgnd.jpg",
           "",
           "FALLBACK:",
-          "/ offline.html",
+          "/ /build/docs/offline.html",
           "",
           "# allow access to google analytics and twitter when we are online",
           "NETWORK:",
diff --git a/docs/src/gen-docs.js b/docs/src/gen-docs.js
index e1778bb7..c7b37025 100755
--- a/docs/src/gen-docs.js
+++ b/docs/src/gen-docs.js
@@ -22,7 +22,7 @@ writer.makeDir('build/docs/syntaxhighlighter').then(function() {
   ngdoc.merge(docs);
   var fileFutures = [];
   docs.forEach(function(doc){
-    fileFutures.push(writer.output(doc.section + '/' + doc.id + '.html', doc.html()));
+    fileFutures.push(writer.output('partials/' + doc.section + '/' + doc.id + '.html', doc.html()));
   });
 
   writeTheRest(fileFutures);
@@ -43,28 +43,19 @@ function writeTheRest(writesFuture) {
   writesFuture.push(writer.copyDir('img'));
   writesFuture.push(writer.copyDir('examples'));
 
-  var manifest = 'manifest="appcache.manifest"',
-      jq = '<script src="jquery.min.js"></script>',
-      ngMin = '<script src="../angular.min.js" ng:autobind></script>',
-      ng = '<script src="../angular.js" ng:autobind></script>';
+  var manifest = 'manifest="/build/docs/appcache.manifest"';
 
   writesFuture.push(writer.copy('docs/src/templates/index.html', 'build/docs/index.html',
-                                writer.replace, {'doc:manifest': manifest,
-                                                 '<!-- angular script place holder -->': ngMin}));
+                                writer.replace, {'doc:manifest': manifest}));
 
   writesFuture.push(writer.copy('docs/src/templates/index.html', 'build/docs/index-jq.html',
-                                writer.replace, {'doc:manifest': manifest,
-                                                 '<!-- angular script place holder -->': ngMin,
-                                                 '<!-- jquery place holder -->': jq}));
+                                writer.replace, {'doc:manifest': manifest}));
 
   writesFuture.push(writer.copy('docs/src/templates/index.html', 'build/docs/index-debug.html',
-                                writer.replace, {'doc:manifest': '',
-                                                 '<!-- angular script place holder -->': ng}));
+                                writer.replace, {'doc:manifest': ''}));
 
   writesFuture.push(writer.copy('docs/src/templates/index.html', 'build/docs/index-jq-debug.html',
-                                writer.replace, {'doc:manifest': '',
-                                                 '<!-- angular script place holder -->': ng,
-                                                 '<!-- jquery place holder -->': jq}));
+                                writer.replace, {'doc:manifest': ''}));
 
   writesFuture.push(writer.copyTpl('offline.html'));
   writesFuture.push(writer.copyTpl('docs-scenario.html'));
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index 1045d39d..abe5e1d7 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -133,7 +133,7 @@ Doc.prototype = {
 
             if (!isFullUrl) self.links.push(absUrl);
 
-            return '<a href="' + (isFullUrl ? '' + url : '#!/' + absUrl) + '">'
+            return '<a href="' + absUrl + '">'
               + (isAngular ? '<code>' : '')
               + (title || url).replace(/\n/g, ' ')
               + (isAngular ? '</code>' : '')
@@ -243,7 +243,7 @@ Doc.prototype = {
       }
       dom.h('Dependencies', self.requires, function(require){
         dom.tag('code', function(){
-          dom.tag('a', {href:"#!/api/angular.service." + require.name}, require.name);
+          dom.tag('a', {href: 'api/angular.service.' + require.name}, require.name);
         });
         dom.html(require.text);
       });
@@ -570,23 +570,23 @@ function scenarios(docs){
   var specs = [];
 
   specs.push('describe("angular+jqlite", function() {');
-  appendSpecs('index.html');
+  appendSpecs('');
   specs.push('});');
 
   specs.push('');
   specs.push('');
 
   specs.push('describe("angular+jquery", function() {');
-  appendSpecs('index-jq.html');
+  appendSpecs('index-jq.html#!/');
   specs.push('});');
 
   return specs.join('\n');
 
-  function appendSpecs(htmlFile) {
+  function appendSpecs(urlPrefix) {
     docs.forEach(function(doc){
       specs.push('  describe("' + doc.section + '/' + doc.id + '", function(){');
       specs.push('    beforeEach(function(){');
-      specs.push('      browser().navigateTo("' + htmlFile + '#!/' + doc.section + '/' + doc.id + '");');
+      specs.push('      browser().navigateTo("' + urlPrefix + doc.section + '/' + doc.id + '");');
       specs.push('    });');
       specs.push('  ');
       doc.scenarios.forEach(function(scenario){
diff --git a/docs/src/templates/.htaccess b/docs/src/templates/.htaccess
index 87487e9e..9f9a152c 100644
--- a/docs/src/templates/.htaccess
+++ b/docs/src/templates/.htaccess
@@ -8,4 +8,8 @@
 
 RewriteEngine on
 RewriteCond %{HTTP_COOKIE}      ng-offline="NG_VERSION_FULL"
-RewriteRule appcache.manifest   appcache-offline.manifest
\ No newline at end of file
+RewriteRule appcache.manifest   appcache-offline.manifest
+
+
+## HTML5 URL Support ##
+RewriteRule ^(guide|api|cookbook|misc|tutorial)(/.*)?$    index.html
diff --git a/docs/src/templates/docs.js b/docs/src/templates/docs.js
index d1069a77..505aed60 100644
--- a/docs/src/templates/docs.js
+++ b/docs/src/templates/docs.js
@@ -4,7 +4,8 @@ function DocsController($location, $browser, $window, $cookies) {
 
   var self = this,
       OFFLINE_COOKIE_NAME = 'ng-offline',
-      DOCS_PATH = /^\/(api)|(guide)|(cookbook)|(misc)|(tutorial)/;
+      DOCS_PATH = /^\/(api)|(guide)|(cookbook)|(misc)|(tutorial)/,
+      INDEX_PATH = /^(\/|\/index[^\.]*.html)$/;
 
   this.$location = $location;
 
@@ -13,7 +14,7 @@ function DocsController($location, $browser, $window, $cookies) {
   self.subpage = false;
   self.offlineEnabled = ($cookies[OFFLINE_COOKIE_NAME] == angular.version.full);
 
-  if (!$location.path()) {
+  if (!$location.path() || INDEX_PATH.test($location.path())) {
     $location.path('/api').replace();
   }
 
@@ -40,11 +41,11 @@ function DocsController($location, $browser, $window, $cookies) {
   });
 
   this.getUrl = function(page){
-    return '#!/' + page.section + '/' + page.id;
+    return page.section + '/' + page.id;
   };
 
   this.getCurrentPartial = function(){
-    return this.partialId ? ('./' + this.sectionId + '/' + this.partialId + '.html') : '';
+    return this.partialId ? ('./partials/' + this.sectionId + '/' + this.partialId + '.html') : '';
   };
 
   this.getClass = function(page) {
@@ -127,7 +128,7 @@ function TutorialInstructionsCtrl($cookieStore) {
 
 angular.service('$locationConfig', function() {
   return {
-    html5Mode: false,
+    html5Mode: true,
     hashPrefix: '!'
   };
 });
diff --git a/docs/src/templates/index.html b/docs/src/templates/index.html
index d5cfaed2..a2def7a6 100644
--- a/docs/src/templates/index.html
+++ b/docs/src/templates/index.html
@@ -5,23 +5,57 @@
       doc:manifest>
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-  <title ng:bind-template="AngularJS: {{partialTitle}}">AngularJS</title>
   <meta name="fragment" content="!">
-  <link rel="stylesheet" href="docs-combined.css" type="text/css"/>
-  <link rel="stylesheet" href="syntaxhighlighter/syntaxhighlighter-combined.css" type="text/css"/>
+  <title ng:bind-template="AngularJS: {{partialTitle}}">AngularJS</title>
+  <script type="text/javascript">
+    // dynamically add base tag as well as css and javascript files.
+    // we can't add css/js the usual way, because some browsers (FF) eagerly prefetch resources
+    // before the base attribute is added, causing 404 and terribly slow loading of the docs app.
+    (function() {
+      var indexFile = (location.pathname.match(/\/(index[^\.]*\.html)/) || ['', 'index.html'])[1],
+          rUrl = /(api|guide|misc|tutorial|cookbook|index[^\.]*\.html).*$/,
+          baseUrl = location.href.replace(rUrl, indexFile),
+          jQuery = /index-jq[^\.]*\.html$/.test(baseUrl),
+          debug = /index[^\.]*-debug\.html$/.test(baseUrl),
+          angularPath = debug ? '../angular.js' : '../angular.min.js',
+          headEl = document.getElementsByTagName('head')[0],
+          sync = true;
 
-  <script>
-    // GA asynchronous tracker
-    var _gaq = _gaq || [];
-    _gaq.push(['_setAccount', 'UA-8594346-3']);
-    _gaq.push(['_setDomainName', '.angularjs.org']);
+      addTag('base', {href: baseUrl});
+      addTag('link', {rel: 'stylesheet', href: 'docs-combined.css', type: 'text/css'});
+      addTag('link', {rel: 'stylesheet', href: 'syntaxhighlighter/syntaxhighlighter-combined.css',
+                      type: 'text/css'});
+      addTag('script', {src: 'syntaxhighlighter/syntaxhighlighter-combined.js'}, sync);
+      if (jQuery) addTag('script', {src: 'jquery.min.js'});
+      addTag('script', {src: angularPath, 'ng:autobind':''}, sync);
+      addTag('script', {src: 'docs-combined.js'}, sync);
+      addTag('script', {src: 'docs-keywords.js'}, sync);
 
-    (function() {
-      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+      function addTag(name, attributes, sync) {
+        var el = document.createElement(name),
+            attrName;
+
+        for (attrName in attributes) {
+          el.setAttribute(attrName, attributes[attrName]);
+        }
+
+        sync ? document.write(outerHTML(el)) : headEl.appendChild(el);
+      }
+
+      function outerHTML(node){
+        // if IE, Chrome take the internal method otherwise build one
+        return node.outerHTML || (
+            function(n){
+                var div = document.createElement('div'), h;
+                div.appendChild(n);
+                h = div.innerHTML;
+                div = null;
+                return h;
+            })(node);
+      }
     })();
 
+
     // force page reload when new update is available
     window.applicationCache && window.applicationCache.addEventListener('updateready', function(e) {
       if (window.applicationCache.status == window.applicationCache.UPDATEREADY) {
@@ -29,6 +63,18 @@
         window.location.reload();
       }
     }, false);
+
+
+    // GA asynchronous tracker
+    var _gaq = _gaq || [];
+    _gaq.push(['_setAccount', 'UA-8594346-3']);
+    _gaq.push(['_setDomainName', '.angularjs.org']);
+
+    (function() {
+      var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
+      ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
+      var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
+    })();
   </script>
 </head>
 
@@ -45,11 +91,11 @@
 
     <ul id="navbar">
       <li><a href="http://angularjs.org/">AngularJS</a></li>
-      <li><a href="#!/misc/started" ng:class="selectedSection('misc')">Getting Started</a></li>
-      <li><a href="#!/tutorial" ng:class="selectedSection('tutorial')">Tutorial</a></li>
-      <li><a href="#!/api" ng:class="selectedSection('api')">API Reference</a></li>
-      <li><a href="#!/cookbook" ng:class="selectedSection('cookbook')">Examples</a></li>
-      <li><a href="#!/guide" ng:class="selectedSection('guide')">Developer Guide</a></li>
+      <li><a href="misc/started" ng:class="selectedSection('misc')">Getting Started</a></li>
+      <li><a href="tutorial" ng:class="selectedSection('tutorial')">Tutorial</a></li>
+      <li><a href="api" ng:class="selectedSection('api')">API Reference</a></li>
+      <li><a href="cookbook" ng:class="selectedSection('cookbook')">Examples</a></li>
+      <li><a href="guide" ng:class="selectedSection('guide')">Developer Guide</a></li>
     </ul>
 
     <div id="sidebar">
@@ -100,11 +146,5 @@
       <button id="cacheButton" ng:click="enableOffline()">Let me have them all!</button>
     </div>
   </div>
-
-  <script src="syntaxhighlighter/syntaxhighlighter-combined.js"></script>
-  <!-- jquery place holder -->
-  <!-- angular script place holder -->
-  <script src="docs-combined.js"></script>
-  <script src="docs-keywords.js"></script>
 </body>
 </html>
-- 
cgit v1.2.3