Skip to content
This repository has been archived by the owner on Apr 12, 2024. It is now read-only.

Commit

Permalink
feat(docs): use html5 history api for all routing in the docs app
Browse files Browse the repository at this point in the history 
- 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
  • Loading branch information
@vojtajina @IgorMinar
vojtajina authored and IgorMinar committed Sep 26, 2011
1 parent 2bc39bb commit 13f92de
Show file tree
Hide file tree
Showing 12 changed files with 150 additions and 80 deletions.
29 changes: 25 additions & 4 deletions Rakefile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -209,18 +209,37 @@ task :package => [:clean, :compile, :docs] do
text = f.read
f.truncate 0
f.rewind
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js")
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
end


File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-jq.html", File::RDWR) do |f|
text = f.read
f.truncate 0
f.rewind
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js")
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
end


File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-debug.html", File::RDWR) do |f|
text = f.read
f.truncate 0
f.rewind
f.write text.sub('../angular.js', "../angular-#{NG_VERSION.full}.js").
sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
end


File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/index-jq-debug.html", File::RDWR) do |f|
text = f.read
f.truncate 0
f.rewind
f.write text.sub('../angular.js', "../angular-#{NG_VERSION.full}.js").
sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
end

File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/docs-scenario.html", File::RDWR) do |f|
text = f.read
f.truncate 0
Expand All @@ -232,14 +251,16 @@ task :package => [:clean, :compile, :docs] do
text = f.read
f.truncate 0
f.rewind
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js")
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
end

File.open("#{pkg_dir}/docs-#{NG_VERSION.full}/appcache-offline.manifest", File::RDWR) do |f|
text = f.read
f.truncate 0
f.rewind
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js")
f.write text.sub('angular.min.js', "angular-#{NG_VERSION.full}.min.js").
sub('/build/docs/', "/#{NG_VERSION.full}/docs-#{NG_VERSION.full}/")
end


Expand Down
10 changes: 5 additions & 5 deletions docs/content/cookbook/deeplinking.ngdoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,14 @@ controller.

In this example we have a simple app which consist of two screens:

* Welcome: url `#` Show the user contact information.
* Settings: url `#/settings` Show an edit screen for user contact information.
* Welcome: url `welcome` Show the user contact information.
* Settings: url `settings` Show an edit screen for user contact information.


The two partials are defined in the following URLs:

* {@link ./examples/settings.html}
* {@link ./examples/welcome.html}
* <a href="./examples/settings.html" ng:ext-link>./examples/settings.html</a>
* <a href="./examples/welcome.html" ng:ext-link>./examples/welcome.html</a>

<doc:example>
<doc:source>
Expand Down Expand Up @@ -79,7 +79,7 @@ The two partials are defined in the following URLs:
</script>
<div ng:controller="AppCntl">
<h1>Your App Chrome</h1>
[ <a href="#!/welcome">Welcome</a> | <a href="#!/settings">Settings</a> ]
[ <a href="welcome">Welcome</a> | <a href="settings">Settings</a> ]
<hr/>
<span style="background-color: blue; color: white; padding: 3px;">
Partial: {{$route.current.template}}
Expand Down
14 changes: 7 additions & 7 deletions docs/spec/ngdocSpec.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -327,8 +327,8 @@ describe('ngdoc', function(){
expect(doc.requires).toEqual([
{name:'$service', text:'<p>for \n<code>A</code></p>'},
{name:'$another', text:'<p>for <code>B</code></p>'}]);
expect(doc.html()).toContain('<a href="#!/api/angular.service.$service">$service</a>');
expect(doc.html()).toContain('<a href="#!/api/angular.service.$another">$another</a>');
expect(doc.html()).toContain('<a href="api/angular.service.$service">$service</a>');
expect(doc.html()).toContain('<a href="api/angular.service.$another">$another</a>');
expect(doc.html()).toContain('<p>for \n<code>A</code></p>');
expect(doc.html()).toContain('<p>for <code>B</code></p>');
});
Expand Down Expand Up @@ -429,13 +429,13 @@ describe('ngdoc', function(){
doc.parse();

expect(doc.description).
toContain('foo <a href="#!/api/angular.foo"><code>angular.foo</code></a>');
toContain('foo <a href="api/angular.foo"><code>angular.foo</code></a>');
expect(doc.description).
toContain('da <a href="#!/api/angular.foo"><code>bar foo bar</code></a>');
toContain('da <a href="api/angular.foo"><code>bar foo bar</code></a>');
expect(doc.description).
toContain('dad<a href="#!/api/angular.foo"><code>angular.foo</code></a>');
toContain('dad<a href="api/angular.foo"><code>angular.foo</code></a>');
expect(doc.description).
toContain('<a href="#!/api/angular.directive.ng:foo"><code>ng:foo</code></a>');
toContain('<a href="api/angular.directive.ng:foo"><code>ng:foo</code></a>');
expect(doc.description).
toContain('<a href="http://angularjs.org">http://angularjs.org</a>');
expect(doc.description).
Expand All @@ -447,7 +447,7 @@ describe('ngdoc', function(){
'{@link\napi/angular.foo\na\nb}');
doc.parse();
expect(doc.description).
toContain('<a href="#!/api/angular.foo"><code>a b</code></a>');
toContain('<a href="api/angular.foo"><code>a b</code></a>');
});

});
Expand Down
4 changes: 2 additions & 2 deletions docs/src/appCache.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:",
Expand Down Expand Up @@ -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:",
Expand Down
21 changes: 6 additions & 15 deletions docs/src/gen-docs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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'));
Expand Down
12 changes: 6 additions & 6 deletions docs/src/ngdoc.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>' : '')
Expand Down Expand Up @@ -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);
});
Expand Down Expand Up @@ -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){
Expand Down
6 changes: 5 additions & 1 deletion docs/src/templates/.htaccess
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,8 @@

RewriteEngine on
RewriteCond %{HTTP_COOKIE} ng-offline="NG_VERSION_FULL"
RewriteRule appcache.manifest appcache-offline.manifest
RewriteRule appcache.manifest appcache-offline.manifest


## HTML5 URL Support ##
RewriteRule ^(guide|api|cookbook|misc|tutorial)(/.*)?$ index.html
11 changes: 6 additions & 5 deletions docs/src/templates/docs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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();
}

Expand All @@ -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) {
Expand Down Expand Up @@ -127,7 +128,7 @@ function TutorialInstructionsCtrl($cookieStore) {

angular.service('$locationConfig', function() {
return {
html5Mode: false,
html5Mode: true,
hashPrefix: '!'
};
});
Loading

0 comments on commit 13f92de

Please sign in to comment.