{"commit":{"authorName":"petehunt","authoredAt":"2013-06-17T02:05:55-07:00","authorEmail":"pete.hunt@fb.com","subject":"Merge pull request #88 from vjeux\/jsx_pitfall","revision":"97efa84676854520efe0187f3f562989db1c1e4e","shortRevision":"97efa84676"},"parents":["22347ea54dd6f6d595bfb541135efdd0541c3896","d7a5f137ffdbb1e704c7d0d1108cc4bf09f0a4e2"],"body":"Adding JSX pitfalls section in the docs","patch":"diff --git a\/docs\/_includes\/nav_docs.html b\/docs\/_includes\/nav_docs.html\nindex d6d9e945a9..1dbd3b5c91 100644\n--- a\/docs\/_includes\/nav_docs.html\n+++ b\/docs\/_includes\/nav_docs.html\n@@ -21,4 +21,11 @@\n

Appendix<\/h3>\n+
\n+
JSX is not HTML<\/a><\/li>\n+ <\/ul>\n+ <\/div>\n <\/div>\ndiff --git a\/docs\/docs\/api.md b\/docs\/docs\/api.md\nindex fd29070ecb..f8b9edda7e 100644\n--- a\/docs\/docs\/api.md\n+++ b\/docs\/docs\/api.md\n@@ -3,6 +3,7 @@ id: docs-api\n title: React API\n layout: docs\n prev: mixins.html\n+next: jsx-is-not-html.html\n ---\n \n ## React\ndiff --git a\/docs\/docs\/jsx-is-not-html.md b\/docs\/docs\/jsx-is-not-html.md\nnew file mode 100644\nindex 0000000000..e3c4126328\n--- \/dev\/null\n+++ b\/docs\/docs\/jsx-is-not-html.md\n@@ -0,0 +1,95 @@\n+---\n+id: docs-jsx-is-not-html\n+title: JSX is not HTML\n+description: Differences between JSX and HTML.\n+layout: docs\n+prev: api.html\n+---\n+\n+JSX looks like HTML but there are some important differences you may run into.\n+\n+## Whitespace removal\n+\n+JSX doesn't follow the same whitespace elimination rules as HTML. JSX removes all the whitespaces between two curly braces expressions. If you want to have a white space, a work-around is to add `{' '}`.\n+\n+```javascript\n+
{this.props.name} {' '} {this.props.surname}<\/div>\n+```\n+\n+This behavior is still being debated. Follow [Issue #65](https:\/\/github.com\/facebook\/react\/issues\/65) to be updated on the situation.\n+\n+## HTML Entities\n+\n+You can insert HTML entities within literal text in JSX:\n+\n+```javascript\n+
First · Second<\/div>\n+```\n+\n+If you want to display an HTML entity within a dynamic content, you will run into double escaping issues as React escapes all the strings you are displaying in order to prevent a wide range of XSS attacks by default.\n+\n+```javascript\n+\/\/ Bad: It displays \"First · Second\"\n+
{'First · Second'}<\/div>\n+```\n+\n+There are various ways to work-around this issue. The easiest one is to write unicode character directly in Javascript. You've got to make sure that the file is saved as UTF-8 and that the propers UTF-8 directives are set so the browser will display it correctly.\n+\n+```javascript\n+
{'First · Second'}<\/div>\n+```\n+\n+A safer alternative is to find the unicode number corresponding to the entity<\/a> and use it inside of a Javascript string.\n+\n+```javascript\n+
{'First \\u00b7 Second'}<\/div>\n+
{'First ' + String.fromCharCode(183) + ' Second'}<\/div>\n+```\n+\n+You can use mixed arrays with strings and JSX elements.\n+\n+```javascript\n+
{['First ', ·<\/span>, ' Second']}<\/div>\n+```\n+\n+In last resort, you always have the ability to insert raw HTML inside of the div.\n+\n+```javascript\n+
\n+```\n+\n+## Comments\n+\n+JSX supports both single-line and multi-lines Javascript comments within a tag declaration:\n+\n+```javascript\n+
\n+```\n+\n+As of React 0.3, there is no good way to insert comments within the children section. [Issue #82](https:\/\/github.com\/facebook\/react\/issues\/82) is tracking progress to enable the following way to write comments:\n+\n+```javascript\n+\/\/ Note: The following is not implemented yet!\n+
\n+ {\/* This is a comment *\/}\n+<\/div>\n+```\n+\n+## Custom HTML attributes\n+\n+If you pass properties to native HTML elements that do not exist in the HTML specification, React will not render them. If you want to use a custom attribute, you should prefix it with `data-`.\n+\n+```javascript\n+
\n+```\n+\n+[Web Accessibility](http:\/\/www.w3.org\/WAI\/intro\/aria) attributes starting with `aria-` will be rendered properly.\n+\n+```javascript\n+
\n+```\n","files":[{"status":"M","path":"docs\/_includes\/nav_docs.html"},{"status":"M","path":"docs\/docs\/api.md"},{"status":"A","path":"docs\/docs\/jsx-is-not-html.md"}]}

dillon1000/react

Files changed