diff options
| author | Misko Hevery | 2012-03-09 15:12:48 -0800 |
|---|---|---|
| committer | Misko Hevery | 2012-03-11 21:31:35 -0700 |
| commit | 3e5377f4f3b1d0f06af50e21026835bee0556b4a (patch) | |
| tree | 156df16f60ddf501df847050946d9ed0765967d2 /docs/content/guide/ie.ngdoc | |
| parent | 488a03631eb69794fd158f3f0df34d936084aec4 (diff) | |
| download | angular.js-3e5377f4f3b1d0f06af50e21026835bee0556b4a.tar.bz2 | |
doc(fixes): to better support ng-directive notation
Diffstat (limited to 'docs/content/guide/ie.ngdoc')
| -rw-r--r-- | docs/content/guide/ie.ngdoc | 162 |
1 files changed, 162 insertions, 0 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> + + + |