mirror/vue-cli
1
0
Fork 0
mirror of https://github.com/vuejs/vue-cli.git synced 2026-04-28 15:59:34 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs(ui): refactor (#1535)

Browse Source 
* docs(ui): refactor

* docs(ui): polish

* docs(ui): remove empty localization section
This commit is contained in:
Guillaume Chau
2018-06-10 15:46:49 +02:00
committed by GitHub
parent 919bcbb2ce
commit 54ad175e08
4 changed files with 223 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/dev-guide/ui-plugin-dev.md → docs/dev-guide/ui-api.md
+140 -121
View File
@@ -1,58 +1,12 @@
# UI Plugin Development Guide
This guide will walk you through the development of cli-ui specific features for your vue-cli plugins.
## Plugin Info
When used in the UI, your plugin can show additional information to make it more discoverable and recognizable.
### Logo
You can put a `logo.png` file in the root directory of the folder that will be published on npm. It will be displayed in several places:
- When searching for a plugin to install
- In the installed plugin list
![Plugins](/plugins.png)
The logo should be a square non-transparent image (ideally 84x84).
### Discoverability
For better discoverability when a user searches for your plugin, put keywords describing your plugin in the `description` field of the plugin `package.json` file.
Example:
```json
{
"name": "vue-cli-plugin-apollo",
"version": "0.7.7",
"description": "vue-cli 3 plugin to add Apollo and GraphQL"
}
```
You should add the url to the plugin website or repository in the `homepage` or `repository` field so that a 'More info' button will be displayed in your plugin description:
```json
{
"repository": {
"type": "git",
"url": "git+https://github.com/Akryum/vue-cli-plugin-apollo.git"
},
"homepage": "https://github.com/Akryum/vue-cli-plugin-apollo#readme"
}
```
![Plugin search item](/plugin-search-item.png)
## UI API
# UI API
The cli-ui exposes an API that allows augmenting the project configurations and tasks, as well as sharing data and communicating with other processes.
![UI Plugin architecture](/vue-cli-ui-schema.png)
### UI files
## UI files
Inside each installed vue-cli plugins, the cli-ui will try to load an optional `ui.js` file in the root folder of the plugin. It will also try to load a `vue-cli-ui.js` file in the user project root so the UI can be manually extended on a per-project basis (also useful to quickly prototype a plugin).
Inside each installed vue-cli plugins, the cli-ui will try to load an optional `ui.js` file in the root folder of the plugin. It will also try to load a `vue-cli-ui.js` file in the user project root so the UI can be manually extended on a per-project basis (also useful to quickly prototype a plugin). Note that you can also use folders (for example `ui/index.js`).
The file should export a function which gets the api object as argument:
@@ -62,9 +16,21 @@ module.exports = api => {
}
```
**⚠️ The files will be reloaded when feetching the plugin list in the 'Project plugins' view. To apply changes, click on the 'Project plugins' button in the navigation sidebar on the left.**
**⚠️ The files will be reloaded when feetching the plugin list in the 'Project plugins' view. To apply changes, click on the 'Project plugins' button in the navigation sidebar on the left in the UI.**
### Dev mode
Here is an example folder structure for a vue-cli plugin using the UI API:
```
- vue-cli-plugin-test
- package.json
- index.js
- generator.js
- prompts.js
- ui.js
- logo.png
```
## Dev mode
While building your plugin, you may want to run the cli-ui in Dev mode, so it will output useful logs to you:
@@ -72,7 +38,13 @@ While building your plugin, you may want to run the cli-ui in Dev mode, so it wi
vue ui --dev
```
### Project configurations
Or:
```
vue ui -D
```
## Project configurations
![Configuration ui](/config-ui.png)
@@ -93,7 +65,7 @@ api.describeConfig({
})
```
#### Config icon
### Config icon
It can be either a [Material icon](https://material.io/tools/icons) code or a custom image (see [Public static files](#public-static-files)):
@@ -107,7 +79,7 @@ api.describeConfig({
If you don't specify an icon, the plugin logo will be displayed if any (see [Logo](#logo)).
#### Config files
### Config files
By default, a configuration UI might read and write to one or more configuration files, for example both `.eslintrc.js` and `vue.config.js`.
@@ -135,7 +107,7 @@ api.describeConfig({
Supported types: `json`, `yaml`, `js`, `package`. The order is important: the first filename in the list will be used to create the config file if it doesn't exist.
#### Display config prompts
### Display config prompts
Use the `onRead` hook to return a list of prompts to be displayed for the configuration:
@@ -242,7 +214,7 @@ Then the `data` object will be:
}
```
#### Configuration tabs
### Configuration tabs
You can organize the prompts into several tabs:
@@ -272,7 +244,7 @@ api.describeConfig({
})
```
#### Save config changes
### Save config changes
Use the `onWrite` hook to write the data to the configuration file (or execute any nodejs code):
@@ -342,7 +314,7 @@ api.describeConfig({
})
```
### Project tasks
## Project tasks
![Tasks ui](/tasks-ui.png)
@@ -360,7 +332,7 @@ api.describeTask({
})
```
#### Task icon
### Task icon
It can be either a [Material icon](https://material.io/tools/icons) code or a custom image (see [Public static files](#public-static-files)):
@@ -374,7 +346,7 @@ api.describeTask({
If you don't specify an icon, the plugin logo will be displayed if any (see [Logo](#logo)).
#### Tasks parameters
### Tasks parameters
You can add prompts to modify the command arguments. They will be displayed in a 'Parameters' modal.
@@ -418,7 +390,7 @@ api.describeTask({
See [Prompts](#prompts) for more info.
#### Task hooks
### Task hooks
Several hooks are available:
@@ -452,7 +424,7 @@ api.describeTask({
})
```
#### Task views
### Task views
You can display custom views in the task details pane using the `ClientAddon` API:
@@ -482,7 +454,7 @@ api.describeTask({
See [Client addon](#client-addon) for more info.
#### Add new tasks
### Add new tasks
You can also add entirely new tasks which aren't in the `package.json` scripts with `api.addTask` instead of `api.describeTask`. Those tasks will only appear in the cli UI.
@@ -510,7 +482,7 @@ api.addTask({
**⚠️ The `command` will run a node context. This means you can call node bin commands like you would normally do in the `package.json` scripts.**
### Prompts
## Prompts
The prompt objects must be valid [inquirer](https://github.com/SBoudrias/Inquirer.js) objects.
@@ -534,17 +506,101 @@ In addition to those, the UI supports special types that only works with it:
- `color`: displays a color picker.
#### Prompts for invocation
### Switch example
```js
{
name: 'open',
type: 'confirm',
default: false,
description: 'Open the app in the browser'
}
```
### Select example
```js
{
name: 'mode',
type: 'list',
default: 'development',
choices: [
{
name: 'Development mode',
value: 'development'
},
{
name: 'Production mode',
value: 'production'
},
{
name: 'Test mode',
value: 'test'
}
],
description: 'Build mode',
link: 'https://link-to-docs'
}
```
### Input example
```js
{
name: 'host',
type: 'input',
default: '0.0.0.0',
description: 'Host for the development server'
}
```
### Checkbox example
Displays multiple switches.
```js
{
name: 'lintOn',
message: 'Pick additional lint features:',
when: answers => answers.features.includes('linter'),
type: 'checkbox',
choices: [
{
name: 'Lint on save',
value: 'save',
checked: true
},
{
name: 'Lint and fix on commit' + (hasGit() ? '' : chalk.red(' (requires Git)')),
value: 'commit'
}
]
}
```
### Color picker example
```js
{
name: 'themeColor',
type: 'color',
message: 'Theme color',
description: 'This is used to change the system UI color around the app',
default: '#4DBA87'
}
```
### Prompts for invocation
In your vue-cli plugin, you may already have a `prompts.js` file which asks the user a few questions when installing the plugin (with the CLI or the UI). You can add the additional UI-only fields (see above) to those prompt objects as well so they will provide more information if the user is using the UI.
**⚠️ Currently, the inquirer types which aren't supported (see above) whill not work properly in the UI.**
### Client addon
## Client addon
A Client addon is a JS bundle which is dynamically loaded into the cli-ui. It is useful to load custom components and routes.
#### Create a client addon
### Create a client addon
The recommended way to create a Client addon is by creating a new project using vue-cli 3. You can either do this in a subfolder of your plugin or in a different npm package.
@@ -583,7 +639,7 @@ Then modify the `.eslintrc.json` file to add some allowed global objects:
You can now run the `serve` script in development and the `build` one when you are ready to publish your plugin.
#### ClientAddonApi
### ClientAddonApi
Open the `main.js` file in the client addon sources and remove all the code.
@@ -626,7 +682,7 @@ locales.keys().forEach(key => {
The cli-ui registers `Vue` and `ClientAddonApi` as global variables in the `window` scope.
In your components, you can use all the components and the CSS classes of [@vue/ui](https://github.com/vuejs/ui) and [@vue/cli-ui](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-ui/src/components) in order to keep the look and feel consistent. You can also translate the strings with [vue-i18n](https://github.com/kazupon/vue-i18n) which is included.
#### Register the client addon
### Register the client addon
Back to the `ui.js` file, use the `api.addClientAddon` method with a require query to the built folder:
@@ -652,7 +708,7 @@ api.addClientAddon({
})
```
#### Use the client addon
### Use the client addon
You can now use the client addon in the views. For example, you can specify a view in a described task:
@@ -691,7 +747,7 @@ ClientAddonApi.component('vue-webpack-dashboard', WebpackDashboard)
![Task view example](/task-view.png)
### Custom views
## Custom views
You can add a new view below the standard 'Project plugins', 'Project configuration' and 'Project tasks' ones using the `api.addView` method:
@@ -731,7 +787,7 @@ ClientAddonApi.addRoutes('vue-webpack', [
![Custom view example](/custom-view.png)
### Shared data
## Shared data
Use Shared data to communicate info with custom components in an easy way.
@@ -821,7 +877,7 @@ export default {
This is very usefull if you create a settings component for example.
### Plugin actions
## Plugin actions
Plugin actions are calls sent between the cli-ui (browser) and plugins (nodejs).
@@ -879,7 +935,7 @@ export default {
}
```
### Inter-process communication (IPC)
## Inter-process communication (IPC)
IPC stands for Inter-Process Communication. This system allows you to easily send messages from child processes (for example, tasks!). And it's pretty fast and lightweight.
@@ -945,7 +1001,7 @@ api.ipcSend({
})
```
### Local storage
## Local storage
A plugin can save and load data from the local [lowdb](https://github.com/typicode/lowdb) database used by the ui server.
@@ -966,7 +1022,7 @@ api.db.get('posts')
const { storageGet, storageSet } = api.namespace('my-plugin.')
```
### Notification
## Notification
You can display notifications using the user OS notification system:
@@ -983,52 +1039,13 @@ There are some builtin icons:
- `'done'`
- `'error'`
### Localization
You can put locale files compatible with [vue-i18n](https://github.com/kazupon/vue-i18n) in a `locales` folder at the root of your plugin. They will be automatically loaded into the client when the project is opened. You can then use `$t` to translate strings in your components and other vue-i18n helpers. Also, the strings used in the UI API (like `describeTask`) will go through vue-i18n as well to you can localize them.
Example `locales` folder:
```
vue-cli-plugin/locales/en.json
vue-cli-plugin/locales/fr.json
```
Example usage in API:
```js
api.describeConfig({
// vue-i18n path
description: 'my-plugin.config.foo'
})
```
Example usage in components:
```html
<VueButton>{{ $t('my-plugin.actions.bar') }}</VueButton>
```
You can also load the locale files in a client addon if you prefer, using the `ClientAddonApi`:
```js
// Load the locale files (uses vue-i18n)
const locales = require.context('./locales', true, /[a-z0-9]+\.json$/i)
locales.keys().forEach(key => {
const locale = key.match(/([a-z0-9]+)\./i)[1]
ClientAddonApi.addLocalization(locale, locales(key))
})
```
#### Help translate the main UI!
See [how to help translating the main UI](./ui-localization.md).
### Hooks
## Hooks
Hooks allows to react to certain cli-ui events.
`onProjectOpen`: Called when the plugin is loaded for the first time for the current project.
### onProjectOpen
Called when the plugin is loaded for the first time for the current project.
```js
api.onProjectOpen((project, previousProject) => {
@@ -1036,7 +1053,9 @@ api.onProjectOpen((project, previousProject) => {
})
```
`onPluginReload`: Called when the plugin is reloaded.
### onPluginReload
Called when the plugin is reloaded.
```js
api.onPluginReload((project) => {
@@ -1044,7 +1063,7 @@ api.onPluginReload((project) => {
})
```
### Public static files
## Public static files
You may need to expose some static files over the cli-ui builtin HTTP server (typically if you want to specify an icon to a custom view).
docs/dev-guide/ui-info.md
+41
View File
@@ -0,0 +1,41 @@
# UI Plugin Info
When used in the UI, your plugin can show additional information to make it more discoverable and recognizable.
## Logo
You can put a `logo.png` file in the root directory of the folder that will be published on npm. It will be displayed in several places:
- When searching for a plugin to install
- In the installed plugin list
![Plugins](/plugins.png)
The logo should be a square non-transparent image (ideally 84x84).
## Discoverability
For better discoverability when a user searches for your plugin, put keywords describing your plugin in the `description` field of the plugin `package.json` file.
Example:
```json
{
"name": "vue-cli-plugin-apollo",
"version": "0.7.7",
"description": "vue-cli 3 plugin to add Apollo and GraphQL"
}
```
You should add the url to the plugin website or repository in the `homepage` or `repository` field so that a 'More info' button will be displayed in your plugin description:
```json
{
"repository": {
"type": "git",
"url": "git+https://github.com/Akryum/vue-cli-plugin-apollo.git"
},
"homepage": "https://github.com/Akryum/vue-cli-plugin-apollo#readme"
}
```
![Plugin search item](/plugin-search-item.png)
docs/dev-guide/ui-localization.md
+38 -1
View File
@@ -1,6 +1,6 @@
# UI Localization
## Translate the UI
## Translate the standard UI
Follow those simple steps to propose a new language for the CLI UI!
@@ -17,3 +17,40 @@ Follow those simple steps to propose a new language for the CLI UI!
The English reference locale is [here](https://github.com/vuejs/vue-cli/blob/dev/packages/%40vue/cli-ui/locales/en.json).
Take a look at [the french localization package](https://github.com/Akryum/vue-cli-locale-fr) as an example.
## Translate your plugin
You can put locale files compatible with [vue-i18n](https://github.com/kazupon/vue-i18n) in a `locales` folder at the root of your plugin. They will be automatically loaded into the client when the project is opened. You can then use `$t` to translate strings in your components and other vue-i18n helpers. Also, the strings used in the UI API (like `describeTask`) will go through vue-i18n as well to you can localize them.
Example `locales` folder:
```
vue-cli-plugin/locales/en.json
vue-cli-plugin/locales/fr.json
```
Example usage in API:
```js
api.describeConfig({
// vue-i18n path
description: 'my-plugin.config.foo'
})
```
Example usage in components:
```html
<VueButton>{{ $t('my-plugin.actions.bar') }}</VueButton>
```
You can also load the locale files in a client addon if you prefer, using the `ClientAddonApi`:
```js
// Load the locale files (uses vue-i18n)
const locales = require.context('./locales', true, /[a-z0-9]+\.json$/i)
locales.keys().forEach(key => {
const locale = key.match(/([a-z0-9]+)\./i)[1]
ClientAddonApi.addLocalization(locale, locales(key))
})
```