Merge branch '2.3'

Author: dunglas

admin/getting-started.md

@@ -228,3 +228,170 @@ export default class extends Component {
   }
 }
 ```
+
+### Using the Hydra Data Provider Directly with react-admin
+
+By default, the `HydraAdmin` component shipped with API Platform Admin will generate a convenient admin interface for every resources and every properties exposed by the API. But sometimes, you may prefer having full control over the generated admin.
+
+To do so, an alternative approach is [to configure every react-admin components manually](https://marmelab.com/react-admin/Tutorial.html) instead of letting the library generating it, but to still leverage the built-in Hydra [data provider](https://marmelab.com/react-admin/DataProviders.html):
+
+```javascript
+// admin/src/App.js
+
+import React, { Component } from 'react';
+import { Admin, Resource } from 'react-admin';
+import parseHydraDocumentation from '@api-platform/api-doc-parser/lib/hydra/parseHydraDocumentation';
+import { hydraClient, fetchHydra as baseFetchHydra  } from '@api-platform/admin';
+import authProvider from './authProvider';
+import { Redirect } from 'react-router-dom';
+import { createMuiTheme } from '@material-ui/core/styles';
+import Layout from './Component/Layout';
+import { UserShow } from './Components/User/Show';
+import { UserEdit } from './Components/User/Edit';
+import { UserCreate } from './Components/User/Create';
+import { UserList } from './Components/User/List';
+
+const theme = createMuiTheme({
+    palette: {
+        type: 'light'
+    },
+});
+
+const entrypoint = process.env.REACT_APP_API_ENTRYPOINT;
+const fetchHeaders = {'Authorization': `Bearer ${window.localStorage.getItem('token')}`};
+const fetchHydra = (url, options = {}) => baseFetchHydra(url, {
+    ...options,
+    headers: new Headers(fetchHeaders),
+});
+const dataProvider = api => hydraClient(api, fetchHydra);
+const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint, { headers: new Headers(fetchHeaders) })
+    .then(
+        ({ api }) => ({api}),
+        (result) => {
+            switch (result.status) {
+                case 401:
+                    return Promise.resolve({
+                        api: result.api,
+                        customRoutes: [{
+                            props: {
+                                path: '/',
+                                render: () => <Redirect to={`/login`}/>,
+                            },
+                        }],
+                    });
+
+                default:
+                    return Promise.reject(result);
+            }
+        },
+    );
+
+export default class extends Component {
+    state = { api: null };
+
+    componentDidMount() {
+        apiDocumentationParser(entrypoint).then(({ api }) => {
+            this.setState({ api });
+        }).catch((e) => {
+            console.log(e);
+        });
+    }
+
+    render() {
+        if (null === this.state.api) return <div>Loading...</div>;
+        return (
+            <Admin api={ this.state.api }
+                   apiDocumentationParser={ apiDocumentationParser }
+                   dataProvider= { dataProvider(this.state.api) }
+                   theme={ theme }
+                   appLayout={ Layout }
+                   authProvider={ authProvider }          
+            >                
+                <Resource name="users" list={ UserList } create={ UserCreate } show={ UserShow } edit={ UserEdit } title="Users"/>
+            </Admin>
+        )
+    }
+}
+```
+
+And accordingly create files `Show.js`, `Create.js`, `List.js`, `Edit.js`
+in the `admin/src/Component/User` directory:
+
+```javascript
+// admin/src/Component/User/Create.js
+
+import React from 'react';
+import { Create, SimpleForm, TextInput, email, required } from 'react-admin';
+
+export const UserCreate = (props) => (
+    <Create { ...props }>
+        <SimpleForm>
+            <TextInput source="email" label="Email" validate={ email() } />
+            <TextInput source="plainPassword" label="Password" validate={ required() } />
+            <TextInput source="name" label="Name"/>
+            <TextInput source="phone" label="Phone"/>
+        </SimpleForm>
+    </Create>
+);
+
+```
+
+```javascript
+// admin/src/Component/User/Edit.js
+
+import React from 'react';
+import { Edit, SimpleForm, DisabledInput, TextInput, DateInput, email } from 'react-admin';
+
+export const UserEdit = (props) => (
+    <Edit {...props}>
+        <SimpleForm>
+            <DisabledInput source="originId" label="ID"/>
+            <TextInput source="email" label="Email" validate={ email() } />
+            <TextInput source="name" label="Name"/>
+            <TextInput source="phone" label="Phone"/>
+            <DateInput disabled source="createdAt" label="Date"/>
+        </SimpleForm>
+    </Edit>
+);
+```
+
+```javascript
+// admin/src/Component/User/List.js
+
+import React from 'react';
+import { List, Datagrid, TextField, EmailField, DateField, ShowButton, EditButton } from 'react-admin';
+import { CustomPagination } from '../Pagination/CustomPagination';
+
+export const UserList = (props) => (
+    <List {...props} title="Users" pagination={ <CustomPagination/> }  perPage={ 30 }>
+        <Datagrid>
+            <TextField source="originId" label="ID"/>
+            <EmailField source="email" label="Email" />
+            <TextField source="name" label="Name"/>
+            <TextField source="phone" label="Phone"/>
+            <DateField source="createdAt" label="Date"/>
+            <ShowButton />
+            <EditButton />
+        </Datagrid>
+    </List>
+);
+```
+
+```javascript
+// admin/src/Component/User/Show.js
+import React from 'react';
+import { Show, SimpleShowLayout, TextField, DateField, EmailField, EditButton } from 'react-admin';
+
+export const UserShow = (props) => (
+    <Show { ...props }>
+        <SimpleShowLayout>
+            <TextField source="originId" label="ID"/>
+            <EmailField source="email" label="Email" />
+            <TextField source="name" label="Name"/>
+            <TextField source="phone" label="Phone"/>
+            <DateField source="createdAt" label="Date"/>
+            <EditButton />
+        </SimpleShowLayout>
+    </Show>
+);
+```

client-generator/images/demo.gif

@@ -1,24 +1,32 @@
 # 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)
 
-The generator works especially well with APIs built with the [API Platform](https://api-platform.com) framework.
+*Generated React and React Native apps, updated in real time* 
+
+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
+* Supports to-one and to-many relations
+* Uses the appropriate input type (`number`, `date`...)
+* Client-side validation
+* Subscribe to data updates pushed by servers 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 [Node.js](https://nodejs.org/) and [Yarn](https://yarnpkg.com/) (or [NPM](https://www.npmjs.com/)) installed.
+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 required 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 with 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 an `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)