API Platform Admin documentation

admin/authentication-support.md

@@ -0,0 +1,82 @@
+# Authentication Support
+
+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.
+
+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';
+
+const entrypoint = 'https://demo.api-platform.com'; // Change this by your own entrypoint
+
+export default (type, params) => {
+  switch (type) {
+    case AUTH_LOGIN:
+      const { username, password } = params;
+      const request = new Request(`${entrypoint}/login_check`, {
+        method: 'POST',
+        body: JSON.stringify({ email: username, password }),
+        headers: new Headers({ 'Content-Type': 'application/json' }),
+      });
+
+      return fetch(request)
+        .then(response => {
+          if (response.status < 200 || response.status >= 300) throw new Error(response.statusText);
+
+          return response.json();
+        })
+        .then(({ token }) => {
+          localStorage.setItem('token', token); // The JWT token is stored in the browser's local storage
+        });
+
+    case AUTH_LOGOUT:
+      localStorage.removeItem('token');
+      break;
+
+    case AUTH_ERROR:
+      if (401 === params.status || 403 === params.status) {
+        localStorage.removeItem('token');
+
+        return Promise.reject();
+      }
+      break;
+
+      default:
+          return Promise.resolve();
+  }
+}
+```
+
+Then, configure the `Admin` component to use the authentication client we just created:
+
+```javascript
+import React, { Component } from 'react';
+import { HydraAdmin, hydraClient, fetchHydra } from 'api-platform-admin';
+import authClient from './authClient';
+
+const entrypoint = 'https://demo.api-platform.com';
+
+const fetchWithAuth = (url, options = {}) => {
+  if (!options.headers) options.headers = new Headers({ Accept: 'application/ld+json' });
+
+  options.headers.set('Authorization', `Bearer ${localStorage.getItem('token')}`);
+  return fetchHydra(url, options);
+};
+
+class Admin extends Component {
+  render() {
+    return <HydraAdmin entrypoint={entrypoint} restClient={hydraClient(entrypoint, fetchWithAuth)} authClient={authClient}/>
+  }
+}
+
+export default Admin;
+```
+
+Refer to [the chapter dedicated to authentication in the Admin On Rest documentation](https://marmelab.com/admin-on-rest/Authentication.html)
+for more information.
+
+Previous chapter: [Getting Started](getting-started.md)
+
+Next chapter: [Handling Relations to Collections](handling-relations-to-collections.md)

admin/getting-started.md

@@ -0,0 +1,205 @@
+# Getting Started
+
+## Installation
+
+Install the skeleton and the library:
+
+Start by installing [the Yarn package manager](https://yarnpkg.com/) ([NPM](https://www.npmjs.com/) is also supported) and
+the [Create React App](https://github.com/facebookincubator/create-react-app) tool.
+
+Then, create a new React application for your admin:
+
+    $ create-react-app my-admin
+
+**Warning:** Admin On Rest and Material UI [aren't compatible with React 15.6 yet](https://github.com/marmelab/admin-on-rest/issues/802). During the meantime, you need to downgrade React to v15.5. Apply the following patch to `packages.json` then run `yarn upgrade` to downgrade:
+
+```patch
+-    "react": "^15.6.1",
++    "react": "~15.5.4",
+-    "react-dom": "^15.6.1",
++    "react-dom": "~15.5.4",
+```
+
+Now, add install `api-platform-admin` library in your newly created project:
+
+    $ yarn add api-platform-admin
+
+## Creating the Admin
+
+Edit the `src/App.js` file like the following:
+
+```javascript
+import React, { Component } 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;
+```
+
+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).
+
+## 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.
+
+### Using Custom Components
+
+In the following example, we change components used for the `description` property of the `books` resource to ones accepting HTML (respectively `RichTextField` that renders HTML markup and `RichTextInput`, a WYSWYG editor).
+(To use the `RichTextInput`, the `aor-rich-text-input` package is must be installed: `yarn add aor-rich-text-input`).
+
+```javascript
+import React from 'react';
+import { RichTextField } from 'admin-on-rest';
+import RichTextInput from 'aor-rich-text-input';
+import HydraAdmin from 'api-platform-admin/lib/hydra/HydraAdmin';
+import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocumentation';
+
+const entrypoint = 'https://demo.api-platform.com';
+
+const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
+  .then(api => {
+    api.resources.map(resource => {
+      const books = api.resources.find(r => 'books' === r.name);
+      books.fields.find(f => 'description' === f.name).fieldComponent = <RichTextField source="description" key="description"/>;
+      books.fields.find(f => 'description' === f.name).inputComponent = <RichTextInput source="description" key="description"/>;
+
+      return resource;
+    });
+
+    return api;
+  })
+;
+
+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.
+The `inputComponent` property allows to set the component to use to render the input used in create and edit screens.
+
+Any [field](https://marmelab.com/admin-on-rest/Fields.html) or [input](https://marmelab.com/admin-on-rest/Inputs.html) provided by the Admin On Rest library can be used.
+
+To go further, take a look to the "[Including admin-on-rest on another React app](https://marmelab.com/admin-on-rest/CustomApp.html)" documentation page of Admin On Rest to learn how to use directly redux, react-router, and redux-saga along with components provided by this library.
+
+### Managing Files and Images
+
+In the following example, we will:
+* find every [ImageObject](http://schema.org/ImageObject) resources. For each [contentUrl](http://schema.org/contentUrl) fields, we will use [ImageField](https://marmelab.com/admin-on-rest/Fields.html#imagefield) as `field` and [ImageInput](https://marmelab.com/admin-on-rest/Inputs.html#imageinput) as `input`.
+* [ImageInput](https://marmelab.com/admin-on-rest/Inputs.html#imageinput) will return a [File](https://developer.mozilla.org/en/docs/Web/API/File) instance. In this example, we will send a multi-part form data to a special action (`https://demo.api-platform.com/images/upload`). The action will return the ID of the uploaded image. We will "replace" the [File](https://developer.mozilla.org/en/docs/Web/API/File) instance by the ID in `normalizeData`.
+* As `contentUrl` fields will return a string, we have to convert Hydra data to AOR data. This action will be done by `denormalizeData`.
+
+```javascript
+import { FunctionField, ImageField, ImageInput } from 'admin-on-rest/lib/mui';
+import React from 'react';
+import HydraAdmin from 'api-platform-admin/lib/hydra/HydraAdmin';
+import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocumentation';
+
+const entrypoint = 'https://demo.api-platform.com';
+
+const apiDocumentationParser = entrypoint => parseHydraDocumentation(entrypoint)
+  .then(api => {
+    api.resources.map(resource => {
+      if ('http://schema.org/ImageObject' === resource.id) {
+        resource.fields.map(field => {
+          if ('http://schema.org/contentUrl' === field.id) {
+            field.denormalizeData = value => ({
+              src: value
+            });
+
+            field.fieldComponent = (
+              <FunctionField
+                key={field.name}
+                render={
+                  record => (
+                    <ImageField key={field.name} record={record} source={`${field.name}.src`}/>
+                  )
+                }
+                source={field.name}
+              />
+            );
+
+            field.inputComponent = (
+              <ImageInput accept="image/*" key={field.name} multiple={false} source={field.name}>
+                <ImageField source="src"/>
+              </ImageInput>
+            );
+
+            field.normalizeData = value => {
+              if (value[0] && value[0].rawFile instanceof File) {
+                const body = new FormData();
+                body.append('file', value[0].rawFile);
+
+                return fetch(`${entrypoint}/images/upload`, { body, method: 'POST' })
+                  .then(response => response.json());
+              }
+
+              return value.src;
+            };
+          }
+
+          return field;
+        });
+      }
+
+      return resource;
+    });
+
+    return api;
+  })
+;
+
+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.
+
+### Using a Custom Validation Function or Inject Custom Props
+
+You can use `fieldProps` and `inputProps` to respectively inject custom properties to fields and inputs generated by API
+Platform Admin. This is particularly useful to add custom validation rules:
+
+```javascript
+import React, { Component } from 'react';
+import { AdminBuilder, hydraClient } from 'api-platform-admin';
+import parseHydraDocumentation from 'api-doc-parser/lib/hydra/parseHydraDocumentation';
+
+const entrypoint = 'https://demo.api-platform.com';
+
+class App extends Component {
+  state = {api: null};
+
+  componentDidMount() {
+    parseHydraDocumentation(entrypoint).then(api => {
+      const books = api.resources.find(r => 'books' === r.name);
+
+      books.writableFields.find(f => 'description' === f.name).inputProps = {
+        validate: value => value.length >= 30 ? undefined : 'Minimum length: 30';
+      };
+
+      this.setState({api: api});
+    })
+  }
+
+  render() {
+    if (null === this.state.api) return <div>Loading...</div>;
+
+    return <AdminBuilder api={this.state.api} restClient={hydraClient(entrypoint)}/>
+  }
+}
+
+export default App;
+```
+
+Previous chapter: [Introduction](index.md)
+
+Next chapter: [Authentication Support](authentication-support.md)