From 27aaee4a90033dc02cc84e32b12c0d85fdd35170 Mon Sep 17 00:00:00 2001 From: Aurelsicoko Date: Wed, 11 Oct 2017 15:37:14 +0200 Subject: [PATCH 1/5] Add usage using bootstrap --- .../3.x.x/en/configurations/configurations.md | 2 + docs/3.x.x/en/plugins/advanced.md | 37 ++++++++++++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/3.x.x/en/configurations/configurations.md b/docs/3.x.x/en/configurations/configurations.md index 3a0e9b008f..ab7cb96037 100644 --- a/docs/3.x.x/en/configurations/configurations.md +++ b/docs/3.x.x/en/configurations/configurations.md @@ -174,6 +174,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`. diff --git a/docs/3.x.x/en/plugins/advanced.md b/docs/3.x.x/en/plugins/advanced.md index bd72c85ccc..ce0a589b8f 100644 --- a/docs/3.x.x/en/plugins/advanced.md +++ b/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. From c946434704b785b81e961fdfcf1cba574da8aa69 Mon Sep 17 00:00:00 2001 From: Aurelsicoko Date: Wed, 11 Oct 2017 16:05:19 +0200 Subject: [PATCH 2/5] Add complete databases example and add dynamic configurations section --- .../3.x.x/en/configurations/configurations.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/docs/3.x.x/en/configurations/configurations.md b/docs/3.x.x/en/configurations/configurations.md index ab7cb96037..d4d766c170 100644 --- a/docs/3.x.x/en/configurations/configurations.md +++ b/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`. @@ -228,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. From e03ec451bf693d6f843cf02ceed382c8a5a56bca Mon Sep 17 00:00:00 2001 From: Aurelsicoko Date: Wed, 11 Oct 2017 17:06:45 +0200 Subject: [PATCH 3/5] Add i18n guides --- docs/3.x.x/en/API.md | 28 ---------------- docs/3.x.x/en/SUMMARY.md | 1 + docs/3.x.x/en/guides/i18n.md | 62 ++++++++++++++++++++++++++++++++++++ 3 files changed, 63 insertions(+), 28 deletions(-) delete mode 100644 docs/3.x.x/en/API.md create mode 100644 docs/3.x.x/en/guides/i18n.md diff --git a/docs/3.x.x/en/API.md b/docs/3.x.x/en/API.md deleted file mode 100644 index 7f7a89ca35..0000000000 --- a/docs/3.x.x/en/API.md +++ /dev/null @@ -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 diff --git a/docs/3.x.x/en/SUMMARY.md b/docs/3.x.x/en/SUMMARY.md index e35b2e817e..9fafcc2ab4 100644 --- a/docs/3.x.x/en/SUMMARY.md +++ b/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) diff --git a/docs/3.x.x/en/guides/i18n.md b/docs/3.x.x/en/guides/i18n.md new file mode 100644 index 0000000000..ecdea6ac60 --- /dev/null +++ b/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`. From a116c6fff83318b9191cc808c2d82f0240f41a0f Mon Sep 17 00:00:00 2001 From: cyril lopez Date: Wed, 11 Oct 2017 18:07:57 +0200 Subject: [PATCH 4/5] Update 3.X.X readme --- docs/3.x.x/en/README.md | 64 +++++++++++------------------------------ 1 file changed, 17 insertions(+), 47 deletions(-) diff --git a/docs/3.x.x/en/README.md b/docs/3.x.x/en/README.md index 42316621c1..ccae149c16 100644 --- a/docs/3.x.x/en/README.md +++ b/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... -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. +## 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. -**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)**
+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/quick-start.md)**
+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)**
+Get to know more about Strapi and how it works. -## Why Strapi ? (other version) +**[Guides](configurations/configurations.md)**
+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)**
+Get to know our CLI to make features the hacker way! +**[Developing a plugin](plugins/development.md)**
+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. - -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/). +**[API Reference](api-reference/reference.md)**
+Learn about Strapi's API, the `strapi` object that is available in your backend. From 958fb6bfd587cb5577c8e458a565996ed8dc422d Mon Sep 17 00:00:00 2001 From: cyril lopez Date: Wed, 11 Oct 2017 18:11:46 +0200 Subject: [PATCH 5/5] Change get starting link in 3.x.x doc --- docs/3.x.x/en/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/3.x.x/en/README.md b/docs/3.x.x/en/README.md index ccae149c16..3d163e30d0 100644 --- a/docs/3.x.x/en/README.md +++ b/docs/3.x.x/en/README.md @@ -16,7 +16,7 @@ This documentation is only related to Strapi v3@alpha.6 ([v1 documentation is st **[Migration guide](migration/migration-guide.md)**
Migrate from v1 to v3@aplha.6. -**[Get Started](getting-started/quick-start.md)**
+**[Get Started](getting-started/installation.md)**
Learn how to install Strapi and start developing your API. **[Concepts](concepts/concepts.md)**