andyMatthews.net
Creating and using custom icons in jQuery Mobile
So you've read Introduction to jQuery Mobile and you've built your first application. You're happy with it, but you want some different icons. The icon set that comes with jQuery Mobile has some nice ones in it, but they're not enough for people who really want to spice up their application. This blog post will show you how to create and implement custom icons. In addition I'll show you how to add high res icon support for iPhone 4's Retina display and newer high resolution devices.
jQuery Mobile uses white PNG 8 bit icons sized at 18x18 pixels. They specify 8bit PNG files, but any image is acceptable. However, if you decide to mix and match packaged icons with custom icons, it's best to stick with white icons for consistency. If you decide to replace all icons, then use GIF or PNG, anything that will give you transparency.
Fire up Photoshop, or the image editing app of your choice, and create a new file at 18x18.
Draw your own icon or find an existing icon from any number of icon sites. Preference should be given to using a vector file for your icon as we'll be increasing the size in a few moments. When you're ready to save your icon select File > Save for Web & Devices and make your settings look like those in the image to the right. Call the image settings.png.
After you've exported your image at 18x18, you'll want to size the canvas upwards, to 36x36 pixels. Select Image > Image Size (or Alt + Ctrl + I). Touch up your icon accordingly, then save for web as before, but this time name the file settings@2x.png. The name of the high-res file doesn't mean anything to jQuery Mobile, but in iPhone development, the @2x indicates a file that is exactly twice the pixel dimensions of a file without the @2x.
If you recall, jQuery recommends hot-linking to the JavaScript and CSS files used by jQuery Mobile as hosted by jQuery themselves. That means we can't alter those files. So once you've got your images saved, we'll need to create a new CSS file that will contain our custom changes. Call it whatever you like, save it wherever you like, but it'll remain empty for a few minutes.
For simplicity's sake, we're going to create a simple button that will use our icon. The code for that button will look like this
- data-role = tells the standard link to behave, and look, like a button.
- data-theme = tells the button which jQuery theme to implement.
- data-iconpos = tells the icon where to appear. Default is left; options are right, top, bottom, or notext (which results in a round button with the selected icon at the center) .
- data-icon = selects the icon. To use built in jQuery icons, simply use a single word like home, add, forward, back, etc. To implement a custom icon use a string such as "twitter-bird" or "myapp-settings". jQuery Mobile will generate a CSS class declaration of ui-icon-myapp-settings that we'll be using to hook into.
Open up the custom CSS file that you created moments ago, and add this class declaration
Save all your files and view the project in your browser. At this point your button should now be displaying your custom icon, congratulations! If it's not, a few things to check...
- Is the file in the right place, or being linked to correctly?
- Did you upload, and correctly link to, the custom CSS file. Remember that the custom file needs to appear after the standard jQuery Mobile file in your code.
- If it's still not showing up, clear your cache. jQuery Mobile hangs on to your files like a miser holds on to his last dime.
Now that your icon is in place let's add in the code needed to implement a high-res icon. jQuery Mobile uses something called CSS3 media queries to detect whether your device is capable of the goodness. We can also use a media query to see if your device is capable of pixel doubling. It looks like this
Broken down that says any screen device capable of double pixel density gets the stuff inside. So now let's take a look at our custiom CSS delcaration now.
Notice that the only differences in this declaration are the different filename, and we're adding a background-size attribute. This forces the 36x36 icon to be sized to the 18x18 size we need.
Hope this article helped you out, and encourages you to try out jQuery Mobile; currently in it's Alpha 3 release. Hit up the demo link to see this code in place. Click the button labeled Custom Icons. If you don't have an iPhone 4 to test with, bug your Apple nerd friend to look at your project once you're done.