Merge branch '2.1'

Author: dunglas

admin/authentication-support.md

@@ -2,28 +2,25 @@
 
 Authentication can easily be handled when using the API Platform's admin library.
 In the following section, we will assume [the API is secured using JWT](https://api-platform.com/docs/core/jwt), but the
-process is similar for other authentication mechanisms.
+process is similar for other authentication mechanisms. The `login_uri` is the full URI to the route specified by the `firewalls.login.json_login.check_path` config in the [JWT documentation](https://api-platform.com/docs/core/jwt). 
 
 The first step is to create a client to handle the authentication process:
 
 ```javascript
-import { AUTH_LOGIN, AUTH_LOGOUT, AUTH_ERROR } from 'admin-on-rest';
+// src/authClient.js
+import { AUTH_LOGIN, AUTH_LOGOUT, AUTH_ERROR, AUTH_CHECK } from 'admin-on-rest';
 
-const entrypoint = 'https://demo.api-platform.com'; // Change this by your own entrypoint
+// Change this to be your own login check route.
+const login_uri = 'https://demo.api-platform.com/login_check'; 
 
 export default (type, params) => {
   switch (type) {
     case AUTH_LOGIN:
       const { username, password } = params;
-      const request = new Request(`${API_ENTRYPOINT}/login`, {
-          body: JSON.stringify({
-              username: params.username,
-              password: params.password,
-          }),
-          headers: new Headers({
-              'Content-Type': 'application/json',
-          }),
-          method: 'POST',
+      const request = new Request(`${login_uri}`, {
+        method: 'POST',
+        body: JSON.stringify({ email: username, password }),
+        headers: new Headers({ 'Content-Type': 'application/json' }),
       });
 
       return fetch(request)
@@ -48,6 +45,9 @@ export default (type, params) => {
         return Promise.reject();
       }
       break;
+
+    case AUTH_CHECK:
+      return localStorage.getItem('token') ? Promise.resolve() : Promise.reject();
 
       default:
           return Promise.resolve();
@@ -59,24 +59,18 @@ Then, configure the `Admin` component to use the authentication client we just c
 
 ```javascript
 import React from 'react';
-import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocumentation';
-import { HydraAdmin, hydraClient, fetchHydra  as baseFetchHydra } from '@api-platform/admin';
+import parseHydraDocumentation from '@api-platform/api-doc-parser/lib/hydra/parseHydraDocumentation';
+import { HydraAdmin, hydraClient, fetchHydra as baseFetchHydra } from '@api-platform/admin';
 import authClient from './authClient';
 import { Redirect } from 'react-router-dom';
 
 const entrypoint = 'https://demo.api-platform.com'; // Change this by your own entrypoint
-
-const fetchHeaders = {
-    'Authorization': `Bearer ${window.localStorage.getItem('token')}`,
-};
-
+const fetchHeaders = {'Authorization': `Bearer ${window.localStorage.getItem('token')}`};
 const fetchHydra = (url, options = {}) => baseFetchHydra(url, {
     ...options,
     headers: new Headers(fetchHeaders),
 });
-
 const restClient = api => hydraClient(api, fetchHydra);
-
 const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint, { headers: new Headers(fetchHeaders) })
     .then(
         ({ api }) => ({ api }),
@@ -85,24 +79,19 @@ const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint,
                 case 401:
                     return Promise.resolve({
                         api: result.api,
-                        customRoutes: [
-                            {
-                                props: {
-                                    path: '/',
-                                    render: () => (
-                                        <Redirect to={`/login`}/>
-                                    ),
-                                },
+                        customRoutes: [{
+                            props: {
+                                path: '/',
+                                render: () => <Redirect to={`/login`}/>,
                             },
-                        ],
+                        }],
                     });
 
                 default:
                     return Promise.reject(result);
             }
         },
-    )
-;
+    );
 
 export default props => (
     <HydraAdmin
@@ -112,8 +101,6 @@ export default props => (
         restClient={restClient}
     />
 );
-
-export default Admin;
 ```
 
 Refer to [the chapter dedicated to authentication in the Admin On Rest documentation](https://marmelab.com/admin-on-rest/Authentication.html)

admin/getting-started.md

@@ -28,24 +28,16 @@ Finally, install the `@api-platform/admin` library:
 Edit the `src/App.js` file like the following:
 
 ```javascript
-import React, { Component } from 'react';
+import React from 'react';
 import { HydraAdmin } from '@api-platform/admin';
 
-class App extends Component {
-  render() {
-    return <HydraAdmin entrypoint="https://demo.api-platform.com"/> // Replace with your own API entrypoint
-  }
-}
-
-export default App;
+export default () => <HydraAdmin entrypoint="https://demo.api-platform.com"/>; // Replace with your own API entrypoint
 ```
 
 Your new administration interface is ready! Type `yarn start` to try it!
 
 Note: if you don't want to hardcode the API URL, you can [use an environment variable](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#adding-custom-environment-variables).
 
-Note: make sure `entrypoint` does not end with a `/`.
-
 ## Customizing the Admin
 
 The API Platform's admin parses the Hydra documentation exposed by the API and transforms it to an object data structure. This data structure can be customized to add, remove or customize resources and properties. To do so, we can leverage the `AdminBuilder` component provided by the library. It's a lower level component than the `HydraAdmin` one we used in the previous example. It allows to access to the object storing the structure of admin's screens.
@@ -78,9 +70,7 @@ const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
   })
 ;
 
-export default (props) => (
-  <HydraAdmin apiDocumentationParser={apiDocumentationParser} entrypoint={entrypoint}/>
-);
+export default (props) => <HydraAdmin apiDocumentationParser={apiDocumentationParser} entrypoint={entrypoint}/>;
 ```
 
 The `fieldComponent` property of the `Field` class allows to set the component used to render a property in list and show screens.
@@ -157,9 +147,7 @@ const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
   })
 ;
 
