Merge pull request #2518 from jsfb/documentation-for-dangerouslySetInnerHtml

Document justification for dangerouslySetInnerHTML, fixes #2256

_data/nav_tips.yml

@@ -36,3 +36,5 @@
     title: this.props.children undefined
   - id: use-react-with-other-libraries
     title: Use React with Other Libraries
+  - id: dangerously-set-inner-html
+    title: Dangerously Set innerHTML

docs/02.3-jsx-gotchas.md

@@ -46,7 +46,7 @@ You can use mixed arrays with strings and JSX elements.
 <div>{['First ', <span>&middot;</span>, ' Second']}</div>
 ```
 
-As a last resort, you always have the ability to insert raw HTML.
+As a last resort, you always have the ability to [insert raw HTML](/react/docs/dom-differences.html).
 
 ```javascript
 <div dangerouslySetInnerHTML={{'{{'}}__html: 'First &middot; Second'}} />

docs/ref-07-special-non-dom-attributes.md

@@ -10,4 +10,4 @@ Beside [DOM differences](/react/docs/dom-differences.html), React offers some at
 
 - `key`: an optional, unique identifier. When your component shuffles around during `render` passes, it might be destroyed and recreated due to the diff algorithm. Assigning it a key that persists makes sure the component stays. See more [here](/react/docs/multiple-components.html#dynamic-children).
 - `ref`: see [here](/react/docs/more-about-refs.html).
-- `dangerouslySetInnerHTML`: takes an object with the key `__html` and a DOM string as value. This is mainly for cooperating with DOM string manipulation libraries. Refer to the last example on the front page.
+- `dangerouslySetInnerHTML`: Provides the ability to insert raw HTML, mainly for cooperating with DOM string manipulation libraries. See more [here](/react/tips/dangerously-set-inner-html.html).

tips/17-children-undefined.md

@@ -25,4 +25,4 @@ var App = React.createClass({
 React.render(<App></App>, mountNode);
 ```
 
-To access your own subcomponents (the `span`s), place [refs](http://facebook.github.io/react/docs/more-about-refs.html) on them.
+For a more sophisticated example, refer to the last example on the [front page](/).

tips/18-use-react-with-other-libraries.md

@@ -4,6 +4,7 @@ title: Use React with Other Libraries
 layout: tips
 permalink: use-react-with-other-libraries.html
 prev: children-undefined.html
+next: dangerously-set-inner-html.html
 ---
 
 You don't have to go full React. The component [lifecycle events](/react/docs/component-specs.html#lifecycle-methods), especially `componentDidMount` and `componentDidUpdate`, are good places to put your other libraries' logic.

tips/19--dangerouslySetInnerHTML.md

@@ -0,0 +1,24 @@
+---
+id: dangerously-set-inner-html
+title: Dangerously Set innerHTML
+layout: tips
+permalink: dangerously-set-inner-html.html
+prev: children-undefined.html
+---
+
+Improper use of the `innerHTML` can open you up to a [cross-site scripting (XSS)](http://en.wikipedia.org/wiki/Cross-site_scripting) attack.  Sanitizing user input for display is notoriously error-prone, and failure to properly sanitize is one of the [leading causes of web vulnerabilities](http://owasptop10.googlecode.com/files/OWASP%20Top%2010%20-%202013.pdf) on the internet.
+
+Our design philosophy is that it should be “easy” to make things safe, and developers should explicitly state their intent when performing “unsafe” operations.  The prop name `dangerouslySetInnerHTML` is intentionally chosen to be frightening, and the prop value (an object instead of a string) can be used to indicate sanitized data.
+
+After fully understanding the security ramifications and properly sanitizing the data, create a new object containing only the key `__html` and your sanitized data as the value.  Here is an example using the JSX syntax:
+
+```js
+function createMarkup() { return {__html: 'First · Second'}; };
+<div dangerouslySetInnerHTML={createMarkup()} />
+```
+
+The point being that if you unintentionally do say `<div dangerouslySetInnerHTML={getUsername()} />` it will not be rendered because `getUsername()` would return a plain `string` and not a `{__html: ''}` object.  The intent behind the `{__html:...}` syntax is that it be considered a "type/taint" of sorts.  Sanitized data can be returned from a function using this wrapper object, and this marked data can subsequently be passed into `dangerouslySetInnerHTML`.  For this reason, we recommend against writing code of the form `<div dangerouslySetInnerHTML={{'{{'}}__html: getMarkup()}} />`.
+
+This functionality is mainly provided for cooperation with DOM string manipulation libraries, so the HTML provided must be well-formed (ie., pass XML validation).
+
+For a more complete usage example, refer to the last example on the [front page](/).