Merge pull request #1290 from alanpoulain/merge-2.6

Merge 2.6

Author: alanpoulain

.github/workflows/cd.yml

@@ -0,0 +1,48 @@
+name: Deploy Website
+
+on:
+  push:
+    branches:
+    - main
+    - '*.*'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Checkout the website
+      uses: actions/checkout@v2
+      with:
+        repository: api-platform/website
+        ref: main
+
+    - name: Get yarn cache directory path
+      id: yarn-cache-dir-path
+      run: echo "::set-output name=dir::$(yarn cache dir)"
+
+    - uses: actions/cache@v2
+      id: yarn-cache
+      with:
+        path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
+        key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-yarn-
+
+    - name: Install deps
+      run: yarn install
+
+    - name: Retrieve docs
+      run: bin/retrieve-documentation
+
+    - name: Build website
+      env:
+        GITHUB_KEY: ${{ secrets.CONTRIBUTORS_GITHUB_TOKEN }}
+      run: yarn gatsby build
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./public
+        cname: api-platform.com

.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: Lint
+
+on:
+  - push
+  - pull_request
+
+jobs:
+  build:
+    name: Lint
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+
+      - name: Lint
+        uses: github/super-linter@v3
+        env:
+          VALIDATE_ALL_CODEBASE: false
+          VALIDATE_EDITORCONFIG: false
+          VALIDATE_JSCPD: false
+          DEFAULT_BRANCH: 2.6
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+
+      - name: Install Proselint
+        run: pip install --quiet --user proselint
+
+      - name: Run Proselint
+        run: find . -name '*.md' -exec proselint {} \;

.markdownlint.yml

@@ -0,0 +1,4 @@
+MD013:
+  line_length: 400
+no-inline-html:
+  allowed_elements: [a, p, img, br]

.travis.yml

