Merge branch 'enhancement/documentation' of github.com:strapi/strapi into enhancement/documentation

docs/3.x.x/en/API.md

@@ -1,28 +0,0 @@
-# API
-
-## Introduction
-
-The API folder contains most of your backend application. Here, you have all your business logic and content types REST API.
-
-It’s in this folder that you will spend the major part of your time. Now we will see how to work with it.
-
-### Structure
-
-The API main folder contains one folder per API. One API can be a content type generated by the command line or by the content type builder plugin. You can also create your own API which contains a business logic with it’s own routes, controller actions and services.
-
-config - Config contains a `route.json` file with your API routes (see documentation routing) and json files for every custom config you want to add to your API (this configs are not by env)
-controllers - Controllers contains all your controllers' files (see controllers documentation for more informations)
-models - Models contains all your models' files (see models documentation for more informations)
-services - Services contains all your services' files (see services documentation for more informations)
-
-### References
-
-All your APIs are in the strapi global variable. You can access to an API using `strapi.api`
-
-For example if you define a `hash` function for the user API's service, you will be able to access it everywhere in your app with `strapi.api.user.services.user.hash()`
-
-configs, controllers, models and services are exposed in `strapi.api` object.
-
-### Create an API
-
-Link to https://docs.google.com/document/d/1kQKpeBUfZXap3nwPkxMMA0gAQW6VB_0qaUM30PPkGCg/edit

docs/3.x.x/en/README.md

