How to use a different icon font - softwareloop/alfresco-inboxes GitHub Wiki

Alfresco-inboxes already includes the really nice ZURB Foundation icons, but if you want to use another icon set, this pages explains how to do it.

We'll use Font Awesome as an example and here is a screenshot of what we want to achieve:

Step 1: download Font Awesome

Download Font Awesome. The current version is 4.2.0 and the distribution zip is called font-awesome-4.2.0.zip.

In alfresco-inboxes' source code locate the folder src/main/amp/web/components/softwareloop/inboxes/ and uncompress the zip file there.

To be sure the paths are correct, check that Font Awesome's main css file is located at src/main/amp/web/components/softwareloop/inboxes/font-awesome-4.2.0/css/font-awesome.min.css

Step 2: reference the CSS

Now locate the Inbox.js file under src/main/amp/web/js/softwareloop/inboxes. This file is responsible for rendering and managing each inbox on the left side of the plugin's page.

Approximately at line 30 is the following definition:

cssRequirements: [
    {cssFile: "./css/Inbox.css"},
    {cssFile: "./css/Item.css"},
    {cssFile: "/components/softwareloop/inboxes/zurb-foundation-icons/general_foundicons.css"}
],

Alfresco Aikau has a complex mechanism for managing, minimising and caching css dependencies. The cssRequiements definition plays an important role in this. Here the definition points to three css'. The first two are needed to give inboxes a graphical style. The third one is the inclusion of the ZURB Foundation icon set. To include Font Awesome, all we need to do is to add a fourth css requirement:

cssRequirements: [
    {cssFile: "./css/Inbox.css"},
    {cssFile: "./css/Item.css"},
    {cssFile: "/components/softwareloop/inboxes/zurb-foundation-icons/general_foundicons.css"},
    {cssFile: "/components/softwareloop/inboxes/font-awesome-4.2.0/css/font-awesome.min.css"}
],

Notice that it is possible to use more than one icon font at a time. Introducing Font Awesome does not preclude us from using ZURB Foundation or any other fonts.

Step 3: set the icon classes

Most of the configuration of alfresco-inboxes is done in the inboxes.get.config.xml file located under src/main/amp/config/alfresco/web-extension/site-webscripts/softwareloop/inboxes/.

A previous page explained how to customise the inbox icons using the iconClass attribute. For example one of the standard inboxes is configured like this:

<inbox id="drafts" iconClass="foundicon-paper-clip">

foundicon-paper-clip is a specific css classes used in ZURB Foundation. In Font Awesome, the equivalent would be something like fa fa-dashboard, so the inbox definition has to be changed accordingly:

<inbox id="drafts" iconClass="fa fa-dashboard">

Feel free to browse Font Awesome's icon catalogue and choose the ones you like best.

To reproduce the screenshot at the beginning of this page, you can use this sample inboxes.get.config.xml:

<inboxes>
    <group id="my-documents">
        <inbox id="drafts" iconClass="fa fa-dashboard">
            <query><![CDATA[
            SELECT d.*, t.* 
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE contains(d, 'PATH:"/app:company_home/st:sites/cm:swsdp/cm:documentLibrary/cm:Meeting_x0020_Notes/*"')
            ]]></query>
        </inbox>
        <inbox id="for-my-approval" iconClass="fa fa-bell">
            <query><![CDATA[
            SELECT d.*, t.*
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE contains(d, 'PATH:"/app:company_home/st:sites/cm:swsdp/cm:documentLibrary/cm:Budget_x0020_Files/cm:Invoices/*"')
            ]]></query>
        </inbox>
        <inbox id="overdue" iconClass="fa fa-envelope">
            <query><![CDATA[
            SELECT d.*, t.*
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE contains(d, 'PATH:"/app:company_home/st:sites/cm:swsdp/cm:documentLibrary/cm:Agency_x0020_Files/cm:Contracts/*"')
            ]]></query>
        </inbox>
        <inbox id="high-priority" iconClass="fa fa-bar-chart">
            <query><![CDATA[
            SELECT d.*, t.*
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE contains(d, 'PATH:"/app:company_home/st:sites/cm:swsdp/cm:documentLibrary/cm:Agency_x0020_Files/cm:Mock-Ups/*"')
            ]]></query>
        </inbox>
    </group>
    <group id="archive">
        <inbox id="invoices" iconClass="fa fa-line-chart">
            <query><![CDATA[
            SELECT d.*, t.*
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE d.cmis:objectTypeId='cmis:document'
            AND d.cmis:createdBy = 'mjackson'
            ]]></query>
        </inbox>
        <inbox id="purchase-orders" iconClass="fa fa-hand-o-right">
            <query><![CDATA[
            SELECT d.*, t.*
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE d.cmis:objectTypeId='cmis:document'
            AND d.cmis:createdBy = 'abeecher'
            ]]></query>
        </inbox>
        <inbox id="quotations" iconClass="fa fa-twitter">
            <query><![CDATA[
            SELECT d.*, t.*
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE contains(d, 'PATH:"/app:company_home/st:sites/cm:swsdp/cm:documentLibrary/cm:Presentations/*"')
            ]]></query>
        </inbox>
        <inbox id="marketing-documents" iconClass="fa fa-github">
            <query><![CDATA[
            SELECT d.*, t.*
            FROM cmis:document AS d
            JOIN cm:titled AS t on d.cmis:objectId = t.cmis:objectId
            WHERE contains(d, 'PATH:"/app:company_home/st:sites/cm:swsdp/cm:documentLibrary/cm:Agency_x0020_Files/cm:Images/*"')
            ]]></query>
        </inbox>
    </group>
</inboxes>

Conclusions

Icons are small details that cost little in terms of customisation effort but give a lot in terms of the final polished look of a webapp.

Another page shows how to use good old bitmap icons and, while at it, how to customise an Aikau component.