Added basic Admin UI hooks docs (#2743)

keystonejs · Apr 17, 2020 · d317bea · d317bea
1 parent 88caa1c
commit d317bea
Show file tree

Hide file tree

Showing 2 changed files with 79 additions and 17 deletions.
diff --git a/packages/app-admin-ui/README.md b/packages/app-admin-ui/README.md
@@ -31,25 +31,89 @@ module.exports = {
 };
 ```
 
-### Config
-
-| Option               | Type       | Default      | Required | Description                                                                |
-| -------------------- | ---------- | ------------ | -------- | -------------------------------------------------------------------------- |
-| `adminPath`          | `String`   | `/admin`     | `false`  | The path of the Admin UI.                                                  |
-| `apiPath`            | `String`   | `/admin/api` | `false`  | The path of the API provided to the Admin UI.                              |
-| `graphiqlPath`       | `String`   | `/admin/api` | `false`  | The path of the graphiql app, an in-browser IDE for exploring GraphQL.     |
-| `authStrategy`       | `Object`   | `null`       | `false`  | See [Authentication Guides](https://keystonejs.com/guides/authentication)  |
-| `pages`              | `Array`    | `null`       | `false`  |                                                                            |
-| `enableDefaultRoute` | `Bool`     | `false`      | `false`  | If enabled, the path of the Admin UI app will be set to `/`.               |
-| `schemaName`         | `String`   | `public`     | `false`  |                                                                            |
-| `isAccessAllowed`    | `Function` | `true`       | `false`  | Controls which users have access to the Admin UI.                          |
-| `adminMeta`          | `Object`   | `{}`         | `false`  | Provides additional `adminMeta`. Useful for Hooks and other customizations |
+## Config
+
+| Option               | Type       | Default       | Required | Description                                                                |
+| -------------------- | ---------- | ------------- | -------- | -------------------------------------------------------------------------- |
+| `adminPath`          | `String`   | `/admin`      | `false`  | The path of the Admin UI.                                                  |
+| `apiPath`            | `String`   | `/admin/api`  | `false`  | The path of the API provided to the Admin UI.                              |
+| `graphiqlPath`       | `String`   | `/admin/api`  | `false`  | The path of the graphiql app, an in-browser IDE for exploring GraphQL.     |
+| `authStrategy`       | `Object`   | `null`        | `false`  | See [Authentication Guides](https://keystonejs.com/guides/authentication)  |
+| `hooks`              | `String`   | `./admin-ui/` | `false`  | Path to customization hooks. See below for more information.               |
+| `enableDefaultRoute` | `Bool`     | `false`       | `false`  | If enabled, the path of the Admin UI app will be set to `/`.               |
+| `schemaName`         | `String`   | `public`      | `false`  |                                                                            |
+| `isAccessAllowed`    | `Function` | `true`        | `false`  | Controls which users have access to the Admin UI.                          |
+| `adminMeta`          | `Object`   | `{}`          | `false`  | Provides additional `adminMeta`. Useful for Hooks and other customizations |
+
+### `hooks`
+
+Customization hooks allow you to modify various areas of the Admin UI to better suit your development needs. The `index.js` file at the given path should export a single config object containing your chosen hooks. All are optional.
+
+If omitted, Keystone will look under `./admin-ui/` for a hooks config export.
+
+#### Usage
+
+```javascript title=index.js
+new AdminUIApp({ hooks: require.resolve('./custom-hooks-path') });
+```
+
+```javascript title=/custom-hooks-path/index.js
+export default {
+  pages: () => {},
+};
+```
+
+The following hooks are available:
+
+#### `pages`
+
+Allows grouping list pages in the sidebar or defining completely new pages.
+
+This should be a function that returns an array of objects, which may contain the following properties:
+
+| Name        | Type             | Description                                                                             |
+| ----------- | ---------------- | --------------------------------------------------------------------------------------- |
+| `label`     | `String`         | The page name to display in the sidebar.                                                |
+| `path`      | `String`         | The page path.                                                                          |
+| `component` | `Function|Class` | A React component which will be used to render this page.                               |
+| `children`  | `Array`          | An array of either Keystone list keys or objects with `listKey` and `label` properties. |
+
+```javascript
+export default {
+  pages: () => [
+    // Custom pages
+    {
+      label: 'A new dashboard',
+      path: '',
+      component: Dashboard,
+    },
+    {
+      label: 'About this project',
+      path: 'about',
+      component: About,
+    },
+    // Ordering existing list pages
+    {
+      label: 'Blog',
+      children: [
+        { listKey: 'Post' },
+        { listKey: 'PostCategory', label: 'Categories' },
+        { listKey: 'Comment' },
+      ],
+    },
+    {
+      label: 'People',
+      children: ['User'],
+    },
+  ],
+};
+```
 
 ### `isAccessAllowed`
 
 This function takes the same arguments as a [shorthand imperative boolean](https://www.keystonejs.com/api/access-control#shorthand-imperative-boolean) access control. It must return either true or false.
 
-If omitted, all users _with accounts_ will be able to access the Admin UI. The example below would restrict access to users with the `isAdmin` permission.
+> **Important:** If omitted, all users _with accounts_ will be able to access the Admin UI. The example below would restrict access to users with the `isAdmin` permission.
 
 #### Usage
 

diff --git a/packages/app-static/README.md b/packages/app-static/README.md
@@ -12,9 +12,7 @@ A KeystoneJS app to serve static files such as images, CSS and JavaScript with s
 
 ## Usage
 
-`index.js`
-
-```js
+```js title=index.js
 const { Keystone } = require('@keystonejs/keystone');
 const { GraphQLApp } = require('@keystonejs/app-graphql');
 const { AdminUIApp } = require('@keystonejs/app-admin-ui');