Custom Icons

DOCman uses an icon font to display all of its icons. Icon fonts are like fonts, except that they display symbols instead of letters and numbers. Their quality don't degrade on different screen types and sizes, great for responsive layouts.

If you need to change the icons that we chose it’s possible to override them. To follow this tutorial you need a good understanding of CSS and template overriding in Joomla.

Front-end

There are three ways to get your own custom icons in DOCman:

upload a custom icon
use background images
use a custom icon font

Upload custom icons

The easiest way to change the icon is by uploading your own. Just open a document in the administrator and click the "Select custom icon" as seen in the screenshot below.

Using background images

In this second technique we are going to override the default icons. This will change all icons on your website at once. It’s no longer possible to use the icons we picked since we’re using / overriding the existing markup.

If you’re feeling old school or if you need to use icons with multiple colors you should use this second technique. We are basically going to use existing class names and change the output of these classes so they’re showing background images instead of an icon font.

Currently we are using the following classes for our 9 base icons:

.k-icon-document-archive
.k-icon-document-audio
.k-icon-document-default
.k-icon-document-document
.k-icon-document-folder
.k-icon-document-image
.k-icon-document-pdf
.k-icon-document-spreadsheet
.k-icon-document-video

These are the 9 icons you can find in the image below from left to right. We are using the :before pseudo element to display the icons:

Available icons

To start with clean classes you need to add some CSS to your website. If you’re using a free or commercial template and want to be able to update your template in the future we strongly recommend you to create a separate icons.css file instead of adding this CSS to the template main stylesheet. So how do you do that?

Create an empty file with a text editor and save it as icons.css in your template root directory.
Open your template’s index.php file
Add the stylesheet to the code. Here’s a small tutorial on adding custom stylesheets: http://docs.joomla.org/JDocument/addStyleSheet
Upload the files to your server

We recommend creating a new icons.css stylesheet because every time you update your template there’s a chance you will remove your style declarations contained within the master template css file. This way all you will need to do is repeat steps 3 & 4 to bring back your new icons.

Protostar template example

If you use Protostar you could search for the following line in the index.php file

<?php
$doc->addStyleSheet('templates/'.$this->template.'/css/template.css');

And right below add this line:

<?php
$doc->addStyleSheet( 'templates/' . $this->template . '/icons.css' );

That will load your icons.css file into the template. Now add the following lines of code to your icons.css file:

body .koowa.koowa [class^="k-icon-document-"]:before,
body .koowa.koowa [class*=" k-icon-document-"]:before {
  content: " ";
}

By adding these lines we are telling the template to clear the content property by only showing a space instead. We do this because the icon font uses this content property to define which icon has to be showed. We added the body element before our class name so our new styles will always be more important than the original ones. This makes sure we won’t get any conflicts. This is how the default DOCman icon styling is overridden.

Now you need to tell the template which images to load. First make sure that the images you want to use are located in the template directories. For example if you’re using the "Protostar" template then you could place the images in:

[joomla] > templates > protostar > images > custom_docman_icons

Now the only way to use images as icons is by using an image background.

There’s actually only one property you have to add per class in order for this to work. Just add the correct image file path to each separate class using the background-image property like so:

body .koowa.koowa .k-icon-document-archive:before {
  background-image: url("images/custom_docman_icons/my_archive_icon.png");
}
body .koowa.koowa .k-icon-document-audio:before {
  background-image: url("images/custom_docman_icons/my_audio_icon.png");
}

Guidance on choosing your icon image

You preferably want to work with transparent PNG files since they can be used on any background color.
The icon area is either 16x16 pixels, 64x63 pixels or something in between so make sure your image is at least 64x64 pixels.
It’s also required to make your icons square shaped.
And if you want beautiful icons on high-resolution screens be sure to use images that are at least 128x128 pixels.

Note: You can also use larger images like 600x600 pixels but this will drastically slow down your website. We recommend using a maximum width and height of 128 pixels.

An example of a finished icon overwrite using images

