Changes to Sencha Touch 2.2 Theming Part 1: Using Iconography

Sencha Touch 2.2 handles iconography very differently than its predecessors. Whereas Touch 1.x-2.1 base-64 encoded PNG files into your app’s stylesheet, Touch 2.2 instead uses a web font from http://pictos.cc/font/ to render iconography in your app’s buttons. This new methodology should significantly improve the performance of your app, particularly with respect to memory consumption. Unfortunately, you will likely need to spend a small bit of time refactoring your code as the strings used to identify icons do not match up to the icon library that had been available in previous versions of Touch. More importantly, the procedure for incorporating your own custom iconography has changed as you will now need to encode your custom icons into a web font (covered in part 2 of this blog entry).

Reviewing the Out of the Box Icons

I’ve catalogued the new iconography and their corresponding string identifiers below:

anchor	box	upload	forbidden	lightning	rss	team	info
heart	list	list	table	folder	pencil	chat2	retweet
time	switch	camera	chat	settings2	settings	attach ment2	bird
delete_ black1	eye	file	browser	home	inbox	network	key
news	photos	power	action	favorites	plane	user	video
truck	chart	expand	refresh	check	check2	play	pause
forward	rewind	play2	refresh2	minus	battery	left	right
wireless	spedo meter	more	print	down load	warning _black	locate	trash
bank	flag	add	delete	lock	unlock	minus2	up
screens	bell	quote	volume _mute	volume	help	arrow _left	arrow _right
arrow _down	organize	book marks	star	maps	reply	attach ment	search
cloud	compose	mail	stop	shuffle	cart	down	arrow _up

Behind the scenes, the SCSS mixin icon-character-for-name maps the iconCls icon identifier to a specific character in the pictos font. This mixin is located at the following location:

touch-2-2-0/resources/themes/stylesheets/sencha-touch/base/mixins/_Class.scss

