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.

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.

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.

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:

RESOURCES = {
    'frontend': [
        'cubane.svgicons',
        'myApp',
    ],
    ...
}

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:

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 Media API URLs section, we can use pattern expansion to make this very compact:

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.

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:

{% 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:

<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 Media API URLs to refer to a particular SVG icon.

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.

{% 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:

<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.

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:

{% 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:

<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.

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:

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:

[<resource-prefix>] | <resource-path>

You can also use pattern expansion in combination with the with-style prefix operator, like in the following example:

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:

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.