body .koowa.koowa [class^="k-icon-document-"]:before,
body .koowa.koowa [class*=" k-icon-document-"]:before {
  content: " ";
}
body .koowa.koowa .k-icon-document-archive:before {
  background-image: url("images/custom_docman_icons/my_archive_icon.png");
}
body .koowa.koowa .k-icon-document-audio:before {
  background-image: url("images/custom_docman_icons/my_audio_icon.png");
}
body .koowa.koowa .k-icon-document-default:before {
  background-image: url("images/custom_docman_icons/my_default_icon.png");
}
body .koowa.koowa .k-icon-document-document:before {
  background-image: url("images/custom_docman_icons/my_document_icon.png");
}
body .koowa.koowa .k-icon-document-folder:before {
  background-image: url("images/custom_docman_icons/my_folder_icon.png");
}
body .koowa.koowa .k-icon-document-image:before {
  background-image: url("images/custom_docman_icons/my_image_icon.png");
}
body .koowa.koowa .k-icon-document-pdf:before {
  background-image: url("images/custom_docman_icons/my_pdf_icon.png");
}
body .koowa.koowa .k-icon-document-spreadsheet:before {
  background-image: url("images/custom_docman_icons/my_spreadsheet_icon.png");
}
body .koowa.koowa .k-icon-document-video:before {
  background-image: url("images/custom_docman_icons/my_video_icon.png");
}

Using a Custom Icon Font

A better solution might be to use your own custom icon font. This technique works almost the same as the one with images but we’ve got a few extra steps to do.

First create your own custom icon font consisting of the 9 icon types that are available:

Available icons

archive
audio
default
document
folder
image
pdf
spreadsheet
video

You can easily create your own custom icon fonts with one of the following tools:

For this tutorial I’m going to use the code that is generated by icomoon.io since we use this app ourselves.

Just like in the image technique we are going to use the existing class names and just assign different icons to them. But before we can do that we have to make sure that our CSS file can locate the proper font files.

Download the font that you created and unzip the file. Within this file you will find a couple of files and directories. Be sure to copy all the fonts from the "fonts" directory and add these files to your template. If you are using the “Protostar” template you could (for example) add the font files to:

templates > protostar > fonts > custom_docman_fonts

To start with clean classes you need to add some CSS to your website. If you’re using a free or commercial template and want to be able to update your template in the future we strongly recommend you to create a separate icons.css file instead of adding this css to the template main stylesheet. So how do you do that?

Create an empty file with a text editor and save it as icons.css in your template root directory.
Open your template’s index.php file
Add the stylesheet to the code. Here’s a small tutorial on adding custom stylesheets: http://docs.joomla.org/JDocument/addStyleSheet
Upload the files to your server

Protostar template example

If you use Protostar you could search for the following line in the index.php file

$doc->addStyleSheet('templates/'.$this->template.'/css/template.css');

And right below add this line:

$doc->addStyleSheet( 'templates/' . $this->template . '/icons.css' );

That will load your icons.css file into the template.

Next open the style.css file (contained within the root of the icon font zip you downloaded) and copy the contents and paste them in your icons.css file:

[joomla] > templates > protostar > icons.css

Now we’ve got to update the CSS style declarations to match those used by DOCman. Look for the area that starts with "[class^=".

