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)
......
This diff is collapsed.
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