-export default (props) => (
-  <HydraAdmin apiDocumentationParser={apiDocumentationParser} entrypoint={entrypoint}/>
-);
+export default (props) => <HydraAdmin apiDocumentationParser={apiDocumentationParser} entrypoint={entrypoint}/>;
 ```
 
 __Note__: In this example, we choose to send the file via a multi-part form data, but you are totally free to use another solution (like `base64`). But keep in mind that multi-part form data is the most efficient solution.
@@ -176,7 +164,7 @@ import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocument
 
 const entrypoint = 'https://demo.api-platform.com';
 
-class App extends Component {
+export default class extends Component {
   state = {api: null};
 
   componentDidMount() {
@@ -197,8 +185,6 @@ class App extends Component {
     return <AdminBuilder api={this.state.api} restClient={hydraClient(entrypoint)}/>
   }
 }
-
-export default App;
 ```
 
 Previous chapter: [Introduction](index.md)

admin/handling-relations-to-collections.md

@@ -3,7 +3,7 @@
 Currently, API Platform Admin doesn't handle `to-many` relations. The core library [is being patched](https://github.com/api-platform/core/pull/1189)
 to document relations to collections through OWL.
 
-During the meantime, it is possible to configure manually API Platform to handle relations to collections.
+In the meantime, it is possible to manually configure API Platform to handle relations to collections.
 
 We will create the admin for an API exposing `Person` and `Book` resources linked with a `many-to-many`
 relation between them (trough the `authors` property).
@@ -77,18 +77,16 @@ Let's customize the components used for the `authors` property:
 ```javascript
 import React, { Component } from 'react';
 import { ReferenceArrayField, SingleFieldList, ChipField, ReferenceArrayInput, SelectArrayInput } from 'admin-on-rest';
-import { AdminBuilder, hydraClient } from 'api-platform-admin';
+import { AdminBuilder, hydraClient } from '@api-platform/admin';
 import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocumentation';
 
 const entrypoint = 'https://demo.api-platform.com';
 
-class Admin extends Component {
-  state = {api: null};
+export default class extends Component {
+  state = {api: null, resources: null};
 
   componentDidMount() {
-    parseHydraDocumentation(entrypoint).then(api => {
-        const r = api.resources;
-
+    parseHydraDocumentation(entrypoint).then({api, resources} => {
         const books = r.find(r => 'books' === r.name);
 
         // Set the field in the list and the show views
@@ -107,31 +105,29 @@ class Admin extends Component {
           </ReferenceArrayInput>
         ;
 
-        this.setState({api: api});
+        this.setState({api, resources});
       }
     )
   }
 
   render() {
     if (null === this.state.api) return <div>Loading...</div>;
 
-    return <AdminBuilder api={this.state.api} restClient={hydraClient(entrypoint)}/>
+    return <AdminBuilder api={this.state.api} restClient={hydraClient({entrypoint: entrypoint, resources: this.state.resources})}/>
   }
 }
-
-export default Admin;
 ```
 
-The admin now properly handle this `to-many` relation!
+The admin now properly handles this `to-many` relation!
 
 ## Using an Autocomplete Input for Relations
 