@@ -185,4 +185,4 @@ For instance, using an autocomplete input is straightforward, [checkout the dedi
 API Platform is built on top of [React Admin](https://marmelab.com/react-admin/).
 You can use all the features provided by the underlying library with API Platform Admin, including support for [file upload](https://marmelab.com/react-admin/DataProviders.html#decorating-your-data-provider-example-of-file-upload), [authentication](https://marmelab.com/react-admin/Authentication.html), [authorization](https://marmelab.com/react-admin/Authorization.html) and deeper customization.
 
-To learn more about these capabilities, refer to [the React Admin documentation](https://marmelab.com/react-admin/). 
+To learn more about these capabilities, refer to [the React Admin documentation](https://marmelab.com/react-admin/).

admin/components.md

@@ -13,7 +13,6 @@ import {
   HydraAdmin,
   ResourceGuesser,
   CreateGuesser,
-  InputGuesser
 } from "@api-platform/admin";
 import { FileField, FileInput } from "react-admin";
 

admin/customizing.md

@@ -8,15 +8,21 @@ Otherwise, all you need to install API Platform Admin is a JavaScript package ma
 
 If you don't have an existing React Application, create one using [Create React App](https://create-react-app.dev/):
 
-    $ yarn create react-app my-admin
+```console
+yarn create react-app my-admin
+```
 
 Go to the directory of your project:
 
-    $ cd my-admin
+```console
+cd my-admin
+```
 
 Finally, install the `@api-platform/admin` library:
 
-    $ yarn add @api-platform/admin
+```console
+yarn add @api-platform/admin
+```
 
 ## Creating the Admin
 
@@ -59,7 +65,10 @@ nelmio_cors:
 
 Clear the cache to apply this change:
 
-    $ docker-compose exec php bin/console cache:clear --env=prod
+```console
+docker-compose exec php \
+    bin/console cache:clear --env=prod
+```
 
 Your new administration interface is ready! Type `yarn start` to try it!
 

admin/file-upload.md

@@ -6,22 +6,22 @@ API Platform Admin is a tool to automatically create a beautiful and fully featu
 for any API supporting [the Hydra Core Vocabulary](http://www.hydra-cg.com/) or other API specification formats supported by [`@api-platform/api-doc-parser`](https://github.com/api-platform/api-doc-parser) (experimental support for [OpenAPI](https://www.openapis.org/) is also available).
 
 API Platform Admin is the perfect companion of APIs created
-using [the API Platform framework](https://api-platform.com), but also supports APIs written with any other programming language or framework as long as they expose a standard Hydra API documentation. 
+using [the API Platform framework](https://api-platform.com), but also supports APIs written with any other programming language or framework as long as they expose a standard Hydra API documentation.
 
 API Platform Admin is a 100% standalone Single-Page-Application with no coupling to the server part,
 according to the API-first paradigm.
 
 API Platform Admin parses the API documentation then uses the awesome [React Admin](https://marmelab.com/react-admin/)
 library to expose a nice, responsive, management interface (Create-Retrieve-Update-Delete) for all documented resource types.
 
-You can  **customize everything** by using provided React Admin and [Material UI](https://material-ui.com/) components, or by writing your custom [React](https://reactjs.org/) components.
+You can **customize everything** by using provided React Admin and [Material UI](https://material-ui.com/) components, or by writing your custom [React](https://reactjs.org/) components.
 
 ## Features
 
 * Automatically generates an admin interface for all the resources of the API thanks to hypermedia features of Hydra
 * Generates 'list', 'create', 'show', and 'edit' screens, as well as a delete button
 * Generates suitable inputs and fields according to the API doc (e.g. number HTML input for numbers, checkbox for booleans, selectbox for relationships...)
-* Generates suitable inputs and fields according to Schema.org types if available (e.g. email field for http://schema.org/email)
+* Generates suitable inputs and fields according to Schema.org types if available (e.g. email field for `http://schema.org/email`)
 * Handles relationships
 * Supports pagination
 * Supports filters and ordering

admin/getting-started.md

@@ -0,0 +1,68 @@
+# Validation
+
+API Platform Admin manages automatically two types of validation: client-side validation and server-side (or submission) validation.
+
+## Client-side Validation
+
+If the API documentation indicates that a field is mandatory,
+API Platform Admin will automatically add a [required client-side validation](https://marmelab.com/react-admin/CreateEdit.html#per-input-validation-built-in-field-validators).
+
+For instance, with API Platform Core as backend, if you write the following:
+
+```php
+<?php
+// api/src/Entity/Book.php
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * @ApiResource
+ */
+class Book
+{
+    /**
+     * @Assert\NotBlank
+     */
+    public ?string $title = null;
+}
+```
+
+If you create a new book and touch the "Title" field without typing, you will see:
+
+![Required title field](images/required-field.png)
+
+## Server-side Validation
+
+When the form is submitted and if submission errors are received,
+API Platform Admin will automatically show the errors for the corresponding fields.
+
+To do so, it uses the [submission validation](https://marmelab.com/react-admin/CreateEdit.html#submission-validation) feature of React Admin,
+and the mapping between the response and the fields is done by the [schema analyzer](components.md#schemaanalyzer) with its method `getSubmissionErrors`.
+
+API Platform Core is supported by default, but if you use another backend, you will need to override the `getSubmissionErrors` method.
+
+For example if you have this code:
+
+```php
+<?php
+// api/src/Entity/Book.php
+
+use ApiPlatform\Core\Annotation\ApiResource;
+use Symfony\Component\Validator\Constraints as Assert;
+
+/**
+ * @ApiResource
+ */
+class Book
+{
+    /**
+     * @Assert\Isbn
+     */
+    public ?string $isbn = null;
+}
+```
+
+If you submit the form with an invalid ISBN, you will see:
+
+![Submission error field](images/submission-error-field.png)

admin/images/required-field.png

@@ -4,7 +4,7 @@ Client Generator is the fastest way to scaffold fully featured webapps and nativ
 
 ![Screencast](images/client-generator-demo.gif)
 
-*Generated React and React Native apps, updated in real time* 
+## Generated React and React Native Apps, Updated in Real Time
 
 It is able to generate apps using the following frontend stacks:
 

admin/images/submission-error-field.png

@@ -18,11 +18,11 @@ Create a [Next.js application with express server](https://github.com/zeit/next.
 
 Enable TypeScript in your next project
 
-    $ yarn add --dev typescript @types/react @types/node
+    yarn add --dev typescript @types/react @types/node
 
 Install required dependencies:
 
-    $ yarn add lodash.get lodash.has @types/lodash isomorphic-unfetch
+    yarn add lodash.get lodash.has @types/lodash isomorphic-unfetch formik
 
 ## Generating Routes
 
@@ -35,7 +35,7 @@ Install required dependencies:
 
 You can launch the server with
 
-    $ yarn dev
+    yarn dev
 
 Go to `http://localhost:3000/books/` to start using your app.
 

admin/index.md

@@ -8,13 +8,19 @@ The Nuxt.js Client Generator generates components for Server Side Rendered appli
 
 Create a [Nuxt.js application](https://nuxtjs.org/guides/get-started/installation#using-create-nuxt-app). The easiest way is to execute:  
 
-    $ npx create-nuxt-app your-app-name
-    # or
-    $ yarn create nuxt-app your-app-name
+```console
+npx create-nuxt-app your-app-name
+```
 
-It will ask you some questions you can use these answers :
+or:
 
+```console
+yarn create nuxt-app your-app-name
 ```
+
+It will ask you some questions you can use these answers :
+
+```console
 Project name: your-app-name
 Programming language: JavaScript
 Package manager: Yarn
@@ -30,8 +36,10 @@ Deployment target: Static (Static/JAMStack hosting)
 
 Install required dependencies:
 
-    $ yarn add moment lodash vue-i18n vuelidate vuex-map-fields nuxt-i18n
-    # yarn add --dev @nuxtjs/vuetify @nuxtjs/fontawesome
+```console
+yarn add moment lodash vue-i18n vuelidate vuex-map-fields nuxt-i18n
+yarn add --dev @nuxtjs/vuetify @nuxtjs/fontawesome
+```
 
 ## Updating nuxtjs config
 
@@ -48,19 +56,22 @@ Update your `nuxt.config.js` with following:
   // to avoid name conflicts in generators
   components: false,  
 ```
+
 ## Generating Routes
 
-    $ npx @api-platform/client-generator https://demo.api-platform.com . --generator nuxt
-    # Replace the URL by the entrypoint of your Hydra-enabled API
+```console
+npx @api-platform/client-generator https://demo.api-platform.com . --generator nuxt
+```
 
-> Note: Omit the resource flag to generate files for all resource types exposed by the API.
+Replace the URL by the entrypoint of your Hydra-enabled API
 
-## Updating default layout
+**Note:** Omit the resource flag to generate files for all resource types exposed by the API.
 
+## Updating default layout
 
 Update your `layouts/default.vue` with following:
 
-```javascript
+```vue
 <template>
   <v-app>
     <alert />
@@ -132,9 +143,11 @@ export default {
 
 ## Starting the Project
 
-You can launch the server with 
+You can launch the server with:
 
-    $ yarn dev
+```console
+yarn dev
+````
 
 Go to `https://localhost:3000/books/` to start using your app.