@function icon-character-for-name($name) {
    // http://pictos.cc/font/

    // Row 1
    @if ($name == "anchor") { @return "a"; }
    @else if ($name == "box") { @return "b"; }
    @else if ($name == "upload") { @return "c"; }
    @else if ($name == "forbidden") { @return "d"; }
    @else if ($name == "lightning") { @return "e"; }
    @else if ($name == "rss") { @return "f"; }
    @else if ($name == "team") { @return "g"; }
//    @else if ($name == "h") { @return "h"; }
    @else if ($name == "info") { @return "i"; }
    @else if ($name == "attachment") { @return "j"; }
    @else if ($name == "heart") { @return "k"; }
    @else if ($name == "list") { @return "l"; }
    @else if ($name == "music") { @return "m"; }
    @else if ($name == "table") { @return "n"; }
    @else if ($name == "folder") { @return "o"; }
    @else if ($name == "pencil") { @return "p"; }
    @else if ($name == "chat2") { @return "q"; }
    @else if ($name == "retweet") { @return "r"; }
    @else if ($name == "search") { @return "s"; }
    @else if ($name == "time") { @return "t"; }
    @else if ($name == "switch") { @return "u"; }
    @else if ($name == "camera") { @return "v"; }
    @else if ($name == "chat") { @return "w"; }
    @else if ($name == "settings2") { @return "x"; }
    @else if ($name == "settings") { @return "y"; }

    // Row 2
    @else if ($name == "attachment2") { @return "A"; }
    @else if ($name == "bird") { @return "B"; }
    @else if ($name == "cloud") { @return "C"; }
    @else if ($name == "delete_black1") { @return "D"; }
    @else if ($name == "eye") { @return "E"; }
    @else if ($name == "file") { @return "F"; }
    @else if ($name == "browser") { @return "G"; }
    @else if ($name == "home") { @return "H"; }
    @else if ($name == "inbox") { @return "I"; }
    @else if ($name == "network") { @return "J"; }
    @else if ($name == "key") { @return "K"; }
//    @else if ($name == "") { @return "L"; }
    @else if ($name == "mail") { @return "M"; }
    @else if ($name == "news") { @return "N"; }
//    @else if ($name == "") { @return "O"; }
    @else if ($name == "photos") { @return "P"; }
    @else if ($name == "power") { @return "Q"; }
    @else if ($name == "action") { @return "R"; }
    @else if ($name == "favorites") { @return "S"; }
    @else if ($name == "plane") { @return "T"; }
    @else if ($name == "user") { @return "U"; }
    @else if ($name == "video") { @return "V"; }
    @else if ($name == "compose") { @return "W"; }
    @else if ($name == "truck") { @return "X"; }
//    @else if ($name == "") { @return "Y"; }
    @else if ($name == "chart") { @return "Z"; }

    // Row 3
    @else if ($name == "expand") { @return "`"; }
    @else if ($name == "refresh") { @return "1"; }
    @else if ($name == "check") { @return "2"; }
    @else if ($name == "check2") { @return "3"; }
    @else if ($name == "play") { @return "4"; }
    @else if ($name == "pause") { @return "5"; }
    @else if ($name == "stop") { @return "6"; }
    @else if ($name == "forward") { @return "7"; }
    @else if ($name == "rewind") { @return "8"; }
    @else if ($name == "play2") { @return "9"; }
    @else if ($name == "refresh2") { @return "0"; }
    @else if ($name == "minus") { @return "-"; }
    @else if ($name == "battery") { @return "="; }
    @else if ($name == "left") { @return "["; }
    @else if ($name == "right") { @return "]"; }
    @else if ($name == "shuffle") { @return ";"; }
    @else if ($name == "wireless") { @return "'"; }
    @else if ($name == "speedometer") { @return ","; }
    @else if ($name == "more") { @return "."; }
    @else if ($name == "print") { @return "/"; }

    // Row 4
    @else if ($name == "download") { @return "~"; }
    @else if ($name == "warning_black") { @return "!"; }
    @else if ($name == "locate") { @return "@"; }
    @else if ($name == "trash") { @return "#"; }
    @else if ($name == "cart") { @return "$"; }
    @else if ($name == "bank") { @return "%"; }
    @else if ($name == "flag") { @return "^"; }
    @else if ($name == "add") { @return "&"; }
    @else if ($name == "delete") { @return "*"; }
    @else if ($name == "lock") { @return "("; }
    @else if ($name == "unlock") { @return ")"; }
    @else if ($name == "minus2") { @return "_"; }
    @else if ($name == "add2") { @return "+"; }
    @else if ($name == "up") { @return "{"; }
    @else if ($name == "down") { @return "}"; }
    @else if ($name == "screens") { @return "|"; }
    @else if ($name == "bell") { @return ":"; }
    @else if ($name == "quote") { @return "\""; }
    @else if ($name == "volume_mute") { @return "<"; }     @else if ($name == "volume") { @return ">"; }
    @else if ($name == "help") { @return "?"; }

    // Backwards compat; icons that are not in the font
    @else if ($name == "arrow_left") { @return "["; }
    @else if ($name == "arrow_right") { @return "]"; }
    @else if ($name == "arrow_up") { @return "{"; }
    @else if ($name == "arrow_down") { @return "}"; }
    @else if ($name == "organize") { @return "I"; }
    @else if ($name == "bookmarks") { @return "I"; }
    @else if ($name == "star") { @return "S"; }
    @else if ($name == "maps") { @return "@"; }
    @else if ($name == "reply") { @return "R"; }

    @else {
        // @debug "#icon: icon with name '#{$name}' not found.";
        @return false;
    }
}

Using the Out of the Box Icons

In prior versions of Sencha Touch you would use the SASS pictos-iconmask() mixin to encode a png file and add appropriate style references into your generated CSS file. In Touch 2.2, however, you’ll need to use the new icon() mixin  that generates a style class referencing the new pictos webfont. The sourcecode for the new icon() mixin is listed below:

/**
 * Includes an icon to be used on Button or Tab components. The $name is the name of the icon, or the character
 * of the font being used.
 *
 *     @include icon('attachment');
 *
 * @param {string} $name The name of the icon to be included.
 * @param {string} $font-family The `font-family` used for this icon. Defaults to the `Pictos` font.
 */
@mixin icon($name, $font-family: false) {
    .x-tab .x-button-icon.#{$name},
    .x-button .x-button-icon.#{$name} {
        $character: icon-character-for-name($name);

        &:before {
            @include absolute-position;
            text-align: center;

            @if $font-family {
                font-family: $font-family;
            }

            @if $character {
                content: "#{$character}";
            } @else {
                content: "#{$name}";
            }
        }
    }
}

Therefore, if you wanted to include a button that used the “network” icon, you would have to add the following to your .SCSS file:

@include icon('network');

Inside of your application’s source files, you would reference the icon name as an iconCls configuration property for a button component or tab as illustrated by the following snippet.

{
 xtype: 'button',
 iconCls: 'network',
 iconAlign: 'top',
 text: 'Net'
}

Note: The iconMask configuration property is no longer required on a button torender the icon.

[CLICK HERE FOR PART 2 OF THIS TWO-PART SERIES]