Client Generator: Mercure support and various improvements

Author: dunglas

client-generator/images/demo.gif

@@ -1,24 +1,31 @@
 # The API Platform Client Generator
 
-API Platform Client Generator is a generator for scaffolding apps with Create-Retrieve-Update-Delete features for any API exposing a Hydra documentation. Currently the following targets are available:
+Client Generator is the fastest way to scaffold fully-featured webapps and native mobile apps from APIs supporting the [Hydra](http://www.hydra-cg.com/) format.
 
- * React/Redux
- * React Native
- * Vue.js
+![Screencast](images/demo.gif)
+*Generated React and React Native apps communicating updated in real time* 
 
-The generator works especially well with APIs built with the [API Platform](https://api-platform.com) framework.
+It is able to generate apps using the following frontend stacks:
+
+* [React with Redux](react.md)
+* [React Native](react-native.md)
+* [Vue.js](vuejs.md)
+
+Client Generator works especially well with APIs built with the [API Platform](https://api-platform.com) framework.
 
 ## Features
 
-* Generate high-quality ES6 components and files built with [React](https://facebook.github.io/react/), [Redux](http://redux.js.org), [React Router](https://reacttraining.com/react-router/) and [Redux Form](http://redux-form.com/) including:
-  * A list view
-  * A creation form
-  * An editing form
-  * A delete button
-* Use the Hydra API documentation to generate the code
-* Generate the suitable HTML5 input type (`number`, `date`...) according to the type of the API property
-* Display of the server-side validation errors under the related input (if using API Platform Core)
-* Client-side validation (`required` attributes)
-* The generated HTML is compatible with [Bootstrap](https://getbootstrap.com/) and includes mandatory classes
-* The generated HTML code is accessible to people with disabilities ([ARIA](https://www.w3.org/WAI/intro/aria) support)
-* The Redux and the React Router configuration is also generated
+* Generate high-quality ES6:
+  * list view (with pagination)
+  * detail view
+  * creation form
+  * edition form
+  * delete button
+* Support to-one and to-many relations
+* Use the appropriate input type (`number`, `date`...)
+* Client-side validation
+* Subscribe to data updates pushed by server supporting [the Mercure protocol](https://mercure.rocks)
+* Display server-side validation errors under the related input (if using API Platform Core)
+* Integration with [Bootstrap](https://getbootstrap.com/) and [FontAwesome](https://fontawesome.com/) (Progressive Web Apps)
+* Integration with [React Native Elements](https://react-native-training.github.io/react-native-elements/)
+* Accessible to people with disabilities ([ARIA](https://www.w3.org/WAI/intro/aria) support in webapps)

client-generator/images/adnew.png renamed to client-generator/images/react-native/add.png

@@ -1,40 +1,44 @@
-React Native generator
-======================
+# React Native generator
 
-Create a React Native application using [React Community's Create React Native App](https://github.com/react-community/create-react-native-app)
+![List](images/list.png) 
+
+## Install
+
+To use this generator you need a proper [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/) (or NPM) installation.
+To run the command line tool, we also recommend using [npx](https://www.npmjs.com/package/npx).
+
+Create a React Native application using [Expo CLI](https://docs.expo.io/versions/latest/workflow/expo-cli).
 
 ```bash
-$ yarn add -g expo-cli
+$ yarn global add expo-cli
 $ expo init my-app
+# When asked, choose to use the blank template
 $ cd my-app
 ```
 
-Install:  React Native Elements, React Native Router Flux, React Native Vector Icons, Redux, React Redux, Redux Thunk, Redux Form, Prop Types
+Install the requires dependencies:
 
 ```bash
-$ yarn add redux react-redux redux-thunk redux-form react-native-elements react-native-router-flux 
-react-native-vector-icons prop-types
+$ yarn add redux react-redux redux-thunk redux-form react-native-elements react-native-router-flux react-native-vector-icons prop-types whatwg-url buffer react-native-event-source
 ```
 
-Install the generator globally:
+## Generating a Native App
+
+In the app directory, generate the files for the resource you want:
 
 ```bash
-$ yarn global add @api-platform/client-generator
+$ npx @api-platform/client-generator https://demo.api-platform.com . -g react-native --resource book
 ```
 
-In the app directory, generate the files for the resource you want:
+Replace the URL by the entrypoint of your Hydra-enabled API.
+Omit the resource flag to generate files for all resource types exposed by the API.
 
-```
-    $ generate-api-platform-client https://demo.api-platform.com  -g react-native --resource foo
-    # Replace the URL by the entrypoint of your Hydra-enabled API
-    # Omit the resource flag to generate files for all resource types exposed by the API
-```
-Create **Router.js** file to import all routes
+Create a `Router.js` file to import all routes:
 
 ```javascript
 import React from 'react';
 import { Router, Stack } from 'react-native-router-flux';
-//replace "book" with the name of resource type
+// Replace "book" with the name of the resource type
 import BookRoutes from './routes/book';
 
 const RouterComponent = () => {
@@ -49,16 +53,31 @@ const RouterComponent = () => {
 
 export default RouterComponent;
 ```
-Here is an example of  **App.js**
+
+Here is an example of a `App.js` file:
 
 ```javascript
 import React, { Component } from 'react';
 import { Provider } from 'react-redux';
 import thunk from 'redux-thunk';
-import { createStore, applyMiddleware, combineReducers} from 'redux';
+import { createStore, applyMiddleware, combineReducers } from 'redux';
 import { View } from 'react-native';
 import {reducer as form} from 'redux-form';
-//replace "book" with the name of resource type
+
+// see https://github.com/facebook/react-native/issues/14796
+import { Buffer } from 'buffer';
+global.Buffer = Buffer;
+
+// see https://github.com/facebook/react-native/issues/16434
+import { URL, URLSearchParams } from 'whatwg-url';
+global.URL = URL;
+global.URLSearchParams = URLSearchParams;
+
+// see https://github.com/facebook/react-native/issues/12890
+import RNEventSource from 'react-native-event-source';
+global.EventSource = RNEventSource;
+
+// Replace "book" with the name of resource type
 import book from './reducers/book';
 import Router from './Router';
 
@@ -80,11 +99,12 @@ export default class App extends Component {
 ```
 
 The code is ready to be executed!
+
 ```bash
 $ expo start
 ```
 
-#### Example of running  application on IOS simulator
+## Screenshots in iOS Simulator
 
-![List](images/list.png) ![Show](images/item.png)
- ![Add](images/adnew.png) ![Delete](images/del.png)
+![List](images/react-native/list.png) ![Show](images/react-native/show.png)
+![Add](images/react-native/add.png) ![Delete](images/react-native/delete.png)

client-generator/images/del.png renamed to client-generator/images/react-native/delete.png

@@ -1,83 +1,113 @@
-# React generator
+# React Generator
 
-Create a React application using [Facebook's Create React App](https://github.com/facebookincubator/create-react-app):
+![List screenshot](images/react/list.png)
 
-    $ create-react-app my-app
-    $ cd my-app
+The React Client Generator generate a Progressive Web App built with battle-tested libraries from the ecosystem:
 
-Install React Router, Redux, React Redux, React Router Redux, Redux Form and Redux Thunk (to handle AJAX requests):
+* [React](https://facebook.github.io/react/)
+* [Redux](http://redux.js.org)
+* [React Router](https://reacttraining.com/react-router/)
+* [Redux Form](http://redux-form.com/)
 
-    $ yarn add redux react-redux redux-thunk redux-form react-router-dom react-router-redux prop-types
+It is designed to generate code that works seamlessly with [Facebook's Create React App](https://github.com/facebook/create-react-app).
 
-Install the generator globally:
+## Install
 
-    $ yarn global add @api-platform/client-generator
+The easiest way to get started is to install [the API Platform distribution](../distribution/index.md).
+It contains the React Client Generator, all dependencies it needs, a Progressive Web App skeleton generated with Create React App,
+a development Docker container to serve the webapp, and all the API Platform components you may need, including an API server
+supporting Hydra.
 
-Reference the Bootstrap CSS stylesheet in `public/index.html` (optional):
+If you use the API Platform, jump to the next section!
+Alternatively, you can generate a skeleton and install the generator using [npx](https://www.npmjs.com/package/npx).
+To run it, you need a proper [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/) (or NPM) installation.
 
-Bootstrap 3 - last release 0.1.15
-```html
-  <!-- ... -->
-    <title>React App</title>
+Bootstrap a React application:
 
-    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
-  </head>
-  <!-- ... -->
+```bash
+$ npx create-react-app client
+$ cd client
+```
+
+Install the required dependencies:
+
+```bash
+$ yarn add redux react-redux redux-thunk redux-form react-router-dom connected-react-router prop-types lodash
+```
+
+Optionally, install Bootstrap and Font Awesome to get an app that looks good:
+
+```bash
+$ yarn add redux bootstrap font-awesome
+```
+
+Finally, start the integrated web server:
+
+```bash
+$ yarn start
 ```
-Bootstrap 4 - from release 0.1.16
 
-```html
-  <!-- ... -->
-    <title>React App</title>
+## Generating a Progressive Web App
+
+If you use the API Platform distribution, generating all the code you need for a given resource is as simple as running the following command:
 
-    <link href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-/Y6pD6FV/Vv2HJnA6t+vslU6fwYXjCFtcEpHbNJ0lyAFsXTsjBbfaDjzALeQsN6M" crossorigin="anonymous">
-    <link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous">
-  </head>
-  <!-- ... -->
+```bash
+$ docker-compose exec client generate-api-platform-client --resource book
 ```
 
-In the app directory, generate the files for the resource you want:
+Omit the resource flag to generate files for all resource types exposed by the API.
+
+If you don't use a standalone installation, run the following command instead:
 
 ```bash
-$ generate-api-platform-client https://demo.api-platform.com src/ --resource book
+$ npx @api-platform/client-generator https://demo.api-platform.com src/ --resource book
 # Replace the URL by the entrypoint of your Hydra-enabled API
-# Omit the resource flag to generate files for all resource types exposed by the API
 ```
 
-The code is ready to be executed! Register the generated reducers and components in the `index.js` file, here is an example:
+The code has been generated, and is ready to be executed!
+Register the reducers and the routes in the `client/src/index.js` file:
 
 ```javascript
 import React from 'react';
 import ReactDOM from 'react-dom';
-import * as serviceWorker from './serviceWorker';
-
 import { createStore, combineReducers, applyMiddleware } from 'redux';
 import { Provider } from 'react-redux';
 import thunk from 'redux-thunk';
 import { reducer as form } from 'redux-form';
-import { BrowserRouter as Router, Route, Switch } from 'react-router-dom';
+import { Route, Switch } from 'react-router-dom';
 import createBrowserHistory from 'history/createBrowserHistory';
-import { syncHistoryWithStore, routerReducer as routing } from 'react-router-redux'
-
+import {
+  ConnectedRouter,
+  connectRouter,
+  routerMiddleware
+} from 'connected-react-router';
+import 'bootstrap/dist/css/bootstrap.css';
+import 'font-awesome/css/font-awesome.css';
+import * as serviceWorker from './serviceWorker';
 // Replace "book" with the name of the resource type
 import book from './reducers/book/';
 import bookRoutes from './routes/book';
 
+const history = createBrowserHistory();
 const store = createStore(
-  combineReducers({routing, form, book}), // Don't forget to register the reducers here
-  applyMiddleware(thunk),
+  combineReducers({
+    router: connectRouter(history),
+    form,
+    book
+    /* Replace book with the name of the resource type */
+  }),
+  applyMiddleware(routerMiddleware(history), thunk)
 );
 
-const history = syncHistoryWithStore(createBrowserHistory(), store);
-
 ReactDOM.render(
   <Provider store={store}>
-    <Router history={history}>
+    <ConnectedRouter history={history}>
       <Switch>
         {bookRoutes}
-        <Route render={() => <h1>Not Found</h1>}/>
+        {/* Replace bookRooutes with the name of the resource type */}
+        <Route render={() => <h1>Not Found</h1>} />
       </Switch>
-    </Router>
+    </ConnectedRouter>
   </Provider>,
   document.getElementById('root')
 );
@@ -87,3 +117,14 @@ ReactDOM.render(
 // Learn more about service workers: http://bit.ly/CRA-PWA
 serviceWorker.unregister();
 ```
+
+Go to `https://localhost/books/` to start using your app.
+That's all!
+
+## Screenshots
+
+![List](images/react/list.png)
+![Pagination](images/react/list-pagination.png)
+![Show](images/react/show.png)
+![Edit](images/react/edit.png)
+![Delete](images/react/delete.png)

client-generator/images/list.png renamed to client-generator/images/react-native/list.png

@@ -1,4 +1,4 @@
-# Vue.js generator
+# Vue.js Generator
 
 Create a Vue.js application using [vue-cli](https://github.com/vuejs/vue-cli):