Reorganization and improvement of getting started guide

README.md

@@ -10,7 +10,9 @@ Check out our [documentation site](http://www.material-ui.com/) for live example
 
 ## Prerequisites
 
-We recommend that you get started with the [React Library](http://facebook.github.io/react/) before diving into material-ui for a better understanding. Should you choose to skip this, don't worry, we'll explain relevant React concepts as they come along.
+We recommend that you get to know [React](http://facebook.github.io/react/) before diving into material-ui. Material-UI is a set of React components, so understanding how React fits into web development is important.
+
+(If you're not familiar with Node, or with the concept of Single Page Applications (SPAs), head over to the [documentation website](http://material-ui.com/#/get-started/prerequisites) for a quick introduction before you read on.)
 
 ## Installation
 
@@ -25,7 +27,7 @@ Some components use [react-tap-event-plugin](https://github.com/zilverline/react
 listen for touch events. This dependency is temporary and will go away once react v1.0 is released. Until then, be
 sure to inject this plugin at the start of your app.
 ```js
-var injectTapEventPlugin = require("react-tap-event-plugin");
+let injectTapEventPlugin = require("react-tap-event-plugin");
 
 //Needed for onTouchTap
 //Can go away when react 1.0 release
@@ -35,40 +37,48 @@ injectTapEventPlugin();
 ```
 
 ### Roboto Font
-Be sure to include the [Roboto](http://www.google.com/fonts/specimen/Roboto) font in your project.
-Here are [some instructions](http://www.google.com/fonts#UsePlace:use/Collection:Roboto:400,300,500) on how to include it in your project.
+Material-UI was designed with the [Roboto](http://www.google.com/fonts/specimen/Roboto) font in mind. So be sure to include it in your project. Here are [some instructions](http://www.google.com/fonts#UsePlace:use/Collection:Roboto:400,300,500) on how to do so.
 
 ## Usage
 
 Once material-ui is included in your project, you can use the components this way:
 ```js
-/** MyAwesomeReactComponent.jsx */
+// get constant references to React and Material-UI
+// components, as we will not be modifying these
+
+const React = require('react');
+
+// it is good practice to require only those components of
+// Material-UI that your app needs, instead of requiring all of
+// Material-UI. This will make your build process faster and
+// your build output smaller
 
-var React = require('react'),
-  mui = require('material-ui'),
-  ThemeManager = new mui.Styles.ThemeManager(),
-  RaisedButton = mui.RaisedButton;
+const RaisedButton = require('material-ui/lib/raised-button');
 
-var MyAwesomeReactComponent = React.createClass({
+// see node_modules/material-ui/lib/index.js for a mapping of
+// Material-UI components to require() calls
+
+const MyAwesomeReactComponent = React.createClass({
 
   childContextTypes: {
     muiTheme: React.PropTypes.object
   },
 
-  getChildContext: function() {
+  getChildContext() {
     return {
       muiTheme: ThemeManager.getCurrentTheme()
     };
   },
 
-  render: function() {
+  render() {
     return (
         <RaisedButton label="Default" />
     );
   }
 
 });
 
+
 module.exports = MyAwesomeReactComponent;
 
 ```
@@ -87,9 +97,10 @@ Material-UI components have their styles defined inline. There are two approache
 This allows you to override variables used by components without having to modify material-ui source files directly.
 
 ## Examples
-There are 2 projects that you can look at to help you get started. The first project can be found in the [example folder](https://github.com/callemall/material-ui/tree/master/examples). This is a basic project that shows how you can consume material-ui components in your own project.
 
-The second project is the actual documentation site. This is a more complex project but will give examples of every component. Check out the [docs folder](https://github.com/callemall/material-ui/tree/master/docs) for build instructions.
+There are 2 projects that you can look at to get started. They can be found in the [examples folder](https://github.com/callemall/material-ui/tree/master/examples). These projects are basic examples that show how to consume material-ui components in your own project. The first project uses [browserify](http://browserify.org/) for module bundling and [gulp](http://gulpjs.com/) for JS task automation, while the second project uses [webpack](http://webpack.github.io/) for module bundling and building.
+
+The source code for this documentation site is also included in the repository. This is a slightly more complex project that also uses webpack, and contains examples of every material-ui component. Check out the [docs folder](https://github.com/callemall/material-ui/tree/master/docs) for build instructions.
 
 ## Contribute
 

docs/src/app/app-routes.jsx

@@ -7,7 +7,11 @@ let DefaultRoute = Router.DefaultRoute;
 // Here we define all our material-ui ReactComponents.
 let Master = require('./components/master');
 let Home = require('./components/pages/home');
+
 let GetStarted = require('./components/pages/get-started');
+let Prerequisites = require('./components/pages/get-started/prerequisites');
+let Installation = require('./components/pages/get-started/installation');
+let Examples = require('./components/pages/get-started/examples');
 
 let Customization = require('./components/pages/customization');
 let Colors = require('./components/pages/customization/colors');
@@ -53,7 +57,13 @@ let Toolbars = require('./components/pages/components/toolbars');
 let AppRoutes = (
   <Route name="root" path="/" handler={Master}>
     <Route name="home" handler={Home} />
-    <Route name="get-started" handler={GetStarted} />
+    <Route name="get-started" handler={GetStarted}>
+      <Route name="prerequisites" handler={Prerequisites} />
+      <Route name="installation" handler={Installation} />
+      <Route name="examples" handler={Examples} />
+      <Redirect from="/get-started" to="prerequisites" />
+    </Route>
+
     <Route name="customization" handler={Customization}>
       <Route name="colors" handler={Colors} />
       <Route name="themes" handler={Themes} />

docs/src/app/components/pages/get-started.jsx

@@ -1,161 +1,21 @@
 let React = require('react');
-let { Paper, Styles } = require('material-ui');
-let CodeBlock = require('../code-example/code-block');
-let FullWidthSection = require('../full-width-section');
-
-let { Spacing, Typography } = Styles;
+let PageWithNav = require('./page-with-nav');
 
 
 class GetStarted extends React.Component {
 
-  getStyles() {
-    return {
-      root: {
-        paddingTop: Spacing.desktopKeylineIncrement
-      },
-      fullWidthSection: {
-        maxWidth: '650px',
-        margin: '0 auto'
-      },
-      headline: {
-        fontSize: '24px',
-        lineHeight: '32px',
-        paddingTop: '16px',
-        marginBottom: '12px',
-        letterSpacing: '0',
-        fontWeight: Typography.fontWeightNormal,
-        color: Typography.textDarkBlack
-      },
-      title: {
-        fontSize: '20px',
-        lineHeight: '28px',
-        paddingTop: '19px',
-        marginBottom: '13px',
-        letterSpacing: '0',
-        fontWeight: Typography.fontWeightMedium,
-        color: '#f00'//Typography.textDarkBlack
-      },
-      codeExample: {
-        backgroundColor: this.context.muiTheme.palette.canvasColor,
-        marginBottom: '32px'
-      }
-    };
-  }
-
   render() {
-    let usageCode =
-          '/** MyAwesomeReactComponent.jsx */\n\n' +
-          'let React = require(\'react\'),\n' +
-          '  mui = require(\'material-ui\'),\n' +
-          '  RaisedButton = mui.RaisedButton;\n\n' +
-          'let SomeAwesomeComponent = React.createClass({\n\n' +
-          '  childContextTypes: {\n' +
-          '    muiTheme: React.PropTypes.object\n' +
-          '  },\n\n' +
-          '  getChildContext() {\n' +
-          '    return {\n' +
-          '      muiTheme: ThemeManager.getCurrentTheme()\n' +
-          '    };\n' +
-          '  },\n\n' +
-          '  render() {\n' +
-          '    return (\n' +
-          '        <RaisedButton label="Default" />\n' +
-          '    );\n' +
-          '  }\n\n' +
-          '});\n\n' +
-          'module.exports = MyAwesomeReactComponent;\n\n\n',
-
-      customizationCode =
-        '@import "node_modules/material-ui/src/less/scaffolding.less";\n\n' +
-        '//Define a custom less file to override\n//any variables defined in scaffolding.less\n' +
-        '@import "my-custom-overrides.less";\n\n' +
-        '@import "node_modules/material-ui/src/less/components.less";',
-
-      usageNotesCode =
-        'let injectTapEventPlugin = require("react-tap-event-plugin");\n\n' +
-        '//Needed for onTouchTap\n' +
-        '//Can go away when react 1.0 release\n' +
-        '//Check this repo:\n' +
-        '//https://github.com/zilverline/react-tap-event-plugin\n' +
-        'injectTapEventPlugin();\n';
-
-    let styles = this.getStyles();
+    let menuItems = [
+      { route: 'prerequisites', text: 'Prerequisites'},
+      { route: 'installation', text: 'Installation & Usage'},
+      { route: 'examples', text: 'Examples'}
+    ];
 
     return (
-      <div style={styles.root}>
-        <FullWidthSection style={styles.FullWidthSection}>
-
-          <h2 style={styles.headline}>Prerequisites</h2>
-          <p>
-            We recommend that you get started with the <a href="http://facebook.github.io/react/">React Library</a> before diving into
-            material-ui for a better understanding. Should you choose to skip this, don&apos;t worry, we&apos;ll explain relevant React concepts as
-            they come along.
-          </p>
-
-
-          <h2 style={styles.headline}>Installation</h2>
-          <p>
-            Material-UI is available as an <a href="https://www.npmjs.org/package/material-ui">npm package</a>.
-            After npm install, you will find all the .jsx files in the /src folder and their compiled versions in the /lib folder.
-          </p>
-
-          <h3 style={styles.title}>React-Tap-Event-Plugin</h3>
-          <p>
-            Some components use <a href="https://github.com/zilverline/react-tap-event-plugin">react-tap-event-plugin</a> to
-            listen for touch events. This dependency is temporary and will go away once react v1.0 is released. Until then, be
-            sure to inject this plugin at the start of your app.
-          </p>
-          <Paper style={styles.codeExample}>
-            <CodeBlock>{usageNotesCode}</CodeBlock>
-          </Paper>
-
-          <h3 style={styles.title}>Roboto Font</h3>
-          <p>
-            Be sure to include the <a href="http://www.google.com/fonts/specimen/Roboto">Roboto</a> font
-            in your project. Here are <a href="http://www.google.com/fonts#UsePlace:use/Collection:Roboto:400,300,500">some instructions</a> on how to include it in your project.
-          </p>
-
-          <h2 style={styles.headline}>Usage</h2>
-          <p>
-            Once material-ui is included in your project, you can use the components this way:
-          </p>
-          <Paper style={styles.codeExample}>
-            <CodeBlock>{usageCode}</CodeBlock>
-          </Paper>
-          <h3 style={styles.title}>Theme</h3>
-          <p>
-            Please note that since v0.8.0, you also need to <a href="#/customization/themes">define a theme</a> for components to start working.
-          </p>
-
-          <h2 style={styles.headline}>Customization</h2>
-          <p>Material-UI components have their styles defined inline. There are two approaches to overriding these styles:</p>
-          <li><a href="#/customization/inline-styles">Override individual component styles via the style prop</a></li>
-          <li><a href="#/customization/themes">Define a Theme to apply overarching style changes</a></li>
-          <p>
-            This allows you to override any variables used without having to modify material-ui source files directly.
-          </p>
-
-          <h2 style={styles.headline}>Examples</h2>
-          <p>
-            There are 2 projects that you can look at to help you get started. The first project can be found
-            in the <a href="https://github.com/callemall/material-ui/tree/master/examples">examples folder</a>. This
-            is a basic project that shows how you can consume material-ui components in your own project.
-          </p>
-          <p>
-            The second project is this documentation site. This is a more complex project but will give
-            examples of every component. Check out the <a href="https://github.com/callemall/material-ui/tree/master/docs">docs folder</a> for
-            build instructions.
-          </p>
-
-        </FullWidthSection>
-      </div>
+      <PageWithNav menuItems={menuItems} />
     );
   }
 
 }
 
-GetStarted.contextTypes = {
-  muiTheme: React.PropTypes.object
-};
-
 module.exports = GetStarted;

docs/src/app/components/pages/get-started/examples.jsx

@@ -0,0 +1,56 @@
+let React = require('react');
+let { Paper, Styles } = require('material-ui');
+
+let { Spacing, Typography } = Styles;
+
+
+class Examples extends React.Component {
+
+  getStyles() {
+    return {
+      headline: {
+        fontSize: '24px',
+        lineHeight: '32px',
+        paddingTop: '16px',
+        marginBottom: '12px',
+        letterSpacing: '0',
+        fontWeight: Typography.fontWeightNormal,
+        color: Typography.textDarkBlack
+      },
+    };
+  }
+
+  render() {
+
+    let styles = this.getStyles();
+
+    return (
+      <div>
+
+        <h2 style={styles.headline}>Examples</h2>
+        <p>
+          There are 2 projects that you can look at to get started. They can be found
+          in the <a href="https://github.com/callemall/material-ui/tree/master/examples">examples folder</a>. These
+          projects are basic examples that show how to consume material-ui components in your own project.
+          The first project uses <a href="http://browserify.org/">browserify</a> for module bundling 
+          and <a href="http://gulpjs.com/">gulp</a> for JS task automation, while the second project 
+          uses <a href="http://webpack.github.io">webpack</a> for module bundling and building.
+        </p>
+        <p>
+          The source code for this documentation site is also included in the repository. This is a slightly more complex project that 
+          also uses webpack, and contains
+          examples of every material-ui component. Check out the <a href="https://github.com/callemall/material-ui/tree/master/docs">docs folder</a> for 
+          build instructions.
+        </p>
+
+    </div>
+    );
+  }
+
+}
+
+Examples.contextTypes = {
+  muiTheme: React.PropTypes.object
+};
+
+module.exports = Examples;