Summary
Images
Question/Problem Description
This article defines how to deal with images in update.CRM web.
Environment
update.CRM web 8.x
Resolution
Folder Structure
Images are located in folder web/images /.
The images folder contains several sub folders, all starting with the name of a theme . A theme changes the visual appearance of update.CRM web and can be configured using web configuration parameter Style .
/images
/update
/update.te.base
/update.te.isi
...
As a template developer you will put your images into a folder named "[theme].[templatename]" (e.g. update.te.isi).
The touchable theme
The touchable theme is a special theme used on touch devices. By convention the theme is named [theme].[touchable] . The fact that the theme is no longer referred to using [theme] but [theme].[touchable] means that your template folder will not be taken into account on touch devices. Therefore, as a template developer, if you want your images to be included in an existing touchable theme, you will have to link your existing [ theme].[templatename] folder to a new folder called [theme].[touchable].[templatename] (e.g. update.touchable.te.isi).
This link can be created using the mklink tool http://technet.microsoft.com/en-us/library/cc753194.aspx
The folder structure in that case would look like
/images
/[theme]
/[theme].touchable
/[theme].te.base
/[theme].te.isi
/[theme].touchable.te.base - a folder link pointing to [theme].te.base
/[theme].touchable.te.isi - a folder link pointing to [theme].te.isi
...
Configuration
In order to use your images you have to configure them in CRM.designer. The most important part is to specify the correct file name. Your options are
Filename as configured in CRM.designer | URL used at runtime |
---|---|
test.png | /images/[theme]/test.png |
/update.te.base/test.png | /images/update.te.base/test.png |
/{theme}.te.base/test.png | /images/[theme].te.base/test.png |
As you can see in the example above you can use placeholder {theme} to include the name of the current theme into your path.
Variations
update.CRM web uses multiple variations of images. Variations can be
- location
- size
- state
The variations are identified by the decorators used in the name as described in the Image Naming Guidelines .
It is recommend to create at least the variations for the normal, small(-s) and extra small(-xs) size as e.g. menus use extra small images and (header)buttons use small images.
For example if you add a new image with name project-sirene.png and size 32x32 pixel, you should also add an image with name project-sirene-s.png and size 16x16 pixel and an image with name project-sirene-xs.png and size 14x14 pixel.
Naming
For how to name your image file see Image Naming Guidelines
CSS Sprites
update.CRM web makes heavy use of CSS sprites to optimize the number of HTTP requests sent to the server.
update.CRM web creates CSS sprites automatically. It scans all folders named [theme]* for files named [spritename].sprite.xml.
Example: Defining a sprite "te-base"
/images
/update
/update.te.base
te-base.sprite.xml
This XML file defines which images to include in the CSS sprite. The most simple version (and the most common too) is to include all image files.
Example: Including all .png files in the CSS sprite.
<?xml version="1.0" encoding="utf-8" ?>
<Sprite>
<Include Files="*.png" />
</Sprite>
The CSS generator will not only include the listed images into the CSS sprite, it will also create CSS styles and mixins for accessing the images on the client. The CSS rules will be named like [spritename]-[imagefilename]. See the following section on how to use sprites.
Important! In order to be able to use images for large- or small item templates, these images MUST be added to the CSS sprite.
Using Images in Code
By default update.CRM web will prefer CSS sprites over <img/> when creating images.
Note: The following information is valid for V8.2 or later. 8.2+
The most convenient and recommended way to create an image is to use jQuery extension image:
// create a CSS sprite for the image in file "logo.png" (defined in sprite "te-base")
$("<span/>").image("te-base-logo");
// create a CSS sprite for the image named "logo" (configured in CRM.designer)
$("<span/>").image("logo");
If - for whatever reason - you explicitly want to create an image based on an <img/> element, then use the same extension method image but use an <img/> element instead of <span/> :
// create an image for file "logo.png" (defined in sprite "te-base")
$("<img/>").image("te-base-logo");
// create an image for the image named "logo" (configured in CRM.designer)
$("<img/>").image("logo");
Note: The following information is valid for V8.1 or earlier. <8.2
In versions prior 8.2 the recommended way to create CSS sprites was to use extension method sprite:
// create a CSS sprite for V8.1 or earlier:
$("<span/>").sprite("te-base-logo");
Note: To maintain compatibility extension method sprite is still available in V8.2. However, it has been marked as obsolete and will be removed in a future version.
Using Images in Forms designer
If you want to design a form and use the css sprite images, you can achieve this by using Image widget or entering the correct image sprite (wherever it is appropriate).
If your image name is:
u8-infoarea-fi.png
then your sprite image name is
u8-img-infoarea-fi
(notice, the -img- insertion after u8, and that there is no file extension). Also, the sprites support setting the image size by using suffixes. The available suffixes are:
- - s (example: u8-img-infoarea-fi-s )
- -xs (example: u8-img-infoarea-fi-xs )