aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorMisko Hevery2012-03-09 15:12:48 -0800
committerMisko Hevery2012-03-11 21:31:35 -0700
commit3e5377f4f3b1d0f06af50e21026835bee0556b4a (patch)
tree156df16f60ddf501df847050946d9ed0765967d2 /docs
parent488a03631eb69794fd158f3f0df34d936084aec4 (diff)
downloadangular.js-3e5377f4f3b1d0f06af50e21026835bee0556b4a.tar.bz2
doc(fixes): to better support ng-directive notation
Diffstat (limited to 'docs')
-rw-r--r--docs/content/guide/ie.ngdoc162
-rw-r--r--docs/src/dom.js3
-rw-r--r--docs/src/ngdoc.js45
3 files changed, 193 insertions, 17 deletions
diff --git a/docs/content/guide/ie.ngdoc b/docs/content/guide/ie.ngdoc
new file mode 100644
index 00000000..3ba93d2d
--- /dev/null
+++ b/docs/content/guide/ie.ngdoc
@@ -0,0 +1,162 @@
+@ngdoc overview
+@name Developer Guide: Internet Explorer Compatibility
+@description
+
+# Overview
+
+This document describes the Internet Explorer (IE) idiosyncrasies when dealing with custom HTML
+attributes and tags. Read this document if you are planning on deploying your angular application
+on IE v8.0 or earlier.
+
+# Short Version
+
+To make your angular application work on IE please make sure that:
+
+ 1. you **do not** use custom element tags such as `<ng:view>` (use the attribute version `<div
+ ng-view>` instead), or
+
+ 2. if you **do use** custom element tags, then you must take these steps to make IE happy:
+
+<pre>
+ <html xmlns:ng="http://angularjs.org">
+ <head>
+ <!--[if lte IE 8]>
+ <script>
+ document.createElement('ng-include');
+ document.createElement('ng-pluralize');
+ document.createElement('ng-view');
+
+ // Optionally these for CSS
+ document.createElement('ng:include');
+ document.createElement('ng:pluralize');
+ document.createElement('ng:view');
+ </script>
+ <![endif]-->
+ </head>
+ <body>
+ ...
+ </body>
+ </html>
+</pre>
+
+The **important** parts are:
+
+ * `xmlns:ng` - *namespace* - you need one namespace for each custom tay you are planning on
+ using.
+
+ * `document.createElement(yourTagName)` - *creation of custom tag names* - Since this is an
+ issue only for older version of IE you need to load it conditionally. For each tag which does
+ not have namespace and which is not defined in HTML you need to pre-declare it to make IE
+ happy.
+
+
+# Long Version
+
+IE has an issues with element tag names which are not standard HTML tag names. These fall into two
+categories, and each category has its own fix.
+
+ * If the tag name starts with `my:` prefix than it is considered an XML namespace and must
+ have corresponding namespace declaration on `<html xmlns:my="ignored">`
+
+ * If the tag has no `:` but it is not a standard HTML tag, then it must be pre-created using
+ `document.createElement('my-tag')`
+
+ * If you have are planning on styling the custom tag with CSS selectors, then it must be
+ pre-created using `document.createElement('my-tag')` regardless of XML namespace.
+
+
+## The Good News
+
+The good news is that these restrictions only apply to element tag names, and not to element
+attribute names. So this requires no special handling in IE: `<div my-tag your:tag></div>`.
+
+
+## What happens if I fail to do this?
+
+Suppose you have HTML with unknown tag `mytag` (this could also be `my:tag` or `my-tag` with same
+result):
+
+<pre>
+ <html>
+ <body>
+ <mytag>some text</mytag>
+ </body>
+ </html>
+</pre>
+
+It should pares into the following DOM:
+
+<pre>
+#document
+ +- HTML
+ +- BODY
+ +- mytag
+ +- #text: some text
+</pre>
+
+The expected behavior is that the `BODY` element has a child element `mytag`, which in turn has
+the text `some text`.
+
+But this is not what IE does (if the above fixes are not included):
+
+<pre>
+#document
+ +- HTML
+ +- BODY
+ +- mytag
+ +- #text: some text
+ +- /mytag
+</pre>
+
+In IE, the behavior is that the `BODY` element has three children:
+
+ 1. A self closing `mytag`. Example of self closing tag is `<br/>`. The trailing `/` is optional,
+ but the `<br>` tag is not allowed to have any children, and browsers consider `<br>some
+ text</br>` as three siblings not a `<br>` with `some text` as child.
+
+ 2. A text node with `some text`. This should have been a child of `mytag` above, not a sibling.
+
+ 3. A corrupt self closing `/mytag`. This is corrupt since element names are not allowed to have
+ the `/` character. Furthermore this closing element should not be part of the DOM since it is
+ only used to delimitate the structure of the DOM.
+
+
+## CSS Styling of Custom Tag Names
+
+The to make CSS selector work with custom elements the custom element name must be shived with the
+`document.createElement('my-tag')` regardless of XML namespace.
+
+<pre>
+ <html xmlns:ng="needed for ng: namespace">
+ <head>
+ <!--[if lte IE 8]>
+ <script>
+ // needed to make ng-include parse properly
+ document.createElement('ng-include');
+
+ // needed to enable CSS reference
+ document.createElement('ng:view');
+ </script>
+ <![endif]-->
+ <style>
+ ng\\:view {
+ display: block;
+ border: 1px solid red;
+ }
+
+ ng-include {
+ display: block;
+ border: 1px solid blue;
+ }
+ </style>
+ </head>
+ <body>
+ <ng:view></ng:view>
+ <ng-include></ng-include>
+ ...
+ </body>
+ </html>
+</pre>
+
+
+
diff --git a/docs/src/dom.js b/docs/src/dom.js
index bda90373..e5320c5f 100644
--- a/docs/src/dom.js
+++ b/docs/src/dom.js
@@ -19,7 +19,8 @@ function DOM() {
var INLINE_TAGS = {
i: true,
- b: true
+ b: true,
+ a: true
};
DOM.prototype = {
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index 6cbf816c..1cbd968e 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -367,18 +367,14 @@ Doc.prototype = {
dom.h('Usage', function() {
var restrict = self.restrict || 'AC';
if (restrict.match(/E/)) {
- dom.text('as element');
+ dom.text('as element (see ');
+ dom.tag('a', {href:'guide/ie'}, 'IE restrictions');
+ dom.text(')');
dom.code(function() {
dom.text('<');
dom.text(self.shortName);
- (self.param||[]).forEach(function(param){
- dom.text('\n ');
- dom.text(param.optional ? ' [' : ' ');
- dom.text(param.name);
- dom.text(BOOLEAN_ATTR[param.name] ? '' : '="..."');
- dom.text(param.optional ? ']' : '');
- });
- dom.text('></');
+ renderParams('\n ', '="', '"');
+ dom.text('>\n</');
dom.text(self.shortName);
dom.text('>');
});
@@ -389,9 +385,7 @@ Doc.prototype = {
dom.code(function() {
dom.text('<' + element + ' ');
dom.text(self.shortName);
- if (self.param.length) {
- dom.text('="' + self.param[0].name + '"');
- }
+ renderParams('\n ', '="', '"', true);
dom.text('>\n ...\n');
dom.text('</' + element + '>');
});
@@ -402,9 +396,7 @@ Doc.prototype = {
dom.code(function() {
dom.text('<' + element + ' class="');
dom.text(self.shortName);
- if (self.param.length) {
- dom.text(': ' + self.param[0].name + ';');
- }
+ renderParams(' ', ': ', ';', true);
dom.text('">\n ...\n');
dom.text('</' + element + '>');
});
@@ -414,6 +406,27 @@ Doc.prototype = {
});
self.method_properties_events(dom);
+
+ function renderParams(prefix, infix, suffix, skipSelf) {
+ (self.param||[]).forEach(function(param) {
+ var skip = skipSelf && (param.name == self.shortName || param.name.indexOf(self.shortName + '|') == 0);
+ if (!skip) {
+ dom.text(prefix);
+ dom.text(param.optional ? '[' : '');
+ var parts = param.name.split('|');
+ dom.text(parts[skipSelf ? 0 : 1] || parts[0]);
+ }
+ if (BOOLEAN_ATTR[param.name]) {
+ dom.text(param.optional ? ']' : '');
+ } else {
+ dom.text(BOOLEAN_ATTR[param.name] ? '' : infix );
+ dom.text(('{' + param.type + '}').replace(/^\{\'(.*)\'\}$/, '$1'));
+ dom.text(param.optional ? ']' : '');
+ dom.text(suffix);
+ }
+ });
+ }
+
},
html_usage_filter: function(dom){
@@ -455,7 +468,7 @@ Doc.prototype = {
dom.text('\n ');
dom.text(param.optional ? ' [' : ' ');
dom.text(param.name);
- dom.text(BOOLEAN_ATTR[param.name] ? '' : '="..."');
+ dom.text(BOOLEAN_ATTR[param.name] ? '' : '="{' + param.type + '}"');
dom.text(param.optional ? ']' : '');
});
dom.text('>');
generated by cgit v1.2.3 (git 2.25.1) at 2025-11-02 21:13:12 +0000