Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
338 lines (226 sloc) 9.37 KB
.. _topics/svgicons:
=========
SVG Icons
=========
SVG images are incredibly useful: They are small in size, scale to any size and
their appearance is always crystal-sharp regardless of the device.
Cubane's SVG icon system simply allows you to declare a set of SVG-based icons
and to refer to those icons anywhere within your template.
.. _topics/svgicons/creating_svgicons:
Creating SVG Icons
==================
When creating SVG icons, we would advise using the same ``viewBox`` for all SVG
files throughout; this will make it easier to place icons within a design more
consistently.
In addition, we suggest to align all icons on the same baseline and to maintain
the same visual white space around an icon. This will greatly help to align
icons within a design.
.. _topics/svgicons/loading:
Loading the SVG icon system
===========================
Cubane's SVG icon system is implemented as a separate app, which is
``cubane.svgicons``. In order to use it, you would need to load
``cubane.svgicons`` in your project setting's list of installed apps:
``settings.INSTALLED_APPS``.
.. code-block:: python
INSTALLED_APPS = [
...
'cubane.svgicons',
'myApp',
...
]
The SVG icon system also provides some default CSS style for icons. If you wish
to use it, simply embed all resources from ``cubane.svgicons`` within the
default resource bucket that you are using for your website, for example:
.. code-block:: python
RESOURCES = {
'frontend': [
'cubane.svgicons',
'myApp',
],
...
}
.. _topics/svgicons/declaring_uni_colored_svg_icons:
Declaring uni-coloured SVG icons
================================
In your app's ``__init__.py`` file, where you declare Cubane's resources,
you can simply declare individual SVG files as SVG icons as well:
.. code-block:: python
RESOURCES = [
# website style
'css/style.css',
...
# SVG icons
'svgicons/phone.svg',
'svgicons/mail.svg',
'svgicons/location.svg'
...
]
.. tip::
As we will see later on, the name of each SVG icon file is important,
because we will simply be able to refer to the ``phone.svg`` icon file via
its name ``phone``.
As discussed in the :ref:`topics/media/media_api_urls`
section, we can use pattern expansion to make this very compact:
.. code-block:: python
RESOURCES = [
# website style
'css/style.css',
...
# SVG icons
'svgicons/*.svg',
...
]
Because the order in which Cubane processes SVG icon files is entirely
arbitrary, we do not need to be concerned about the order in which SVG icon
files are declared (which would be alphabetical when using pattern expansion).
All SVG icons declared in such way are uni-coloured by default. This means that
all shapes will automatically take the fill colour of the current text colour as
declared in your CSS style. We will see how this works in just a moment.
.. _topics/svgicons/referring_to_svg_icons:
Referring to SVG icons
======================
After having declared your SVG icons as resources, you can simply refer to an
icon by its name within your templates, for example:
.. code-block:: html+django
{% load svgicon_tags %}
<html>
<body>
...
{% svgiconref 'frontend/phone' %}
</body>
</html>
The argument contains the name of the resource bucket that contains the
referenced icon which is ``frontend`` in the example above. The name of the
bucket is followed by the name of the icon ``phone``.
Cubane will generate markup very similar to the following:
.. code-block:: html
<i class="svgicon svgicon-phone">
<svg>
<use xlink:href="/static/cubane.svgicons.frontend.39388d.svg#svgicon-phone"></use>
</svg>
</i>
In *Production* mode, the referenced external file
``cubane.svgicons.frontend.39388d.svg`` will have been generated during site
deployment automatically and contains all SVG icons declared for the
``frontend`` resource bucket. The full reference will only present the SVG icon
symbol ``svgicon-phone`` from within the file.
.. note::
Referring to SVG icons this way means that the browser will download an
external file before any SVG icon can be presented. The browser can cache
the external file once it has been downloaded.
In *Debug* mode, Cubane will generate a different path using the
:ref:`topics/media/media_api_urls` to refer to a particular SVG icon.
.. _topics/svgicons/embedding_svg_icon_sets:
Embedding SVG icon sets
=======================
Another way of using SVG icons is to embed an SVG icon set within your template.
This is usually your base template. It will contain the declaration of each SVG
icon; however, no icon has actually been presented anywhere yet.
Embedding SVG icons offer the benefit of faster rendering time since no
external resource has to be downloaded first in order to present an icon on the
screen. However, this approach -- if not considered carefully -- may overload
your initial markup file extensively.
.. code-block:: html+django
{% load svgicon_tags %}
<html>
<body>
...
{% inline_svgicons 'frontend' %}
</body>
</html>
The first argument to the ``inline_svgicons`` template tag is the resource
*bucket* from which you would like to include SVG icon resources.
Cubane will generate markup very similar to the following:
.. code-block:: html
<svg style="display: none;">
<symbol id="svgicon-phone" viewBox="0 0 64 64">...</symbol>
<symbol id="svgicon-mail" viewBox="0 0 64 64">...</symbol>
<symbol id="svgicon-location" viewBox="0 0 64 64">...</symbol>
</svg>
Each symbol declaration contains the original ``viewBox`` from the original SVG
file and its SVG shape declaration (not shown). Further, the unique identifier
for each symbol reassembles the name of each SVG icon, which was derived from
its filename.
.. note::
Cubane will remove any embedded style information for uni-coloured SVG
icons automatically because the current text colour of the containing
element will be used as the fill colour of the SVG icon.
.. _topics/svgicons/using_embedded_svg_icons:
Using embedded SVG icons
========================
After having declared SVG icons in your resources and made them available
within your template via the ``inline_svgicons`` template tag, you can now
present any embedded SVG icon by using the ``svgicon`` template tag:
.. code-block:: html+django
{% load svgicon_tags %}
<html>
<body>
<div class="header">
{% svgicon 'phone' %}
</div>
{% inline_svgicons 'frontend' %}
</body>
</html>
Ultimately this will generate markup similar to the following:
.. code-block:: html
<i class="svgicon svgicon-phone">
<svg>
<use xlink:href="#svgicon-phone"></use>
</svg>
</i>
Please note that the markup for any SVG icon is contained within the template
only once, even if the same SVG icon is used multiple times. Further, the fill
colour of an SVG icon is set to the current text colour. For example, if the
text colour of the ``.header`` container would be set to ``red``, then any shape
of the ``phone`` SVG icon would also be filled with the colour ``red``.
.. _topics/svgicons/using_multi_colored_svg_icons:
Using multi-coloured SVG Icons
==============================
By default, SVG icons are uni-coloured, which means that the current text colour
will define what the actual fill colour is used when presenting an SVG icon.
SVG icons can be declared as multi-coloured SVG icons, which means that the icon
will retain its style information; independently of the current text colour.
You can simply declare multi-coloured SVG icons by using the ``with-style``
prefix operator when declaring an SVG icon:
.. code-block:: python
RESOURCES = [
# website style
'css/style.css',
...
# multi-coloured SVG icons
'with-style|svgicons/phone.svg',
'with-style|svgicons/mail.svg',
'with-style|svgicons/location.svg'
...
]
The ``with-style`` operator is prefixed to the resource path by using the
*pipe* character:
.. code-block:: none
[<resource-prefix>] | <resource-path>
You can also use pattern expansion in combination with the ``with-style``
prefix operator, like in the following example:
.. code-block:: python
RESOURCES = [
# multi-coloured SVG icons
'with-style|styled-svgicons/*.svg',
...
]
If you are using uni-coloured *and* multi-coloured SVG icons in your project,
you could declare both types of icons by using pattern expansion based on two
different folders, for example:
.. code-block:: python
RESOURCES = [
'svgicons/*.svg',
'with-style|styled-svgicons/*.svg',
...
]
You would present a multi-coloured SVG icon in the same way as before by using
the ``svgicon`` or ``svgiconref`` template tags.
The system automatically determines if the icon is presented as a uni-coloured
SVG icon (using the current text colour as the fill colour) or as a
multi-coloured SVG icon (using the style information embedded within the SVG
icon itself).
Uni-coloured and multi-coloured SVG icons can be mixed within the same resource
bucket and can be used when embedded within a template or referred to through
an external file.