[class^="icon-"], [class*=" icon-"] {

This line has to be changed to the following:

body .koowa.koowa .k-icon-document-default:before,
body .koowa.koowa .k-icon-document-image:before,
body .koowa.koowa .k-icon-document-video:before,
body .koowa.koowa .k-icon-document-archive:before,
body .koowa.koowa .k-icon-document-folder:before,
body .koowa.koowa .k-icon-document-pdf:before,
body .koowa.koowa .k-icon-document-audio:before,
body .koowa.koowa .k-icon-document-document:before,
body .koowa.koowa .k-icon-document-spreadsheet:before {

So the revised style declaration should now look something like this:

body .koowa.koowa .k-icon-document-default:before,
body .koowa.koowa .k-icon-document-image:before,
body .koowa.koowa .k-icon-document-video:before,
body .koowa.koowa .k-icon-document-archive:before,
body .koowa.koowa .k-icon-document-folder:before,
body .koowa.koowa .k-icon-document-pdf:before,
body .koowa.koowa .k-icon-document-audio:before,
body .koowa.koowa .k-icon-document-document:before,
body .koowa.koowa .k-icon-document-spreadsheet:before {
    font-family: 'icomoon';
    speak: none;
    font-style: normal;
    font-weight: normal;
    font-variant: normal;
    text-transform: none;
    line-height: 1;
    -webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
}

Next we have to manually link the codes in the "content" property to the class names we are using. The codes in the “content:” property are characters from the “Private Use Area of Unicode”. Using these characters make sure that screen readers won’t read single Latin characters but just ignore the characters instead. These codes are usually generated by the tool you used to create the icon font. More information about this can be found on the icomoon.io docs page.

We want to use the existing class names. But we need to add the new characters to them. So let’s say you’ve got the following class in your css file (that comes with the font) to represent the "image" icon:

.icon-camera:before {
    content: "\e601";
}

To actually make this work you should change it to:

body .koowa.koowa .k-icon-document-image:before {
    content: "\e601";
}

The important part here is that the "content" property doesn’t get changed. You have to do this manually for all 9 icons.

An example of a finished icon overwrite (icons.css) using a font

@font-face {
  font-family: 'icomoon';
  src:url('fonts/icomoon.eot');
  src:url('fonts/icomoon.eot?#iefix') format('embedded-opentype'),
  url('fonts/icomoon.ttf') format('truetype'),
  url('fonts/icomoon.woff') format('woff'),
  url('fonts/icomoon.svg#icomoon') format('svg');
  font-weight: normal;
  font-style: normal;
}
body .koowa.koowa .k-icon-document-default:before,
body .koowa.koowa .k-icon-document-image:before,
body .koowa.koowa .k-icon-document-video:before,
body .koowa.koowa .k-icon-document-archive:before,
body .koowa.koowa .k-icon-document-folder:before,
body .koowa.koowa .k-icon-document-pdf:before,
body .koowa.koowa .k-icon-document-audio:before,
body .koowa.koowa .k-icon-document-document:before,
body .koowa.koowa .k-icon-document-spreadsheet:before {
  font-family: 'icomoon';
  speak: none;
  font-style: normal;
  font-weight: normal;
  font-variant: normal;
  text-transform: none;
  line-height: 1;
  /* Better Font Rendering =========== */
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
}
body .koowa.koowa .k-icon-document-default:before {
  content: "\e600";
}
body .koowa.koowa .k-icon-document-image:before {
  content: "\e601";
}
body .koowa.koowa .k-icon-document-video:before {
  content: "\e602";
}
body .koowa.koowa .k-icon-document-archive:before {
  content: "\e603";
}
body .koowa.koowa .k-icon-document-folder:before {
  content: "\e604";
}
body .koowa.koowa .k-icon-document-pdf:before {
  content: "\e605";
}
body .koowa.koowa .k-icon-document-audio:before {
  content: "\e606";
}
body .koowa.koowa .k-icon-document-document:before {
  content: "\e607";
}
body .koowa.koowa .k-icon-document-spreadsheet:before {
  content: "\e608";
}

Backend

Right now we’ve only covered how to add the images to the frontend, but wouldn’t it be useful to have the same icons display on the administrator side?

This is basically the same as adding the new icons to the frontend template. First locate the administrator template you are using. We are using the "Isis" template in the following example which can be found here:

[joomla] > administrator > templates > isis

To make things a little bit easier we’re just going to use the same file we already created. So Basically the only thing you have to do is this:

Download the administrator template index.php file
locate the line that starts with a piece of code that looks like this:

$doc->addStyleSheet('templates/' . $this->template ….

Add the following line right below (replacing [your template] with protostar for example):

$doc->addStyleSheet(JURI::root().'templates/[your template]/icons.css');

Upload the index.php file and you should be good to go.

Why so much code?

The code is so explicit to make sure our extensions look great in any Joomla template. Using a "better safe then sorry" approach means you need to override all classes.