Skip to content

Latest commit

 

History

History
84 lines (55 loc) · 5.51 KB

svg-processing.md

File metadata and controls

84 lines (55 loc) · 5.51 KB
Raw

English description | Описание на русском

Working with SVG

TARS supports two workflows for working with vector graphic: SVG-sprite and SVG-symbols. There are exist some more workflwos (inline SVG in HTML, inline in CSS, base64 in CSS, SVG-stack), but SVG-sprite and SVG-symbols is the best choice at the moment, cause they totally are supported by all browsers (from IE9). That workflows are really fast and it is comfortable to work with them.

You cannot use symbols and SVG-sprite in one time. All options for working with SVG is set in tars-config.

It is important that when you save the image in SVG there is have to be viewBox attribute! Save SVG as an object that can be inserted into HTML without changing (in Adobe Illustrator Image location option — Embed).

SVG symbols

Build for IE8 not supported in that workflow

In that workflow SVG-images will be combined into one SVG-file and every iscon will be represented as SVG-symbol. You can reuse each icon, set colors and size from CSS in that case. You can get more info from css-tricks.

Images that will be included in such way must be in a folder (default path): 'static/img/svg/'. Nested directories are not supported.

Symbols are created to use it in tempaltes (html|jade|hbs). In CSS you can change colors, size, add stroke and stroke width. You sholud use helpers for symbols using in templates and components. Helper creates HTML, add size's attributes and custom classname.

Using in handlebars:

{{Icon iconName='iconName' className='customClass'  iconWidth='25' iconHeight='25'}}

Using in jade:

!= jadeHelpers.Icon.call(locals, {iconName: 'iconName', className: 'customClass', iconWidth: '25', iconHeight: '25'})

Using in pug:

!= pugHelpers.Icon.call(locals, {iconName: 'iconName', className: 'customClass', iconWidth: '25', iconHeight: '25'})

You can set two properites: iconname (iconName), which you'd like to include (without extension), classname for that icon (customClass), sizes (iconWidth, iconHeight). Sizes are not required, so you can drop it from helper options. TARS generate class automatically by using template icon__iconName in case you have not passed it to helper. TARS use sizes from svg file if you not passed it to helper. You can use that helper in pages and components too. That helper will generate HTML like:

<svg class="chrome" width="32px" height="32px">
    <use xlink:href="#chrome"></use>
</svg>

File with ready symbols is generated by TARS automatically. It only remains to connect it. TARS supports several ways to include SVG-symbols:

  • inject — inject into the page code;
  • separate-file-with-link — separate file with link from each use to that file;
  • separate-file — just separate file.

In inject case only Icon ID (its name) will be set in symbol use tag. You can manage, where you'd like to inject all symbols by using label %=symbols=%. It is not necessary to remove that labels and scripts from tempaltes, cause they will be deleted from build automatically, if they are not used! In case of using separate file with link, path to SVG-symbols file and Icon ID will be passed into xlink:href.

<svg class="chrome" width="32px" height="32px">
    <use xlink:href="static/images/svg-symbols.svg#chrome"></use>
</svg>

In that case SVG-symbols file will be cached in browser. You can set the path to file by using option pathToExternalSymbolsFile in tars-config. File will be generated in that directory. File will be created in the root directory of build by default.

SVG-symbols loading from separate file is supported in all modern browsers natively except IE9 - Edge. You can use polyfill for them. You can exclude it from build by using option usePolyfillForExternalSymbols if you don't support IE. The code of polyfill including is in templates by default. It is not necessary to remove that labels and scripts from tempaltes, cause they will be deleted from build automatically, if they are not used!

In the third one you have to implement your own workflow of SVG-symbols injecting to HTML. You have to write some code to load SVG-symbols file and inject it into the page-code. There are two useful articles, which describe the best ways to implement it: css-tricks and osvaldas.info. The last is the most cool.

More info about symbols configuration you can get from options docs.

SVG-sprites

SVG images are combined into the SVG-sprite.

SVG-images in the release-version is minified and has release hash in the name. Images that will be included in such way must be in a folder (default path): 'static/img/svg/'. Nested directories are not supported.

You can include image by using mixin (example on scss):

@include bg-svg($svg-image-name);  // Sprite with svg-images including

Attention, $svg-image-name is a var, that has the same name as the icon, which you'd like to use (without extension).

bg-svg mixin will include SVG-sprite as a background, will set all necessary offsets and sizes into the CSS. In case of --ie and --ie8 flags using sprite of rastered SVG-images will be created for IE8 automatically.

You can not set color of SVG icon from CSS. So, it is necessary to create production-ready icon, with correct size and color.