resources

Introduction

Xarigami Core has a set of standard 16x16px images for use throughout xarigami core and modules. They are located in the modules/base/xarimages/icons directory.

Xarigami also has a number of sprite maps used with the core sprite css. These image maps are also located in the modules/base/xarimages directory, and the associated CSS in modules/base/xarstyles.

In line with the Xaraya project, we have used the Tango Project naming conventions and a collection of Tango icons where available, plus additional GPL compatible icons where specific Tango icons were unavailable. The latter may be updated with Tango look icons in the future.

1. Using images in Xarigami Core and Modules
   • Adding an Image URL using inbuilt functions
   • Overriding an image in a theme
2. Using Image Sprites in Xarigami Core and Modules
   • Loading the sprite CSS
   • Using sprite CSS and creating your own sprite maps
   • Overriding CSS and sprite image maps
3. Using sprites in templates - Examples
4. Sprite image reference table

1. Using images in Xarigami Core and Modules

Adding an Image URL using inbuilt functions

Xarigami standard icon images may be used individually where suitable by assigning to a variable, or directly in your templates. There is a standard function to add your images, which has the added advantage of allowing you to override the images in your themes. The function automatically looks for an image in a directory called 'xarimages' in the specified module. For example:

/* Assigning to a variable in code */
$myimage = xarTplGetImage('icons/image.gif','base');

To use the function in your theme templates:

/* add an image to your template */
<img title="sometitle" src="#xarTplGetImage('myimage.png','base')#" alt="some description" />

Overriding an image in a theme

If an image has been inserted into a module system template using the standard function (xarTplGetimage()) then you can easily override this image by placing an image of the same name in your theme.

The image should be placed in the corresponding module directory in an images directory. eg If an image called 'mail.png' is located in the module/base/xarimages/icons directory you can add your own version of this in your theme at themes/[yourtheme]/modules/base/images/mail.png

Back to top

2. Using Image Sprites in Xarigami Core and Modules

All 16x16px images used throughout Xarigami Core have been consolidated into sprite image maps.  Originally we had one image map but a decision was made to split the image maps up into four different ones each containing icons that are most likely to appear on any given page.

There may be further images added to the sprite image maps in the future. To display any specific image, a CSS class is now used instead of specifying the image itself. When there are a number of images on a page, this cuts down the number of page requests, and often the cumulative image size, and reduces page load time.

To use sprites in your templates or modules, you must have the Xarigami sprite css loaded. You can then use any of the standard sprite icons from any of the four standard sprite maps.

Loading the sprites CSS

In Xarigami, the sprites CSS and sprite image maps are both located in the Base module. The sprite CSS is a small file, and loaded as part of the core css.

You can also load the sprite images and css on any of your module pages in the usual way with the style tag:

<xar:style module="base" file="xgamisprites" scope="module" version="1.0" />

The xgamisprites.css file has two important classes in it that you must use to display an image:

• a css rule to specify the image - each of these rules is made up of the image name prefixed by 'xs-' eg xs-delete
• a css rule to specify the image map where the image is. There are currently four sprite image maps and a corresponding class for each one, namely sprite (has admin icons), esprite (editor icons), dsprite (mainly display page icons), csprite (community icons). The image maps are xgamispritesa.png, xgamispritese.png, xgamispritesd.png and xgamispritesd.png.

There is no image loading until you specify one of the image map css rules.

Back to top

Creating your own sprite map and using the sprite CSS

You can create your own icon sprite map for use in your theme or modules. All you need to is create the map, and a css class that calls the map you have made that can reside in your module xarstyles directory, or in your theme style directory (module or main theme style directory). You can use all the style rules in the xgamisprite.css so you don't have to load additional css as long as your image map is compatible.

1. Create the icon map file - vertical align the 16px by 16px icons, singly in a column, and give them a vertical spacing of 30px starting from the zero coordinate position in the file.
2. Create a small CSS file, 'mysprite.css',  with the following rule in it (assuming in this example, your sprite map file is called mysprites.png): .mysprite {background: url(relative/path/toyourspritemap/mysprites.png) no-repeat top left; }
3. Load your sprite css file with the following tag: <xar:style file="mysprite' scope="module|theme|system" module="modulename" />, where the scope is either module, theme or system depending on where your css is located.
4. If you do not have the xarigami core css loaded, including xgamisprites.css, you need to also load it in your template as well (using the xar:stye tag as explained above).

Now you can use the same technique to display your icons in your page. See the examples below.

Back to top

Overriding the CSS and image map

You can override the xgamisprites.css just like you can any other core css by copying the original to your theme in the theme/<yourtheme>/modules/base/styles directory.

The sprite css file includes calls to the sprite image maps (xgamispritesa.png, xgampspritese.png, xgamispritesd.png and xgamispritesc.png all located in the Base module xarimages directory) and the image map path is relative to the sprite css file.

If you override your core CSS file and import the sprites css, remember that this import path must also be relative to the core CSS file you are importing to.

You may also want or need to define new classes to use with the sprites image map, or tweak the existing ones for your themes.

Back to top

Examples of using CSS Sprites in templates

It is easy to include any of the images in your pages once you have loaded the xgamisprites.css.  To display any of the images listed in the table below,  add the 'sprite' class, plus the class corresponding to the image you wish to use.

The xgamisprites.css caters for common situations as in the examples below including the CSS rules for the image itself, spans to hide text if buttons are required, and p tags to display icons without links.

Some examples:

<!--  Icon preceding text in a list-->

<ul>   
    <li class="sprite xs-view-refresh" title="icon preceding text"> Some text</li>
    
    <li class="esprite xs-add" title="icon preceding text"><a href="/"> Link with text</a></li>

</ul>

• Some text
• Link with text

<p class="esprite xs-edit xar-displayinline" title="icon preceding text"><a href="/">Your text</a></p>

<p class="esprite xs-add xar-displayinline" title="icon preceding text"><a href="/">Your text</a></p>

<span class="sprite xs-view-refresh" title="icon preceding text"><a href="/"> Your text</a></span>

Your text

Your text

Your text

<p class="dsprite xs-system-search" title="icon preceding text"><span> Your text</span></p>

Your text

<a class="dsprite xs-system-user" title="sometitle" href="/"> Some title</a> 

Some title

The following table lists the available sprites available in Xarigami Core and associated CSS classes. To display a sprite use the sprite class, plus any one of the classes that load the image map of choice.

Back to top

Back to top