Docs review (strapi#6848)

* docs: improve getting started Signed-off-by: Jim LAURIE <j.laurie6993@gmail.com> * docs: review quickstart video and some steps Signed-off-by: Jim LAURIE <j.laurie6993@gmail.com> * docs: review concepts Signed-off-by: Jim LAURIE <j.laurie6993@gmail.com> * docs: review email - upload plugins Signed-off-by: Jim LAURIE <j.laurie6993@gmail.com> * fix: PR feedback Signed-off-by: Jim LAURIE <j.laurie6993@gmail.com> * fix: PR feedback type conflict Signed-off-by: Jim LAURIE <j.laurie6993@gmail.com> Signed-off-by: Gil Fernandes <gil.fernandes@onepointltd.com>
onepointconsulting · Aug 13, 2020 · b5a2994 · b5a2994
1 parent ce092d3
commit b5a2994
Show file tree

Hide file tree

Showing 17 changed files with 357 additions and 739 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -161,7 +161,6 @@ module.exports = {
             ['/v3.x/getting-started/contributing', 'Contributing'],
             ['/v3.x/getting-started/troubleshooting', 'Troubleshooting'],
             '/v3.x/getting-started/quick-start',
-            '/v3.x/getting-started/quick-start-tutorial',
           ],
         },
         {

diff --git a/docs/v3.x/concepts/configurations.md b/docs/v3.x/concepts/configurations.md
@@ -56,6 +56,8 @@ Instead of writing those credentials into your configuration files, you can defi
 
 **Example**
 
+**Path —** `.env`
+
 ```
 DATABASE_PASSWORD=acme
 ```
@@ -70,7 +72,7 @@ Now you can access those variables in your configuration files and application.
 
 In your configuration files you will have access to a `env` utility that allows defining defaults and casting values.
 
-`config/database.js`
+**Path —** `./config/database.js`
 
 ```js
 module.exports = ({ env }) => ({

diff --git a/docs/v3.x/concepts/controllers.md b/docs/v3.x/concepts/controllers.md
@@ -43,6 +43,8 @@ const { parseMultipartData, sanitizeEntity } = require('strapi-utils');
 - `parseMultipartData`: This function parses Strapi's formData format.
 - `sanitizeEntity`: This function removes all private fields from the model and its relations.
 
+#### Collection Type
+
 :::: tabs
 
 ::: tab find
@@ -194,7 +196,7 @@ const { sanitizeEntity } = require('strapi-utils');
 
 module.exports = {
   /**
-   * delete a record.
+   * Delete a record.
    *
    * @return {Object}
    */
@@ -212,6 +214,90 @@ module.exports = {
 
 ::::
 
+#### Single Type
+
+:::: tabs
+
+::: tab find
+
+#### `find`
+
+```js
+const { sanitizeEntity } = require('strapi-utils');
+
+module.exports = {
+  /**
+   * Retrieve the record.
+   *
+   * @return {Array}
+   */
+
+  async find(ctx) {
+    const entity = await strapi.services.restaurant.findOne();
+    return sanitizeEntity(entity, { model: strapi.models.restaurant });
+  },
+};
+```
+
+:::
+
+::: tab update
+
+#### `update`
+
+```js
+const { parseMultipartData, sanitizeEntity } = require('strapi-utils');
+
+module.exports = {
+  /**
+   * Update the record.
+   *
+   * @return {Object}
+   */
+
+  async update(ctx) {
+    let entity;
+    if (ctx.is('multipart')) {
+      const { data, files } = parseMultipartData(ctx);
+      entity = await strapi.services.restaurant.createOrUpdate(data, {
+        files,
+      });
+    } else {
+      entity = await strapi.services.restaurant.createOrUpdate(ctx.request.body);
+    }
+
+    return sanitizeEntity(entity, { model: strapi.models.restaurant });
+  },
+};
+```
+
+:::
+
+::: tab delete
+
+#### `delete`
+
+```js
+const { sanitizeEntity } = require('strapi-utils');
+
+module.exports = {
+  /**
+   * Delete the record.
+   *
+   * @return {Object}
+   */
+
+  async delete(ctx) {
+    const entity = await strapi.services.restaurant.delete();
+    return sanitizeEntity(entity, { model: strapi.models.restaurant });
+  },
+};
+```
+
+:::
+
+::::
+
 ## Custom controllers
 
 You can also create custom controllers to build your own business logic and API endpoints.

diff --git a/docs/v3.x/concepts/middlewares.md b/docs/v3.x/concepts/middlewares.md
@@ -79,6 +79,46 @@ By default this file doesn't exist, you will have to create it.
   - `{middlewareName}` (Object): Configuration of one middleware
     - `enabled` (boolean): Tells Strapi to run the middleware or not
 
+### Settings
+
+**Example**:
+
+**Path —** `./config/middleware.js`.
+
+```js
+module.exports = {
+  //...
+  settings: {
+    cors: {
+      origin: 'http://localhost',
+    },
+  },
+};
+```
+
+### Load order
+
+The middlewares are injected into the Koa stack asynchronously. Sometimes it happens that some of these middlewares need to be loaded in a specific order. To define a load order, create or edit the file `./config/middleware.js`.
+
+**Path —** `./config/middleware.js`.
+
+```js
+module.exports = {
+  load: {
+    before: ['responseTime', 'logger', 'cors', 'responses'],
+    order: [
+      "Define the middlewares' load order by putting their name in this array in the right order",
+    ],
+    after: ['parser', 'router'],
+  },
+};
+```
+
+- `load`:
+  - `before`: Array of middlewares that need to be loaded in the first place. The order of this array matters.
+  - `order`: Array of middlewares that need to be loaded in a specific order.
+  - `after`: Array of middlewares that need to be loaded at the end of the stack. The order of this array matters.
+
 ## Core middleware configurations
 
 The core of Strapi embraces a small list of middlewares for performances, security and great error handling.
@@ -139,7 +179,7 @@ The following middlewares cannot be disabled: responses, router, logger and boom
 The session doesn't work with `mongo` as a client. The package that we should use is broken for now.
 :::
 
-## Response middlewares
+### Response middlewares
 
 - [`gzip`](https://en.wikipedia.org/wiki/Gzip)
   - `enabled` (boolean): Enable or not GZIP response compression.
@@ -178,45 +218,7 @@ The session doesn't work with `mongo` as a client. The package that we should us
   - `whiteList` (array): Whitelisted IPs. Default value: `[]`.
   - `blackList` (array): Blacklisted IPs. Default value: `[]`.
 
-**Example**:
-
-**Path —** `./config/middleware.js`.
-
-```js
-module.exports = {
-  //...
-  settings: {
-    cors: {
-      origin: 'http://localhost',
-    },
-  },
-};
-```
-
-### Load order
-
-The middlewares are injected into the Koa stack asynchronously. Sometimes it happens that some of these middlewares need to be loaded in a specific order. To define a load order, create or edit the file `./config/middleware.js`.
-
-**Path —** `./config/middleware.js`.
-
-```js
-module.exports = {
-  load: {
-    before: ['responseTime', 'logger', 'cors', 'responses'],
-    order: [
-      "Define the middlewares' load order by putting their name in this array in the right order",
-    ],
-    after: ['parser', 'router'],
-  },
-};
-```
-
-- `load`:
-  - `before`: Array of middlewares that need to be loaded in the first place. The order of this array matters.
-  - `order`: Array of middlewares that need to be loaded in a specific order.
-  - `after`: Array of middlewares that need to be loaded at the end of the stack. The order of this array matters.
-
-### Examples
+## Example
 
 Create your custom middleware.
 

diff --git a/docs/v3.x/concepts/services.md b/docs/v3.x/concepts/services.md
@@ -19,6 +19,8 @@ You can read about `strapi.query` calls [here](./queries.md).
 In the following example your controller, service and model are named `restaurant`.
 :::
 
+#### Collection Type
+
 :::: tabs
 
 ::: tab find
@@ -277,6 +279,102 @@ module.exports = {
 
 ::::
 
+#### Single Type
+
+:::: tabs
+
+::: tab find
+
+#### `find`
+
+```js
+const _ = require('lodash');
+
+module.exports = {
+  /**
+   * Promise to fetch the record
+   *
+   * @return {Promise}
+   */
+  async find(populate) {
+    const results = await strapi.query('restaurant').find({ _limit: 1 }, populate);
+    return _.first(results) || null;
+  },
+};
+```
+
+- `populate` (array): you have to mention data you want populate `["author", "author.name", "comment", "comment.content"]`
+
+:::
+
+::: tab createOrUpdate
+
+#### `createOrUpdate`
+
+```js
+const _ = require('lodash');
+
+module.exports = {
+  /**
+   * Promise to add/update the record
+   *
+   * @return {Promise}
+   */
+
+  async createOrUpdate(data, { files } = {}) {
+    const results = await strapi.query('restaurant').find({ _limit: 1 });
+    const entity = _.first(results) || null;
+
+    let entry;
+    if (!entity) {
+      entry = await strapi.query('restaurant').create(data);
+    } else {
+      entry = await strapi.query('restaurant').update({ id: entity.id }, data);
+    }
+
+    if (files) {
+      // automatically uploads the files based on the entry and the model
+      await strapi.entityService.uploadFiles(entry, files, {
+        model: 'restaurant',
+        // if you are using a plugin's model you will have to add the `plugin` key (plugin: 'users-permissions')
+      });
+      return this.findOne({ id: entry.id });
+    }
+
+    return entry;
+  },
+};
+```
+
+:::
+
+::: tab delete
+
+#### `delete`
+
+```js
+module.exports = {
+  /**
+   * Promise to delete a record
+   *
+   * @return {Promise}
+   */
+
+  delete() {
+    const results = await strapi.query('restaurant').find({ _limit: 1 });
+    const entity = _.first(results) || null;
+
+    if (!entity) return;
+
+    return strapi.query('restaurant').delete({id: entity.id});
+  },
+};
+```
+
+:::
+
+::::
+
 ## Custom services
 
 You can also create custom services to build your own business logic.