Icon and Icon Pool

To use your own icon font files in the sap.ui.core.Icon control, the font file needs to be declared with font-face tag in the CSS styles and the icon font file needs to be registered in sap.ui.core.IconPool. The required icon font file depends on the browser supported by your application. For Internet Explorer (IE) versions below IE9, the font files need the following extensions: .eot and .ttf. For other browser versions, only the .ttf extension is required.

To add custom icons, proceed as follows:

1. Declare the font-face tag in your CSS.

   Example for IE versions below IE9:

   <style>
   font-face {
       font-family: 'SAP-icons'; /*Please replace 'SAP-icons' with your font name which will be used when register in sap.ui.core.IconPool*/
       src: url('_PATH_TO_EOT_FILE_');
       src: url('_PATH_TO_EOT_FILE_?#iefix') format('embedded-opentype'), /*?#iefix is required to be added to the end of the path of eot file here*/
            url('_PATH_TO_TTF_FILE_') format('truetype');
       font-weight: normal;
       font-style: normal;
   };
   </style>

   Example for IE versions as of IE9:

   <style>
   @font-face {
       font-family: 'SAP-icons'; /*Please replace 'SAP-icons' with your font name which will be used when register in sap.ui.core.IconPool*/
       src: url('_PATH_TO_TTF_FILE_') format('truetype');
       font-weight: normal;
       font-style: normal;
   };
   </style>

2. Call sap.ui.core.IconPool.addIcon with the following parameters for each character your icon supports:

   • iconName: This parameter defines the name of the current icon. The icon name is used together with the collection name as an identifier for the icon to address the icon via URI and must, thus, be unique within the collection.

   • collectionName: This parameter defines the name of an icon collection. Together with the icon name it is used to uniquely identify an icon in a URI.

   • fontFamily: This parameter matches the string you have used in the @font-face tag in CSS for the font-family property ('SAP-icons' in the code snippet in step 1).

   • content: This parameter defines the special character that represents this icon; use a format like 'e000' without escape character.

To reference icons, you assign the icon URI to a control by setting sURI for the control's corresponding property. To get the icon URI, the following two options exist:

• Call sap.ui.core.IconPool.getIconURI with the iconName property:

  jQuery.sap.require("sap.ui.core.IconPool");
  var sURI = sap.ui.core.IconPool.getIconURI("accidental-leave");//please change the parameter to the name of your desired icon

• If you know the collection name and the icon name, write the icon URI directly in the following format:

  sap-icon://[collection-name]/[icon-name]

  Note You need the collection name only for custom icons. The URI for predefined icons does not need the collection name.

The following code snippet shows how the sap.m.Dialog control that already supported image URI has been adapted to also support icon URI. sap.ui.core.IconPool.createControlByURI returns an instance of sap.ui.core.Icon if sURI is an icon URI. Otherwise, the second parameter is called as a constructor method to create an instance. The sURI is set for the src property of the instance.

sap.m.Dialog.prototype.setIcon = function(sURI){
    this.setProperty("icon", sURI, true);
    if(!jQuery.os.ios){
       //icon is only shown in non iOS platform
       if(this._iconImage){
           this._iconImage.setSrc(sURI);
       }else{
           this._iconImage = sap.ui.core.IconPool.createControlByURI({
               src: sURI //src is mandatory
               /* other properties can be put here, such as id, ...*/
           }, sap.m.Image);
       }
   }
   return this;
};

If the img tag is rendered directly in the control, and not by creating an image control, use the writeIcon method on sap.ui.core.RenderManager. The writeIcon method accepts an URI as the first parameter. Depending on this parameter, it renders either an img or a span tag. The classes and attributes defined in the second and third parameter are also added to the rendered tag.

Font face is inserted into the style sheet dynamically when Icon or writeIcon are used for the first time. If the special character needs to be written into the CSS to show the icon in a control, call the sap.ui.core.IconPool.insertFontFaceStyle function to insert the built in font face in your CSS. This is shown in the following code snippet:

jQuery.sap.require("sap.ui.core.IconPool");
sap.ui.core.IconPool.insertFontFaceStyle();

If you render the icon span directly in your control, or use icon font in your CSS, you have the maximal freedom to style the Icon control.

If you use the icon by creating an instance of sap.ui.core.Icon within your control, however, use the CSS class sapUiIcon to add a new style to the icon. To avoid influencing the style of icons used elsewhere, wrap the icon CSS class with your control's root DOM class.