Skip to content

G
gitlab-ce
Commit 4561ce85 authored by Tim Zallmann's avatar Tim Zallmann
Browse files
Options

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
Show whitespace changes
Inline Side-by-side
Showing with 173 additions and 135 deletions
doc/development/fe_guide/icons.md
View file @ 4561ce85
# 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**
`= sprite_icon('issues', size: 72, css_class: 'icon-danger')`
```haml
= sprite_icon('issues', size: 72, css_class: 'icon-danger')
```
**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
......@@ -28,33 +46,71 @@ We have a special Vue component for our sprite icons in `\vue_shared\components\
Sample usage :
`<icon
name="retry"
:size="32"
css-classes="top"
/>`
**name** Name of the Icon in the SVG Sprite ([Overview is available here](http://gitlab-org.gitlab.io/gitlab-svgs/)`).
**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.
```javascript
<script>
import Icon from "~/vue_shared/components/icon.vue"
export default {
components: {
Icon,
},
};
<script>
<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
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)`
## 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
doc/development/fe_guide/index.md
View file @ 4561ce85
......@@ -54,8 +54,8 @@ Vuex specific design patterns and practices.
## [Axios](axios.md)
Axios specific practices and gotchas.
## [Icons](icons.md)
How we use SVG for our Icons.
## [Icons and Illustrations](icons.md)
How we use SVG for our Icons and Illustrations.
## [Components](components.md)
......
doc/development/fe_guide/vue.md
View file @ 4561ce85
......@@ -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.
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
component that should exist in each Vue feature.
......@@ -17,7 +17,7 @@ This component is responsible for:
1. Calling the Store to store the data received
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]
and about [one way data flow][one-way-data-flow].
......@@ -51,14 +51,14 @@ of the new feature should be.
The Store and the Service should be imported and initialized in this file and
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
#### 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.
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
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:
// haml
.js-vue-app{ data: { endpoint: 'foo' }}
// index.js
document.addEventListener('DOMContentLoaded', () => new Vue({
el: '.js-vue-app',
data() {
......@@ -87,13 +88,11 @@ document.addEventListener('DOMContentLoaded', () => new Vue({
```
#### 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.
It should be done while initializing our Vue instance, and the data should be provided as `props` to the main component:
##### example:
```javascript
document.addEventListener('DOMContentLoaded', () => new Vue({
el: '.js-vue-app',
render(createElement) {
......@@ -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]
#### 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
#### Vuex
......@@ -163,9 +143,9 @@ Refer to [axios](axios.md) for more details.
Axios instance should only be imported in the service file.
```javascript
import axios from 'javascripts/lib/utils/axios_utils';
```
```javascript
import axios from '~/lib/utils/axios_utils';
```
### End Result
......@@ -177,8 +157,8 @@ export default class Store {
/**
* 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
* need guarantee it's an Object and it's documented.
* Usually in a small SPA you don't need any options when starting the store.
* In that case you do need guarantee it's an Object and it's documented.
*
* @param {Object} options
*/
......@@ -186,7 +166,7 @@ export default class Store {
this.options = options;
// Create a state object to handle all our data in the same place
this.todos = []:
this.todos = [];
}
setTodos(todos = []) {
......@@ -207,7 +187,7 @@ export default class Store {
}
// service.js
import axios from 'javascripts/lib/utils/axios_utils'
import axios from '~/lib/utils/axios_utils'
export default class Service {
constructor(options) {
......@@ -233,8 +213,8 @@ export default {
type: Object,
required: true,
},
}
}
},
};
</script>
<template>
<div>
......@@ -275,7 +255,7 @@ export default {
},
created() {
this.service = new Service('todos');
this.service = new Service('/todos');
this.getTodos();
},
......@@ -284,9 +264,9 @@ export default {
getTodos() {
this.isLoading = true;
this.service.getTodos()
.then(response => response.json())
.then((response) => {
this.service
.getTodos()
.then(response => {
this.store.setTodos(response);
this.isLoading = false;
})
......@@ -296,18 +276,21 @@ export default {
});
},
addTodo(todo) {
this.service.addTodo(todo)
then(response => response.json())
.then((response) => {
addTodo(event) {
this.service
.addTodo({
title: 'New entry',
text: `You clicked on ${event.target.tagName}`,
})
.then(response => {
this.store.addTodo(response);
})
.catch(() => {
// Show an error
});
}
}
}
},
},
};
</script>
<template>
<div class="container">
......@@ -333,7 +316,7 @@ export default {
<div>
</template>
// bundle.js
// index.js
import todoComponent from 'todos_main_component.vue';
new Vue({
......@@ -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
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:
```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', () => {
it('should render the loading state while the request is being made', () => {
const Component = Vue.extend(component);
const vm = new Component().$mount();
expect(vm.$el.querySelector('i.fa-spin')).toBeDefined();
});
describe('with data', () => {
// Mock the service to return data
const interceptor = (request, next) => {
next(request.respondWith(JSON.stringify([{
title: 'This is a todo',
body: 'This is the text'
}]), {
status: 200,
}));
};
let vm;
let mock;
beforeEach(() => {
Vue.http.interceptors.push(interceptor);
// Create a mock adapter for stubbing axios API requests
mock = new MockAdapter(axios);
const Component = Vue.extend(component);
// Mount the Component
vm = new Component().$mount();
});
afterEach(() => {
Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor);
// 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();
});
it('should render todos returned by the endpoint', done => {
// Mock the get request on the API endpoint to return data
mock.onGet('/todos').replyOnce(200, [
{
title: 'This is a todo',
text: 'This is the text',
},
]);
it('should render todos', (done) => {
setTimeout(() => {
expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(1);
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();
}, 0);
});
});
describe('add todo', () => {
let vm;
beforeEach(() => {
const Component = Vue.extend(component);
vm = new Component().$mount();
it('should add a todos on button click', (done) => {
// 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');
return [201, {}];
});
it('should add a todos', (done) => {
setTimeout(() => {
vm.$el.querySelector('.js-add-todo').click();
// Add a new interceptor to mock the add Todo request
Vue.nextTick(() => {
expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2);
});
}, 0);
done();
});
});
});
```
#### `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:
```javascript
......@@ -447,13 +433,10 @@ const data = {prop: 'foo'};
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
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
[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)
[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
[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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7