05341fb3b3 · samitouri/QOS-React-2

@@ -57,4 +57,159 @@ View the finished code in a web browser and type your name into the text field.

57

58 We strongly believe that components are the right way to separate concerns rather than "templates" and "display logic." We think that markup and the code that generates it are intimately tied together. Additionally, display logic is often very complex and using template languages to express it becomes cumbersome.

59

60 -We've found that the best solution for this problem is to generate markup directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs. In order to make this easier, we've added a *very* simple, **optional** HTML-like syntax for the function calls that generate markup called JSX. See [the JSX syntax documentation](syntax.html) for more information.

\ No newline at end of file

60 +We've found that the best solution for this problem is to generate markup directly from the JavaScript code such that you can use all of the expressive power of a real programming language to build UIs. In order to make this easier, we've added a *very* simple, **optional** HTML-like syntax for the function calls that generate markup called JSX.

61 +

62 +### Don't use JSX if you don't like it!

63 +

64 +React works out of the box without JSX. Simply construct your markup using the

65 +functions on `React.DOM`. For example, here's how to construct a simple link:

66 +

67 +```javascript

68 +var link = React.DOM.a({href: 'http://facebook.github.io/react'}, 'React');

69 +```

70 +

71 +However, we recommend using JSX for many reasons:

72 +

73 +- It's easier to visualize the structure of the DOM.

74 +- Designers are more comfortable making changes.

75 +- It's familiar for those who have used MXML or XAML.

76 +

77 +### The Transform

78 +

79 +JSX transforms XML-like syntax into native JavaScript. It turns XML elements and

80 +attributes into function calls and objects, respectively.

81 +

82 +```javascript

83 +var Nav;

84 +// Input (JSX):

85 +var app = <Nav color="blue" />;

86 +// Output (JS):

87 +var app = Nav({color:'blue'}, null);

88 +```

89 +

90 +Notice that in order to use `<Nav />`, the `Nav` variable must be in scope.

91 +

92 +JSX also allows specifying children using XML syntax:

93 +

94 +```javascript

95 +var Nav, Profile;

96 +// Input (JSX):

97 +var app = <Nav color="blue"><Profile>click</Profile></Nav>;

98 +// Output (JS):

99 +var app = Nav({color:'blue'}, Profile(null, 'click'));

100 +```

101 +

102 +Use the [JSX Compiler](/react/jsx-compiler.html) to try out JSX and see how it

103 +desugars into native JavaScript.

104 +

105 +If you want to use JSX, the [Getting Started](getting-started.html) guide shows

106 +how to setup compilation.

107 +

108 +> Note:

109 +>

110 +> Details about the code transform are given here to increase understanding, but

111 +> your code should not rely on these implementation details.

112 +

113 +### React and JSX

114 +

115 +React and JSX are independent technologies, but JSX was primarily built with

116 +React in mind. The two valid uses of JSX are:

117 +

118 +- To construct instances of React DOM components (`React.DOM.*`).

119 +- To construct instances of composite components created with

120 + `React.createClass()`.

121 +

122 +**React DOM Components**

123 +

124 +To construct a `<div>` is to create a variable that refers to `React.DOM.div`.

125 +

126 +```javascript

127 +var div = React.DOM.div;

128 +var app = <div className="appClass">Hello, React!</div>;

129 +```

130 +

131 +**React Component Components**

132 +

133 +To construct an instance of a composite component, create a variable that

134 +references the class.

135 +

136 +```javascript

137 +var MyComponent = React.createClass({/*...*/});

138 +var app = <MyComponent someProperty={true} />;

139 +```

140 +

141 +See [Component Basics](component-basics.html) to learn more about components.

142 +

143 +> Note:

144 +>

145 +> Since JSX is JavaScript, identifiers such as `class` and `for` are discouraged

146 +> as XML attribute names. Instead, React DOM components expect attributes like

147 +> `className` and `htmlFor`, respectively.

148 +

149 +### DOM Convenience

150 +

151 +Having to define variables for every type of DOM element can get tedious

152 +(e.g. `var div, span, h1, h2, ...`). JSX provides a convenience to address this

153 +problem by allowing you to specify a variable in an `@jsx` docblock field. JSX

154 +will use that field to find DOM components.

155 +

156 +```javascript

157 +/**

158 + * @jsx React.DOM

159 + */

160 +var Nav;

161 +// Input (JSX):

162 +var tree = <Nav><span /></Nav>;

163 +// Output (JS):

164 +var tree = Nav(null, React.DOM.span(null, null));

165 +```

166 +

167 +> Remember:

168 +>

169 +> JSX simply transforms elements into function calls and has no notion of the

170 +> DOM. The docblock parameter is only a convenience to resolve the most commonly

171 +> used elements. In general, JSX has no notion of the DOM.

172 +

173 +### JavaScript Expressions

174 +

175 +#### Attribute Expressions

176 +

177 +To use a JavaScript expression as an attribute value, wrap the expression in a

178 +pair of curly braces (`{}`) instead of quotes (`""`).

179 +

180 +```javascript

181 +// Input (JSX):

182 +var person = <Person name={window.isLoggedIn ? window.name : ''} />;

183 +// Output (JS):

184 +var person = Person({name: window.isLoggedIn ? window.name : ''});

185 +```

186 +

187 +#### Child Expressions

188 +

189 +Likewise, JavaScript expressions may be used to express children:

190 +

191 +```javascript

192 +// Input (JSX):

193 +var content = <Container>{window.isLoggedIn ? <Nav /> : <Login />}</Container>;

194 +// Output (JS):

195 +var content = Container(null, window.isLoggedIn ? Nav(null, null) : Login(null, null));

196 +```

197 +

198 +### Tooling

199 +

200 +Beyond the compilation step, JSX does not require any special tools.

201 +

202 +- Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).

203 +- Linting provides accurate line numbers after compiling without sourcemaps.

204 +- Elements use standard scoping so linters can find usage of out-of-scope

205 + components.

206 +

207 +### Prior Work

208 +

209 +JSX is similar to several other JavaScript embedded XML language

210 +proposals/projects. Some of the features of JSX that distinguish it from similar

211 +efforts include:

212 +

213 +- JSX is a simple syntactic transform.

214 +- JSX neither provides nor requires a runtime library.

215 +- JSX does not alter or add to the semantics of JavaScript.

Add more jsx docs rather than linking