-We'll do a last improvement to our admin: transform the relation selector we just created to use autocompletion.
+We'll make one last improvement to our admin: transforming the relation selector we just created to use autocompletion.
 
 Start by adding a "partial search" filter on the `name` property of the `Book` resource class.
 
 ```yaml
-# etc/packages/api_platform.yaml
+# config/api_filters.yml
 
 services:
     person.search_filter:

client-generator/index.md

@@ -1,23 +1,24 @@
 # The API Platform Client Generator
 
-API Platform Client Generator is a generator to scaffold app with Create-Retrieve-Update-Delete features for any API exposing a Hydra documentation for:
+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:
+
  * React/Redux
  * Vue.js
 
-Works especially well with APIs built with the [API Platform](https://api-platform.com) framework.
+The 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 edition form
-  * A deletion button
+  * 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 include mandatory classes
+* 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
 

client-generator/react.md

@@ -15,14 +15,27 @@ Install the generator globally:
 
 Reference the Bootstrap CSS stylesheet in `public/index.html` (optional):
 
+Bootstrap 3 - last release 0.1.15
 ```html
   <!-- ... -->
     <title>React App</title>
-
+    
     <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
   </head>
   <!-- ... -->
 ```
+Bootstrap 4 - from release 0.1.16
+
+```html
+  <!-- ... -->
+    <title>React App</title>
+    
+    <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>
+  <!-- ... -->
+```
+
 
 In the app directory, generate the files for the resource you want:
 
@@ -35,6 +48,7 @@ The code is ready to be executed! Register the generated reducers and components
 ```javascript
 import React from 'react';
 import ReactDom from 'react-dom';
+import registerServiceWorker from './registerServiceWorker';
 import { createStore, combineReducers, applyMiddleware } from 'redux';
 import { Provider } from 'react-redux';
 import thunk from 'redux-thunk';
@@ -43,7 +57,7 @@ import { BrowserRouter as Router, Route, Switch } from 'react-router-dom';
 import createBrowserHistory from 'history/createBrowserHistory';
 import { syncHistoryWithStore, routerReducer as routing } from 'react-router-redux'
 
-// Replace "foo" by the name of the resource type
+// Replace "foo" with the name of the resource type
 import foo from './reducers/foo/';
 import fooRoutes from './routes/foo';
 
@@ -65,6 +79,8 @@ ReactDom.render(
   </Provider>,
   document.getElementById('root')
 );
+
+registerServiceWorker();
 ```
 
 Previous chapter: [Introduction](index.md)

client-generator/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting
 
-* The generator does not perform any authentication, so you must ensure that all referenced hydra paths for your API are
+* The generator does not perform any authentication, so you must ensure that all referenced Hydra paths for your API are
 accessible anonymously. If you are using API Platform this will at least include:
 
   ```

client-generator/vuejs.md

@@ -38,7 +38,7 @@ import Vuex from 'vuex';
 import VueRouter from 'vue-router';
 import App from './App.vue';
 
-// Replace "foo" by the name of the resource type
+// Replace "foo" with the name of the resource type
 import foo from './store/modules/foo/';
 import fooRoutes from './routes/foo';
 
@@ -89,7 +89,7 @@ Replace the `App.vue` file with the following :
   <div class="container">
     <nav>
       <ul class="nav nav-justified">
-        <!-- Replace Foo by your resource name -->
+        <!-- Replace Foo with your resource name -->
         <li class="active"><router-link :to="{ name: 'FooList' }" class="active">Foos</router-link></li>
       </ul>
     </nav>

core/content-negotiation.md

@@ -11,10 +11,10 @@ Both XML and JSON formats are experimental and there are no assurance that we wi
 
 API Platform Core will automatically detect the best resolving format depending on:
 
-* enabled formats (link to docs for this / see below)
-* the `Accept` HTTP header
-* Alternatively to send the proper `Accept` HTTP header, you can also request a specific format by adding its name as the extension of the URL.
-* Available formats are :
+* enabled formats (see below)
+* the requested format, specified in either the `Accept` HTTP header or as an extension appended to the URL
+
+Available formats are:
 
 Format                                                          | Format name  | MIME types                    | Backward Compatibility guaranteed
 ----------------------------------------------------------------|--------------|-------------------------------|----------------------------------------
@@ -134,8 +134,8 @@ final class CustomItemNormalizer implements NormalizerInterface, DenormalizerInt
 }
 ```
 
-For example if you want to make the `csv` format to work for even complex entities with a lot of hierarchy, you have
-to flatten or remove too complex relations:
+For example if you want to make the `csv` format work for even complex entities with a lot of hierarchy, you have to
+flatten or remove too complex relations:
 
 ```php
 <?php