|
1 | | -# React from Markup |
| 1 | +# react-from-markup |
2 | 2 |
|
3 | | -> Declare your React components with static HTML |
| 3 | +> Declare your React props with `data-` attributes |
4 | 4 |
|
5 | | -## Why? |
| 5 | +## Intro |
6 | 6 |
|
7 | | -Sometimes, your tech stack doesn’t speak JavaScript very well. |
| 7 | +`react-from-markup` converts this |
8 | 8 |
|
9 | | -This can be a particular problem with some CMS, or legacy systems. React is a JavaScript library, and oftentimes, it’s difficult to create the bootstrapping JavaScript from your templating system. |
| 9 | +```html |
| 10 | +<div |
| 11 | + data-rehydratable="ShowMore" |
| 12 | + data-content="Hello, World!" |
| 13 | +> |
| 14 | + Hello, World! |
| 15 | +</div> |
| 16 | +``` |
10 | 17 |
|
11 | | -`react-from-markup` is intended to make it possible to use React components on these legacy systems, _without changing the way you write your React components_. It provides tools to simplify the mapping from `data-` attributes into React props, and _can even handle React children_. |
| 18 | +into this |
12 | 19 |
|
13 | | -The result: React can be used to build a component library, useable by other React apps, but you don’t need to write a second component library for your legacy systems, or a second set of non-React JavaScript. You just need to integrate new markup into your non-React templates, and run a script on page load to initialize. |
| 20 | +```jsx |
| 21 | +<ShowMore content="Hello, World!" /> |
| 22 | +``` |
14 | 23 |
|
15 | | -## Notable uses |
| 24 | +using a _rehydrator_: |
| 25 | + |
| 26 | +```jsx |
| 27 | +import ShowMore from "./ShowMore"; |
| 28 | + |
| 29 | +export default async domNode => { |
| 30 | + return <ShowMore content={domNode.getAttribute("data-content")} />; |
| 31 | +}; |
| 32 | +``` |
| 33 | + |
| 34 | +This is extremely useful for changing React props in a non-React environment, like a CMS with its own templating language. |
| 35 | + |
| 36 | +## Features |
| 37 | + |
| 38 | +- Convert static markup into React components |
| 39 | +- Rehydrate React children |
| 40 | +- Asynchronous rehydration |
| 41 | +- Much more |
| 42 | + |
| 43 | +## Quick start |
| 44 | + |
| 45 | +Install `react-from-markup` |
| 46 | + |
| 47 | +```sh |
| 48 | +npm install react-from-markup --save |
| 49 | +``` |
| 50 | + |
| 51 | +Annotate your component’s markup with `data-` attributes for each prop, and a `data-rehydratable` attribute to let `react-from-markup` identify your component. |
| 52 | + |
| 53 | +```jsx |
| 54 | +// components/ShowMore/index.jsx |
| 55 | +export default ({ content }) => { |
| 56 | + <div data-content={content} data-rehydratable="ShowMore"> |
| 57 | + {content} |
| 58 | + </div>; |
| 59 | +}; |
| 60 | +``` |
16 | 61 |
|
17 | | -- Thomson Reuters uses `react-from-markup` on its Enterprise Web Platform. It runs on Adobe Experience Manager and HTL, and powers thomsonreuters.com, business unit sites, and campaign pages. It’s also used on their blog network, a WordPress-based platform of blogs. The same React-based component library is able to back each platform, and is also used in several non-`react-from-markup` sites that were able to use React directly, such as the [2017 Annual Report](https://ar.tr.com). |
| 62 | +Write a rehydrator for your component, to describe how to map static data back to React props: |
18 | 63 |
|
19 | | -## Documentation |
| 64 | +```jsx |
| 65 | +// components/ShowMore/rehydrator.jsx |
| 66 | +import ShowMore from "./ShowMore"; |
| 67 | + |
| 68 | +export default async domNode => { |
| 69 | + return <ShowMore content={domNode.getAttribute("data-content")} />; |
| 70 | +}; |
| 71 | +``` |
| 72 | + |
| 73 | +Add your component to your page, wrapping it in a _markup-container_. `react-from-markup` will only rehydrate markup inside this. |
| 74 | + |
| 75 | +```html |
| 76 | +<!-- index.html --> |
| 77 | +<html> |
| 78 | + <body> |
| 79 | + <div id="root"> |
| 80 | + <div data-react-from-markup-container> |
| 81 | + <div data-rehydratable="ShowMore" data-content="Hello, World"> |
| 82 | + Hello, World |
| 83 | + </div> |
| 84 | + </div> |
| 85 | + </div> |
| 86 | + </body> |
| 87 | +</html> |
| 88 | +``` |
| 89 | + |
| 90 | +> Note, this markup could have been produced by React, using the `<ShowMore />` component. |
| 91 | +
|
| 92 | +Run `react-from-markup` on page load. |
| 93 | + |
| 94 | +```js |
| 95 | +// index.js |
| 96 | +import rehydrate from "react-from-markup"; |
| 97 | +import showMoreRehydrator from "./components/ShowMore/rehydrator"; |
| 98 | + |
| 99 | +rehydrate(document.getElementById("root"), { |
| 100 | + ShowMore: showMoreRehydrator |
| 101 | +}); |
| 102 | +``` |
| 103 | + |
| 104 | +## Full Documentation |
20 | 105 |
|
21 | 106 | In-depth documentation can be found [here](https://simon360.github.io/react-from-markup). |
| 107 | + |
| 108 | +## Notable uses |
| 109 | + |
| 110 | +- [Thomson Reuters](thomsonreuters.com) uses `react-from-markup` on its Enterprise Web Platform. It runs on Adobe Experience Manager and HTL, and powers thomsonreuters.com, business unit sites, and campaign pages. It’s also used on their blog network, a WordPress-based platform of blogs. The same React-based component library is able to back each platform, and is also used in several non-`react-from-markup` sites that were able to use React directly, such as the [2017 Annual Report](https://ar.tr.com). |
0 commit comments