Commit 4561ce85 authored by Tim Zallmann's avatar Tim Zallmann

Merge branch 'docs-vue-guide-update' into 'master'

Update Frontend documentation regarding Vue and Icons/Illustrations

See merge request gitlab-org/gitlab-ce!18995
parents cb868f41 8f57de81
# Icons # Icons and SVG Illustrations
We are using SVG Icons in GitLab with a SVG Sprite, due to this the icons are only loaded once and then referenced through an ID. The sprite SVG is located under `/assets/icons.svg`. Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome usages. We manage our own Icon and Illustration library in the [gitlab-svgs][gitlab-svgs] repository.
This repository is published on [npm][npm] and managed as a dependency via yarn.
You can browse all available Icons and Illustrations [here][svg-preview].
To upgrade to a new version run `yarn upgrade @gitlab-org/gitlab-svgs`.
### Usage in HAML/Rails ## Icons
To use a sprite Icon in HAML or Rails we use a specific helper function : We are using SVG Icons in GitLab with a SVG Sprite.
This means the icons are only loaded once, and are referenced through an ID.
The sprite SVG is located under `/assets/icons.svg`.
Our goal is to replace one by one all inline SVG Icons (as those currently bloat the HTML) and also all Font Awesome icons.
`sprite_icon(icon_name, size: nil, css_class: '')` ### Usage in HAML/Rails
**icon_name** Use the icon_name that you can find in the SVG Sprite ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`). To use a sprite Icon in HAML or Rails we use a specific helper function :
**size (optional)** Use one of the following sizes : 16,24,32,48,72 (this will be translated into a `s16` class) ```ruby
sprite_icon(icon_name, size: nil, css_class: '')
```
**css_class (optional)** If you want to add additional css classes - **icon_name** Use the icon_name that you can find in the SVG Sprite
([Overview is available here][svg-preview]).
- **size (optional)** Use one of the following sizes : 16, 24, 32, 48, 72 (this will be translated into a `s16` class)
- **css_class (optional)** If you want to add additional css classes
**Example** **Example**
`= sprite_icon('issues', size: 72, css_class: 'icon-danger')` ```haml
= sprite_icon('issues', size: 72, css_class: 'icon-danger')
```
**Output from example above** **Output from example above**
`<svg class="s72 icon-danger"><use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use></svg>` ```html
<svg class="s72 icon-danger">
<use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons.svg#issues"></use>
</svg>
```
### Usage in Vue ### Usage in Vue
...@@ -28,33 +46,71 @@ We have a special Vue component for our sprite icons in `\vue_shared\components\ ...@@ -28,33 +46,71 @@ We have a special Vue component for our sprite icons in `\vue_shared\components\
Sample usage : Sample usage :
`<icon ```javascript
name="retry" <script>
:size="32" import Icon from "~/vue_shared/components/icon.vue"
css-classes="top"
/>` export default {
components: {
**name** Name of the Icon in the SVG Sprite ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`). Icon,
},
**size (optional)** Number value for the size which is then mapped to a specific CSS class (Available Sizes: 8,12,16,18,24,32,48,72 are mapped to `sXX` css classes) };
<script>
**css-classes (optional)** Additional CSS Classes to add to the svg tag. <template>
<icon
name="issues"
:size="72"
css-classes="icon-danger"
/>
</template>
```
- **name** Name of the Icon in the SVG Sprite ([Overview is available here][svg-preview]).
- **size (optional)** Number value for the size which is then mapped to a specific CSS class
(Available Sizes: 8, 12, 16, 18, 24, 32, 48, 72 are mapped to `sXX` css classes)
- **css-classes (optional)** Additional CSS Classes to add to the svg tag.
### Usage in HTML/JS ### Usage in HTML/JS
Please use the following function inside JS to render an icon : Please use the following function inside JS to render an icon:
`gl.utils.spriteIcon(iconName)` `gl.utils.spriteIcon(iconName)`
## Adding a new icon to the sprite ## SVG Illustrations
All Icons and Illustrations are managed in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository which is added as a dev-dependency. Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers.
Please use the class `svg-content` around it to ensure nice rendering.
To upgrade to a new SVG Sprite version run `yarn upgrade @gitlab-org/gitlab-svgs`. ### Usage in HAML/Rails
# SVG Illustrations **Example**
Please use from now on for any SVG based illustrations simple `img` tags to show an illustration by simply using either `image_tag` or `image_path` helpers. Please use the class `svg-content` around it to ensure nice rendering. The illustrations are also organised in the [gitlab-svgs](https://gitlab.com/gitlab-org/gitlab-svgs) repository (as they are then automatically optimised). ```haml
.svg-content
= image_tag 'illustrations/merge_requests.svg'
```
**Example** ### Usage in Vue
`= image_tag 'illustrations/merge_requests.svg'` To use an SVG illustrations in a template provide the path as a property and display it through a standard img tag.
Component:
```js
<script>
export default {
props: {
svgIllustrationPath: {
type: String,
required: true,
},
},
};
<script>
<template>
<img :src="svgIllustrationPath" />
</template>
```
[npm]: https://www.npmjs.com/package/@gitlab-org/gitlab-svgs
[gitlab-svgs]: https://gitlab.com/gitlab-org/gitlab-svgs
[svg-preview]: https://gitlab-org.gitlab.io/gitlab-svgs
...@@ -54,8 +54,8 @@ Vuex specific design patterns and practices. ...@@ -54,8 +54,8 @@ Vuex specific design patterns and practices.
## [Axios](axios.md) ## [Axios](axios.md)
Axios specific practices and gotchas. Axios specific practices and gotchas.
## [Icons](icons.md) ## [Icons and Illustrations](icons.md)
How we use SVG for our Icons. How we use SVG for our Icons and Illustrations.
## [Components](components.md) ## [Components](components.md)
......
...@@ -8,7 +8,7 @@ All new features built with Vue.js must follow a [Flux architecture][flux]. ...@@ -8,7 +8,7 @@ All new features built with Vue.js must follow a [Flux architecture][flux].
The main goal we are trying to achieve is to have only one data flow and only one data entry. The main goal we are trying to achieve is to have only one data flow and only one data entry.
In order to achieve this goal, you can either use [vuex](#vuex) or use the [store pattern][state-management], explained below: In order to achieve this goal, you can either use [vuex](#vuex) or use the [store pattern][state-management], explained below:
Each Vue bundle needs a Store - where we keep all the data -,a Service - that we use to communicate with the server - and a main Vue component. Each Vue bundle needs a Store - where we keep all the data -, a Service - that we use to communicate with the server - and a main Vue component.
Think of the Main Vue Component as the entry point of your application. This is the only smart Think of the Main Vue Component as the entry point of your application. This is the only smart
component that should exist in each Vue feature. component that should exist in each Vue feature.
...@@ -17,7 +17,7 @@ This component is responsible for: ...@@ -17,7 +17,7 @@ This component is responsible for:
1. Calling the Store to store the data received 1. Calling the Store to store the data received
1. Mounting all the other components 1. Mounting all the other components
![Vue Architecture](img/vue_arch.png) ![Vue Architecture](img/vue_arch.png)
You can also read about this architecture in vue docs about [state management][state-management] You can also read about this architecture in vue docs about [state management][state-management]
and about [one way data flow][one-way-data-flow]. and about [one way data flow][one-way-data-flow].
...@@ -51,14 +51,14 @@ of the new feature should be. ...@@ -51,14 +51,14 @@ of the new feature should be.
The Store and the Service should be imported and initialized in this file and The Store and the Service should be imported and initialized in this file and
provided as a prop to the main component. provided as a prop to the main component.
Don't forget to follow [these steps.][page_specific_javascript] Don't forget to follow [these steps][page_specific_javascript].
### Bootstrapping Gotchas ### Bootstrapping Gotchas
#### Providing data from Haml to JavaScript #### Providing data from HAML to JavaScript
While mounting a Vue application may be a need to provide data from Rails to JavaScript. While mounting a Vue application may be a need to provide data from Rails to JavaScript.
To do that, provide the data through `data` attributes in the HTML element and query them while mounting the application. To do that, provide the data through `data` attributes in the HTML element and query them while mounting the application.
_Note:_ You should only do this while initing the application, because the mounted element will be replaced with Vue-generated DOM. _Note:_ You should only do this while initializing the application, because the mounted element will be replaced with Vue-generated DOM.
The advantage of providing data from the DOM to the Vue instance through `props` in the `render` function The advantage of providing data from the DOM to the Vue instance through `props` in the `render` function
instead of querying the DOM inside the main vue component is that makes tests easier by avoiding the need to instead of querying the DOM inside the main vue component is that makes tests easier by avoiding the need to
...@@ -68,6 +68,7 @@ create a fixture or an HTML element in the unit test. See the following example: ...@@ -68,6 +68,7 @@ create a fixture or an HTML element in the unit test. See the following example:
// haml // haml
.js-vue-app{ data: { endpoint: 'foo' }} .js-vue-app{ data: { endpoint: 'foo' }}
// index.js
document.addEventListener('DOMContentLoaded', () => new Vue({ document.addEventListener('DOMContentLoaded', () => new Vue({
el: '.js-vue-app', el: '.js-vue-app',
data() { data() {
...@@ -87,13 +88,11 @@ document.addEventListener('DOMContentLoaded', () => new Vue({ ...@@ -87,13 +88,11 @@ document.addEventListener('DOMContentLoaded', () => new Vue({
``` ```
#### Accessing the `gl` object #### Accessing the `gl` object
When we need to query the `gl` object for data that won't change during the application's lyfecyle, we should do it in the same place where we query the DOM. When we need to query the `gl` object for data that won't change during the application's life cyle, we should do it in the same place where we query the DOM.
By following this practice, we can avoid the need to mock the `gl` object, which will make tests easier. By following this practice, we can avoid the need to mock the `gl` object, which will make tests easier.
It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component: It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component:
##### example:
```javascript ```javascript
document.addEventListener('DOMContentLoaded', () => new Vue({ document.addEventListener('DOMContentLoaded', () => new Vue({
el: '.js-vue-app', el: '.js-vue-app',
render(createElement) { render(createElement) {
...@@ -121,25 +120,6 @@ in one table would not be a good use of this pattern. ...@@ -121,25 +120,6 @@ in one table would not be a good use of this pattern.
You can read more about components in Vue.js site, [Component System][component-system] You can read more about components in Vue.js site, [Component System][component-system]
#### Components Gotchas
1. Using SVGs icons in components: To use an SVG icon in a template use the `icon.vue`
1. Using SVGs illustrations in components: To use an SVG illustrations in a template provide the path as a prop and display it through a standard img tag.
```javascript
<script>
export default {
props: {
svgIllustrationPath: {
type: String,
required: true,
},
},
};
<script>
<template>
<img :src="svgIllustrationPath" />
</template>
```
### A folder for the Store ### A folder for the Store
#### Vuex #### Vuex
...@@ -163,13 +143,13 @@ Refer to [axios](axios.md) for more details. ...@@ -163,13 +143,13 @@ Refer to [axios](axios.md) for more details.
Axios instance should only be imported in the service file. Axios instance should only be imported in the service file.
```javascript ```javascript
import axios from 'javascripts/lib/utils/axios_utils'; import axios from '~/lib/utils/axios_utils';
``` ```
### End Result ### End Result
The following example shows an application: The following example shows an application:
```javascript ```javascript
// store.js // store.js
...@@ -177,8 +157,8 @@ export default class Store { ...@@ -177,8 +157,8 @@ export default class Store {
/** /**
* This is where we will iniatialize the state of our data. * This is where we will iniatialize the state of our data.
* Usually in a small SPA you don't need any options when starting the store. In the case you do * Usually in a small SPA you don't need any options when starting the store.
* need guarantee it's an Object and it's documented. * In that case you do need guarantee it's an Object and it's documented.
* *
* @param {Object} options * @param {Object} options
*/ */
...@@ -186,7 +166,7 @@ export default class Store { ...@@ -186,7 +166,7 @@ export default class Store {
this.options = options; this.options = options;
// Create a state object to handle all our data in the same place // Create a state object to handle all our data in the same place
this.todos = []: this.todos = [];
} }
setTodos(todos = []) { setTodos(todos = []) {
...@@ -207,7 +187,7 @@ export default class Store { ...@@ -207,7 +187,7 @@ export default class Store {
} }
// service.js // service.js
import axios from 'javascripts/lib/utils/axios_utils' import axios from '~/lib/utils/axios_utils'
export default class Service { export default class Service {
constructor(options) { constructor(options) {
...@@ -233,8 +213,8 @@ export default { ...@@ -233,8 +213,8 @@ export default {
type: Object, type: Object,
required: true, required: true,
}, },
} },
} };
</script> </script>
<template> <template>
<div> <div>
...@@ -275,7 +255,7 @@ export default { ...@@ -275,7 +255,7 @@ export default {
}, },
created() { created() {
this.service = new Service('todos'); this.service = new Service('/todos');
this.getTodos(); this.getTodos();
}, },
...@@ -284,9 +264,9 @@ export default { ...@@ -284,9 +264,9 @@ export default {
getTodos() { getTodos() {
this.isLoading = true; this.isLoading = true;
this.service.getTodos() this.service
.then(response => response.json()) .getTodos()
.then((response) => { .then(response => {
this.store.setTodos(response); this.store.setTodos(response);
this.isLoading = false; this.isLoading = false;
}) })
...@@ -296,18 +276,21 @@ export default { ...@@ -296,18 +276,21 @@ export default {
}); });
}, },
addTodo(todo) { addTodo(event) {
this.service.addTodo(todo) this.service
then(response => response.json()) .addTodo({
.then((response) => { title: 'New entry',
this.store.addTodo(response); text: `You clicked on ${event.target.tagName}`,
}) })
.catch(() => { .then(response => {
// Show an error this.store.addTodo(response);
}); })
} .catch(() => {
} // Show an error
} });
},
},
};
</script> </script>
<template> <template>
<div class="container"> <div class="container">
...@@ -333,7 +316,7 @@ export default { ...@@ -333,7 +316,7 @@ export default {
<div> <div>
</template> </template>
// bundle.js // index.js
import todoComponent from 'todos_main_component.vue'; import todoComponent from 'todos_main_component.vue';
new Vue({ new Vue({
...@@ -365,76 +348,79 @@ Each Vue component has a unique output. This output is always present in the ren ...@@ -365,76 +348,79 @@ Each Vue component has a unique output. This output is always present in the ren
Although we can test each method of a Vue component individually, our goal must be to test the output Although we can test each method of a Vue component individually, our goal must be to test the output
of the render/template function, which represents the state at all times. of the render/template function, which represents the state at all times.
Make use of Vue Resource Interceptors to mock data returned by the service. Make use of the [axios mock adapter](axios.md#mock-axios-response-on-tests) to mock data returned.
Here's how we would test the Todo App above: Here's how we would test the Todo App above:
```javascript ```javascript
import component from 'todos_main_component'; import Vue from 'vue';
import axios from '~/lib/utils/axios_utils';
import MockAdapter from 'axios-mock-adapter';
describe('Todos App', () => { describe('Todos App', () => {
it('should render the loading state while the request is being made', () => { let vm;
let mock;
beforeEach(() => {
// Create a mock adapter for stubbing axios API requests
mock = new MockAdapter(axios);
const Component = Vue.extend(component); const Component = Vue.extend(component);
const vm = new Component().$mount(); // Mount the Component
vm = new Component().$mount();
});
afterEach(() => {
// Reset the mock adapter
mock.restore();
// Destroy the mounted component
vm.$destroy();
});
it('should render the loading state while the request is being made', () => {
expect(vm.$el.querySelector('i.fa-spin')).toBeDefined(); expect(vm.$el.querySelector('i.fa-spin')).toBeDefined();
}); });
describe('with data', () => { it('should render todos returned by the endpoint', done => {
// Mock the service to return data // Mock the get request on the API endpoint to return data
const interceptor = (request, next) => { mock.onGet('/todos').replyOnce(200, [
next(request.respondWith(JSON.stringify([{ {
title: 'This is a todo', title: 'This is a todo',
body: 'This is the text' text: 'This is the text',
}]), { },
status: 200, ]);
}));
};
let vm;
beforeEach(() => {
Vue.http.interceptors.push(interceptor);
const Component = Vue.extend(component);
vm = new Component().$mount(); Vue.nextTick(() => {
const items = vm.$el.querySelectorAll('.js-todo-list div')
expect(items.length).toBe(1);
expect(items[0].textContent).toContain('This is the text');
done();
}); });
});
afterEach(() => { it('should add a todos on button click', (done) => {
Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor);
});
// Mock the put request and check that the sent data object is correct
mock.onPut('/todos').replyOnce((req) => {
expect(req.data).toContain('text');
expect(req.data).toContain('title');
it('should render todos', (done) => { return [201, {}];
setTimeout(() => {
expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(1);
done();
}, 0);
}); });
});
describe('add todo', () => { vm.$el.querySelector('.js-add-todo').click();
let vm;
beforeEach(() => {
const Component = Vue.extend(component);
vm = new Component().$mount();
});
it('should add a todos', (done) => {
setTimeout(() => {
vm.$el.querySelector('.js-add-todo').click();
// Add a new interceptor to mock the add Todo request // Add a new interceptor to mock the add Todo request
Vue.nextTick(() => { Vue.nextTick(() => {
expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2); expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2);
}); done();
}, 0);
}); });
}); });
}); });
``` ```
#### `mountComponent` helper
### `mountComponent` helper
There is a helper in `spec/javascripts/helpers/vue_mount_component_helper.js` that allows you to mount a component with the given props: There is a helper in `spec/javascripts/helpers/vue_mount_component_helper.js` that allows you to mount a component with the given props:
```javascript ```javascript
...@@ -447,13 +433,10 @@ const data = {prop: 'foo'}; ...@@ -447,13 +433,10 @@ const data = {prop: 'foo'};
const vm = mountComponent(Component, data); const vm = mountComponent(Component, data);
``` ```
#### Test the component's output ### Test the component's output
The main return value of a Vue component is the rendered output. In order to test the component we The main return value of a Vue component is the rendered output. In order to test the component we
need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that: need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that:
### Stubbing API responses
Refer to [mock axios](axios.md#mock-axios-response-on-tests)
[vue-docs]: http://vuejs.org/guide/index.html [vue-docs]: http://vuejs.org/guide/index.html
[issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards
...@@ -466,4 +449,3 @@ Refer to [mock axios](axios.md#mock-axios-response-on-tests) ...@@ -466,4 +449,3 @@ Refer to [mock axios](axios.md#mock-axios-response-on-tests)
[issue-boards-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/boards/services/board_service.js.es6 [issue-boards-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/boards/services/board_service.js.es6
[flux]: https://facebook.github.io/flux [flux]: https://facebook.github.io/flux
[axios]: https://github.com/axios/axios [axios]: https://github.com/axios/axios
[axios-interceptors]: https://github.com/axios/axios#interceptors
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment