Skip to content

Commit a04e23a

Browse files
Matthew HonnibalAlexKVal
Matthew Honnibal
authored and
AlexKVal
committed
* Add draft Introduction page, explaining the project background and goals.
1 parent 4803d2c commit a04e23a

File tree

1 file changed

+116
-0
lines changed

1 file changed

+116
-0
lines changed

Diff for: ‎docs/src/IntroductionPage.js

+116
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
/** @jsx React.DOM */
2+
3+
'use strict';
4+
5+
var React = require('react');
6+
var fs = require('fs');
7+
8+
var NavMain = require('./NavMain');
9+
var PageHeader = require('./PageHeader');
10+
var PageFooter = require('./PageFooter');
11+
var StaticExample = require('./StaticExample');
12+
var ReactPlayground = require('./ReactPlayground')
13+
14+
15+
var TabbedArea = require('../../cjs/TabbedArea');
16+
var TabPane = require('../../cjs/TabPane');
17+
var preStyles = {"overflow": true};
18+
19+
var Page = React.createClass({
20+
render: function () {
21+
return (
22+
<div>
23+
<NavMain activePage="introduction" />
24+
25+
<PageHeader
26+
title="Introduction"
27+
subTitle="The most popular front-end framework, rebuilt for React."/>
28+
29+
<div className="container bs-docs-container">
30+
<div className="row">
31+
<div className="col-md-9" role="main">
32+
<div className="bs-docs-section">
33+
<p className="lead">React-Bootstrap is a library of reuseable front-end components. You'll get the look-and-feel of Twitter Bootstrap, but with much cleaner code, via Facebook's React.js framework.
34+
</p>
35+
<p>
36+
Let's say you want a small button that says "Something", to trigger the function someCallback. If were writing a native application, you might write something like:
37+
</p>
38+
{StaticExample({codeText: 'button(size=SMALL, color=GREEN, text="Something", onClick=someCallback)'})}
39+
<p>
40+
With the most popular web front-end framework, Twitter Bootstrap, you'd write this in your HTML:
41+
</p>
42+
{StaticExample({codeText: '<button id="something-btn" type="button" class="btn btn-success btn-sm">\n\tSomething\n</button>'})}
43+
<p>
44+
And something like <code>$('#something-btn').click(someCallback);</code> in your Javascript.
45+
By web standards this is quite nice, but it's still quite nasty. React-Bootstrap lets you write this:
46+
</p>
47+
{StaticExample({codeText: '<Button bsStyle="success" bsSize="small" onClick={someCallback}>\n\tSomething\n</Button>'})}
48+
49+
<p>
50+
The HTML/CSS implementation details are abstracted away, leaving you with an interface that more closely resembles what you would expect to write in other programming languages.
51+
</p>
52+
<p>
53+
Here's a more complicated example: a tabbed navigation area, showing the implementation with Bootstrap, and React-Bootstrap:
54+
</p>
55+
56+
<TabbedArea defaultActiveKey={2}>
57+
<TabPane key={1} tab="With Bootstrap">
58+
<pre>{fs.readFileSync(__dirname + '/../comparisons/TabbedAreaBS.html', 'utf8')}</pre>
59+
</TabPane>
60+
<TabPane key={2} tab="With React-Bootstrap">
61+
<pre>{fs.readFileSync(__dirname + '/../comparisons/TabbedAreaRBS.jsx', 'utf8')}</pre>
62+
</TabPane>
63+
</TabbedArea>
64+
65+
<h2>A better Bootstrap API using React.js</h2>
66+
<p>
67+
The Bootstrap code is so repetitive because HTML and CSS do not support the abstractions necessary for a nice library of components. That's why we have to write <small>btn</small> three times, within an element called <small>button</small>.
68+
</p>
69+
70+
<p><strong>The React.js solution is to write directly in Javascript.</strong> React takes over the page-rendering entirely; you just give it a tree of Javascript objects, and tell it how state is transmitted between them.</p>
71+
72+
<p>For instance, we might tell React to render a page displaying a single button, styled using the handy Bootstrap CSS:
73+
</p>
74+
<StaticExample codeText={fs.readFileSync(__dirname + '/../comparisons/vanillaButton.js', 'utf8')} />
75+
<p>
76+
But now that we're in Javascript, we can wrap the HTML/CSS, and provide a much better API:
77+
</p>
78+
<StaticExample codeText={fs.readFileSync(__dirname + '/../comparisons/noJSXButton.js', 'utf8')} />
79+
80+
React-Bootstrap is a library of such components, which you can also easily extend and enhance with your own functionality.
81+
<h3>JSX Syntax</h3>
82+
<p>
83+
While each React component is really just a Javascript object, writing tree-structures that way gets tedious. React encourages the use of a syntactic-sugar called JSX, which lets you write the tree in an HTML-like syntax:
84+
</p>
85+
<ReactPlayground show={true} codeText={fs.readFileSync(__dirname + '/../comparisons/ButtonToolbarDropdown.js', 'utf8')} />
86+
87+
<p>
88+
Some people's first impression of React.js is that it seems messy to mix Javascript and HTML in this way.
89+
However, compare the code required to add
90+
91+
a dropdown button in the example above to the <a href="http://getbootstrap.com/javascript/#dropdowns">
92+
Bootstrap Javascript</a> and <a href="http://getbootstrap.com/components/#btn-dropdowns">Components</a> documentation for creating a dropdown button.
93+
The documentation is split in two because you have to implement the component in two places in your code: first you must add the HTML/CSS elements, and then you must call some Javascript setup code to wire the component together.
94+
</p>
95+
<p>
96+
The React-Bootstrap component library tries to follow the React.js philosophy that a single piece of functionality should be defined in a single place.
97+
View the current React-Bootstrap library on the <a href="/components.html">components page</a>.
98+
</p>
99+
<p>
100+
The project is under active development --- APIs will change, and the documentation is far from complete. Contributions are encouraged!
101+
</p>
102+
</div>
103+
</div>
104+
</div>
105+
</div>
106+
<PageFooter />
107+
</div>
108+
);
109+
},
110+
111+
shouldComponentUpdate: function() {
112+
return false;
113+
}
114+
});
115+
116+
module.exports = Page;

0 commit comments

Comments
 (0)