wip: add error ngdoc

angular · Aug 29, 2014 · c139181 · c139181
1 parent 0397485
commit c139181
Showing 1 changed file with 51 additions and 0 deletions.
diff --git a/docs/content/error/$location/nobase.ngdoc b/docs/content/error/$location/nobase.ngdoc
@@ -0,0 +1,51 @@
+@ngdoc error
+@name $location:nobase
+@fullName $location in HTML5 mode requires a <base> tag to be present!
+@description
+
+When {@link ng.$location `$location`} service is configured to use the
+{@ng.provider.$locationProvider `html5Mode`} (`history.pushState`), it is required that the base URL
+is specificed for the application via `<base href="">` tag.
+
+The base URL is then used to resolve all relative urls throughout the application regardless of the
+entry point into the app.
+
+If you are deploying your app into the root context, set the base url to `/`:
+
+```
+<head>
+  <base href="/">
+  ...
+</head>
+```
+
+If you are deploying your app into a sub-context, set the base url to the url of the subcontext:
+
+```
+<head>
+  <base href="/myapp">
+  ...
+</head>
+```
+
+Before Angular 1.3 we didn't have this hard requirement and it was easy to write apps that worked
+when deployed in the root context (https://myapp.com/) but were broken when deployed to
+a sub-context (e.g. https://myapp.com/subapp/), because in the sub-context all absolute urls would
+resolve to the root context of the app. To prevent this, use relative urls throughout your app:
+
+```
+<!-- wrong: -->
+<a href="/userProfile">User Profile</a>
+
+
+<!-- correct: -->
+<a href="userProfile">User Profile</a>
+
+```
+
+Additionally, if your app is used by users with browsers that don't support `history.pushState` api,
+the fallback mechanism provided by $location can get easily broken when we can't properly determine
+the base url of the application.
+
+In order to reduce the migration pain, we require that the base url is always specified when
+`$location`'s `html5mode` is enabled.