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.
@@ -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.
@@ -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.
Loading
Loading
@@ -17,7 +17,7 @@ This component is responsible for:
1. Calling the Store to store the data received
1. Mounting all the other components
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].
Loading
Loading
@@ -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
Loading
Loading
@@ -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() {
Loading
Loading
@@ -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 lifecyle, 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) {
Loading
Loading
@@ -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
Loading
Loading
@@ -163,13 +143,13 @@ 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
The following example shows an application:
The following example shows an application:
```javascript
// store.js
Loading
Loading
@@ -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
*/
Loading
Loading
@@ -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 = []) {
Loading
Loading
@@ -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) {
Loading
Loading
@@ -233,8 +213,8 @@ export default {
type: Object,
required: true,
},
}
}
},
};
</script>
<template>
<div>
Loading
Loading
@@ -275,7 +255,7 @@ export default {
},
created() {
this.service = new Service('todos');
this.service = new Service('/todos');
this.getTodos();
},
Loading
Loading
@@ -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;
})
Loading
Loading
@@ -296,18 +276,21 @@ export default {
});
},
addTodo(todo) {
this.service.addTodo(todo)
then(response => response.json())
.then((response) => {
this.store.addTodo(response);
})
.catch(() => {
// Show an error
});
}
}
}
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>
<divclass="container">
Loading
Loading
@@ -333,7 +316,7 @@ export default {
<div>
</template>
// bundle.js
// index.js
import todoComponent from 'todos_main_component.vue';
new Vue({
Loading
Loading
@@ -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', () => {
let vm;
let mock;
beforeEach(() => {
// Create a mock adapter for stubbing axios API requests
mock = new MockAdapter(axios);
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', () => {