@@ -8,58 +8,28 @@
 
 [Strapi](http://strapi.io) is an open source solution to create, deploy and manage your own API. It provides a powerful dashboard and features to make your life easier.
 
-## v3.0.0 coming soon...
+## v3@alpha.6 is available!
-We've been working on a major update for Strapi during the past months, rewriting the core framework and the dashboard. Some parts of this work have been merged into our master branch. Currently, this is not stable and ready.
+We've been working on a major update for Strapi during the past months, rewriting the core framework and the dashboard.
 
-**Please DON'T use the `master` branch in production. To run and start your current project, we strongly recommend to use the v1.6.3.**
+This documentation is only related to Strapi v3@alpha.6 ([v1 documentation is still available](http://strapi.io/documentation/1.x.x)).
 
-For more informations on the upcoming version, please take a look to our [ROADMAP](ROADMAP.md).
+**[Migration guide](migration/migration-guide.md)**<br />
+Migrate from v1 to v3@aplha.6.
 
-Also, we need your opinion about the next features you would like. Please answer our [latest survey about Strapi v3](http://bit.ly/2v7MAdn).
+**[Get Started](getting-started/installation.md)**<br />
+Learn how to install Strapi and start developing your API.
 
-![Content Manager Plugin - Screenshot](http://blog.strapi.io/content/images/2017/07/preview-readme-9.png)
+**[Concepts](concepts/concepts.md)**<br />
+Get to know more about Strapi and how it works.
 
-## Why Strapi ? (other version)
+**[Guides](configurations/configurations.md)**<br />
+Get familiar with Strapi. Discover concrete examples on how to develop the features you need.
 
-> At [Strapi](http://strapi.io), we believe that we can change the status quo of web development. Our products are simple to use, user-friendly and production-ready.
+**[Command Line Interface](cli/CLI.md)**<br />
+Get to know our CLI to make features the hacker way!
 
+**[Developing a plugin](plugins/development.md)**<br />
+Understand how to develop your own plugin.
 
-Web and mobile applications need a powerful, user-friendly and production-ready API-driven solution. That's why we created Strapi, an open-source Content Management Framework (CMF) to expose your content (data, media) across multi-devices.
+**[API Reference](api-reference/reference.md)**<br />
-
+Learn about Strapi's API, the `strapi` object that is available in your backend.
-Halfway between a CMS and a framework, Strapi takes advantage of both worlds. A powerful dashboard to easily manage your content with a flexible framework layer to develop and integrate specific features.
-
-## Features
-
-- **Dashboard**, is a complete UI to manage your app. If you try it, you'll like it!
-- **100% JavaScript**, the language you are probably already using for the front-end.
-- **Useful CLI** that lets you scaffold projects and APIs on the fly.
-- **Front-end agnostic** that can be used with React, Vue, Angular, Backbone, Ember, iOS, Android, etc.
-- **Security layers** that just work and ship reusable security policies.
-- **WebSockets** to handle realtime connections and events.
-- **Mongo** as a main database to store your data with efficiency.
-
-## Plugins
-
-> Only what you need. No more. No less.
-
-Thanks to the plugins, you will be able to create the perfect app without useless features. Strapi's ecosystem has been thought to be the most granular as possible. Please [read our blog](http://blog.strapi.io/everything-you-need-to-know-about-strapi-v3/) to get more details about them.
-
-## Support
-
-### Community support
-
-For general help using Strapi, please refer to [the official Strapi documentation](http://strapi.io). For additional help, you can use one of these channels to ask questions:
-
-- [StackOverflow](http://stackoverflow.com/questions/tagged/strapi)
-- [Slack](http://slack.strapi.io) (highly recommended for realtime support)
-- [GitHub](https://github.com/strapi/strapi)
-- [Twitter](https://twitter.com/strapijs)
-- [Facebook](https://www.facebook.com/Strapi-616063331867161)
-
-### Professional support
-
-[Strapi Solutions](http://strapi.io), the company behind Strapi, provides a full range of solutions to get better and faster results. We're always looking for the next challenges: coaching, consulting, training, customization, etc. [Drop us an email](mailto:support@strapi.io) to see how we can help you.
-
-## License
-
-[MIT License](LICENSE.md) Copyright (c) 2015-2017 [Strapi Solutions](http://strapi.io/).

docs/3.x.x/en/SUMMARY.md

@@ -18,6 +18,7 @@
 ### Guides
 * [Configurations](configurations/configurations.md)
 * [Controllers](guides/controllers.md)
+* [Internationalization](guides/i18n.md)
 * [Models](guides/models.md)
 * [Policies](guides/policies.md)
 * [Public Assets](guides/public-assets.md)

docs/3.x.x/en/configurations/configurations.md

@@ -152,6 +152,67 @@ Most of the application's configurations are defined by environment. It means th
        - `password` (string): Password used to establish the connection.
        - `options` (object): List of additional options used by the connector.
 
+#### Example
+
+**Path —** `./config/environments/**/database.json`.
+```json
+{
+  "defaultConnection": "default",
+  "connections": {
+    "default": {
+      "connector": "strapi-mongoose",
+      "settings": {
+        "client": "mongo",
+        "host": "localhost",
+        "port": 27017,
+        "database": "development",
+        "username": "fooUsername",
+        "password": "fooPwd"
+      },
+      "options": {}
+    },
+    "postgres": {
+      "connector": "strapi-bookshelf",
+      "settings": {
+        "client": "postgres",
+        "host": "localhost",
+        "port": 5432,
+        "username": "aureliengeorget",
+        "password": "${process.env.USERNAME}",
+        "database": "${process.env.PWD}",
+        "schema": "public"
+      },
+      "options": {}
+    },
+    "mysql": {
+      "connector": "strapi-bookshelf",
+      "settings": {
+        "client": "mysql",
+        "host": "localhost",
+        "port": 5432,
+        "username": "aureliengeorget",
+        "password": "root",
+        "database": ""
+      },
+      "options": {}
+    },
+    "redis": {
+      "connector": "strapi-redis",
+      "settings": {
+        "port": 6379,
+        "host": "localhost",
+        "password": ""
+      },
+      "options": {
+        "debug": false
+      }
+    }
+  }
+}
+```
+
+> Please refer to the [dynamic configurations section](#dynamic-configurations) to use global environment variable to configure the databases.
+
 ### Request
 
 **Path —** `./config/environments/**/request.json`.
@@ -174,6 +235,8 @@ Most of the application's configurations are defined by environment. It means th
  - `router`
   - `prefix` (string): API url prefix (eg. `/v1`).
 
+> Note: The session doesn't work with `mongo` as a client. The package that we should use is broken for now.
+
 ### Response
 
 **Path —** `./config/environments/**/response.json`.
@@ -226,3 +289,33 @@ Most of the application's configurations are defined by environment. It means th
  - `autoReload` (boolean): Enable or disabled server reload on files update. Default value: depends on the environment.
  - [`cron`](https://en.wikipedia.org/wiki/Cron)
   - `enabled` (boolean): Enable or disable CRON tasks to schedule jobs at specific dates. Default value: `false`.
+
+## Dynamic configurations
+
+For security reasons, sometimes it's better to set variables through the server environment. It's also useful to push dynamics values into configurations files. To enable this feature into JSON files, Strapi embraces a JSON-file interpreter into his core to allow dynamic value in the JSON configurations files.
+
+### Syntax
+
+The syntax is inspired by the [ES6 template literals ES2015 specifications](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals). These dynamic values are indicated by the Dollar sign and curly braces (`${expression}`).
+
+### Usage
+
+In any JSON configurations files in your project, you can inject dynamic values like this:
+
+**Path —** `./config/application.json`.
+```json
+{
+  "name": "${process.env.APP_NAME}",
+  "description": "${process.env.APP_DESCRIPTION}",
+  "favicon": {
+    "path": "favicon.ico",
+    "maxAge": 86400000
+  },
+  "public": {
+    "path": "./public",
+    "maxAge": 60000
+  }
+}
+```
+
+> Note: You can't execute functions inside the curly braces. Only strings are allowed.

docs/3.x.x/en/guides/i18n.md

@@ -0,0 +1,62 @@
+# Internationalization
+
+See the [internationalization' concepts](../concepts/concepts.md#internationalization) for details.
+
+Because an API may need to send different data based on the language of the user, Strapi provides a built-in strategy to handle the internationalization (i18n).
+
+## Usage
+
+The `i18n` method that will allow you to retrieve the right string based on the language is accessible through the request `context`.
+
+There are many strategies to define the language that the server should use to return the correct translation. It can be based on the `locale` query parameter, the `cookie` or the `Accept-Language` header.
+
+- Query: Add the `locale` parameter in the URL `GET /hello/John?locale=en_US`.
+- Cookie: Set the `locale` field in the cookie `locale=en\-US;`.
+- Header: Set the `Accept-Language` header with the value `en_US`.
+
+> Please refer to the [language configuration](../configurations/configurations.md#language)
+
+#### Example
+
+Let's say we want to say `Hello John` in french and `Bonjour Tom` in french. We need to use the built-in `i18n` and replace the string based on the received name.
+
+**Path —** `./api/hello/config/routes.json`.
+```json
+{
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/hello/:name",
+      "handler": "Hello.sayHello"
+    }
+  ]
+}
+```
+
+**Path —** `./api/hello/controllers/Hello.js`.
+```js
+module.exports = {
+  // GET /hello
+  sayHello: async (ctx) => {
+    ctx.send(ctx.i18n.__('Hello %s', ctx.params.name));
+  }
+};
+```
+
+You need to define the english and french translation for this key.
+
+**Path —** `./config/locales/en_US.json`.
+```json
+{
+	"Hello %s": "Hello %s"
+}
+```
+
+**Path —** `./config/locales/fr_FR.json`.
+```json
+{
+	"Hello %s": "Bonjour %s"
+}
+```
+
+That's all! `GET /hello/John?locale=en_US` will return `Hello John` and `GET /hello/Tom?locale=fr_FR` will return `Bonjour Tom`.

docs/3.x.x/en/plugins/advanced.md

@@ -191,6 +191,39 @@ export default compose(
 
 ***
 
+## Execute a logic before mounting
+
+You can execute a business logic before your plugin is being mounted.
+
+### Usage
+
+To do this, you need to create `bootstrap.js` file at the root of your `src` plugin's folder.
+This file must contains a default functions that returns a `Promise`.
+
+#### Example
+
+In this example, we want to populate the left menu with links that will refer to our Content Types.
+
+**Path —** `./app/plugins/content-manager/admin/src/bootstrap.js`.
+```js
+import { generateMenu } from 'containers/App/sagas';
+
+// This method is executed before the load of the plugin
+const bootstrap = (plugin) => new Promise((resolve, reject) => {
+  generateMenu()
+    .then(menu => {
+      plugin.leftMenuSections = menu;
+
+      resolve(plugin);
+    })
+    .catch(e => reject(e));
+});
+
+export default bootstrap;
+```
+
+***
+
 ## Prevent rendering
 
 You can prevent your plugin from being rendered if some conditions aren't met.
@@ -198,9 +231,9 @@ You can prevent your plugin from being rendered if some conditions aren't met.
 ### Usage
 
 To disable your plugin's rendering, you can simply create `requirements.js` file at the root of your `src` plugin's folder.
-This file must contain a default function that returns a `Promise`;
+This file must contain a default function that returns a `Promise`.
 
-Example:
+#### Example
 
 Let's say that you want to disable your plugin if the server autoReload config is disabled in development mode.