diff --git a/_config.yml b/_config.yml index 2e8d78690e8c..322d220529f4 100644 --- a/_config.yml +++ b/_config.yml @@ -223,6 +223,9 @@ collections: tutorial_ng2: output: true permalink: /tutorial/ng2/:path + tutorial_react: + output: true + permalink: /tutorial/react/:path guide: output: true permalink: /guide/:path @@ -279,6 +282,14 @@ defaults: layout: single sidebar: nav: "tutorial_ng2" + - scope: + path: "" + type: tutorial_react + values: + sitemap: true + layout: single + sidebar: + nav: "tutorial_react" - scope: path: "" type: guide diff --git a/_tutorial_react/helloworld.md b/_tutorial_react/helloworld.md new file mode 100644 index 000000000000..20564fdb190c --- /dev/null +++ b/_tutorial_react/helloworld.md @@ -0,0 +1,294 @@ +--- +title: "UI-Router for React - Hello World!" +layout: single +excerpt: "Getting started with UI-Router for React" +sitemap: true +--- + +{% include toc icon="columns" title="Hello World!" %} + +Let's build a UI-Router for React Hello World application. +It will have two "pages" (`hello` and `about`), each one having its own URL. +We can switch between pages by clicking on links. +The link for the active page will be highlighted. + +# Full Source Code + +Start by looking over the complete source code (ignoring SystemJS `config.js`) for the Hello World application. We will go over each part in more detail below. + +## `index.html` + +```html + + + + + + + + + + + +
+ + + +``` + +## `helloworld.jsx` + +```javascript +import React from 'react'; +import ReactDOM from 'react-dom'; +import UIRouterReact, {UIView, UISref, UISrefActive} from 'ui-router-react'; + + +const router = new UIRouterReact(); + +var helloState = { + name: 'hello', + url: '/hello', + component: () =>

hello world

+} + +var aboutState = { + name: 'about', + url: '/about', + component: () =>

Its the UI-Router hello world app!

+} + +router.stateRegistry.register(helloState); +router.stateRegistry.register(aboutState); + +router.start(); + +ReactDOM.render( +
+ + Hello + + + About + + + +
, + document.getElementById('react-app') +); +``` + +# Live demo + +A live demo of the finished app can be seen below, in the [Plunker](https://plnkr.co/). Navigate between the +"Hello" and "About" links and watch the UI change. + + +
+ +# Prepping Hello World + +Follow these steps to make your own copy of the Hello World app. + +## Get UI-Router + +Get the UI-Router for React code using npm + +``` +npm install ui-router-react +``` + +You could alternatively refer to the +[copy distributed on npmcdn.com](https://npmcdn.com/ui-router-react@latest/_bundles/ui-router-react.min.js). +(This is how the live demo plunkers function) + +## Configure your module loader + +React development requires a module loader and is best with a bundler, such as webpack. +There are many benefits to bundling, but one critical benefit for React is tree shaking capabilities, which eliminates unused code from the bundle. + +For these tutorials, however, we're going to use SystemJS and the full UMD bundles. +First, create an empty `helloworld.jsx` file. + +**SystemJS config.js** + +The `map` section of `systemjs.config.js` tells the System loader where to look for things. +Add an entry for `ui-router-react` in the `map:` section. +This entry must allow us to `import from 'ui-router-react'` and get the `ui-router-router` library entry point (`main:` from `package.json`). + +Add a second second entry for `helloworld` which will get us the helloworld app entry point. + +```js +... + map: { + "react": "//npmcdn.com/react@15/dist/react.js", + "react-dom": "//npmcdn.com/react-dom/dist/react-dom.js", + "ui-router-react": "//npmcdn.com/ui-router-react@latest/_bundles/ui-router-react.js", + "helloworld": "./" + }, + packages: { + helloworld: { + main: './helloworld.js', + defaultExtension: 'js' + } + } +... +``` + +SystemJS is a large, nuanced topic, but this is as far as we're going to discuss for this tutorial. + +## Script tags + +The scripts loaded from npmcdn are prerequisites for React + JSX running in a plunker. + +The `config.js` script is our SystemJS configuration. + +~~~html + + ... + + + ... +~~~ + +## Bootstrapping the javascript +This script tells the module loader to load `helloworld`, which is our application's entry point. + +```html + +``` + +# Building Hello World + +## ES6 imports + +In order to access the code required to bootstrap React and UI-Router, we need to import a bunch of things. + +```js +import React from 'react'; +import ReactDOM from 'react-dom'; +import UIRouterReact, {UIView, UISref, UISrefActive} from 'ui-router-react'; +``` + +## Creating the components + +Create the React components that make up our application. + +**The `Hello` and `About` components** + +Create two components for our two "pages". + +~~~js +const Hello = () =>

hello world

; +const About = () =>

Its the UI-Router hello world app!

+~~~ + +These two stateless components make up the two pages of our application. +One of these components will be shown, when its corresponding state is active. + +*Viewport* + +The application contains a `` viewport. +The `` viewport will be filled with the component from the currently active state. + +*Links* + +It also contains two anchor tags wrapped into `UISref` components. +The `UISref` components create a link and attach it to their child elements, similar to an anchor tag's `href`. +Instead of linking to a URL like an `href`, a `UISref` links to a state. + +When clicked, the linked state is activated. +The `UISref` component automatically builds a `href` attribute for you (``) based on your state's url. + +*Active Link* + +The `UISref` components are also wrapped by a ``, which is another component. +The addition of `UISrefActive` adds the `active` css class to the `UISref`'s child when the target state is active. + +## Instantiating the root component + +Inside the `` tag, we add markup for our application's components. + +```html + +
+ Loading... +
+ +``` + +## Create your first states + +A state is the basic building block for UI-Router applications. +This javascript object is a simple state definition. + +```js +let helloState = { name: 'hello', url: '/hello', component: Hello }; +``` + +This simple state definition has three properties: + +`name` +: The state is named `hello`. + +`url` +: When the state is active, the browser's url will be `/hello`. + +`component` +: The `component:` property value is the React component class that will be loaded into the viewport when the state is active. In this case, we will load the `Hello` component. + +Add the other about state: + +```js +let helloState = { name: 'hello', url: '/hello', component: Hello }; +let aboutState = { name: 'about', url: '/about', component: About }; +``` + +## Configure and start UIRouter + +We can create a new instance of the router and configure it with our states. + +```js +const router = new UIRouterReact(); + +router.stateRegistry.register(helloState); +router.stateRegistry.register(aboutState); + +router.start(); +``` + +The `.stateRegistry.register()` method takes care of registering our states. +The `.start()` method tells the Router to activate, listen for url changes and handle view changes. + +## Bootstrapping React + +Bootstrap React. + +```js +ReactDOM.render( +
+ + Hello + {' '} + + About + + + +
, + document.getElementById('react-app') +); +``` + +--- + +Go back to the [live demo](#live-demo) and check it out! + +When you're finished, move on to the [Hello Solar System!](hellosolarsystem) tutorial. + diff --git a/_tutorial_react/index.md b/_tutorial_react/index.md new file mode 100644 index 000000000000..ed5b58f95a4a --- /dev/null +++ b/_tutorial_react/index.md @@ -0,0 +1,7 @@ +--- +title: "UI-Router for React - Tutorials" +sitemap: true +permalink: /tutorial/react/ +--- + +[Get started](helloworld) \ No newline at end of file