Archive | Font Awesome RSS for this section

Adding Event Handlers to Font Awesome Icons in XPages

In the previous two posts, I showed how to implement Font Awesome in XPages and two options for adding icons to your page. In this post, I’ll show how you can add event handlers so that you can trigger an action when a user clicks on an icon.

Add a Client-Side Event Handler with Dojo or jQuery

If you want to trigger a client-side event, you can use Dojo or jQuery to add an event handler to the icon after the page loads.

For example, if you have this bullseye icon…

<i id="myIcon" class="fa fa-bullseye"></i>

…and you want to add an event handler to display an alert when the user clicks on it, you can use this Dojo code:

dojo.on(dojo.byId('myIcon'), 'click', function() {
  console.log('clicked icon');

Here’s more information about attaching event handlers (you may need to include the dojo.on module) and event delegation in Dojo.

Add Icon Within an XPages Control

Another option for making icons clickable is to put them inside of another XPages control that has an event handler. For example, you can create a link control, button control, span control, etc and put a font awesome icon inside of it.

Here’s an example of displaying an icon within an XPages button. It displays a message in the console with client-side JavaScript and also triggers a server-side partial refresh of a panel.

To add the icon, you have to switch to the source view and add it directly.

<xp:button value=" Click Me" id="button1">
  <i id="myIconButton" class="fa fa-bullseye"></i>
  <xp:eventHandler event="onclick" submit="true" refreshMode="partial" refreshId="myPanel">
    <xp:this.script><![CDATA[console.log('clicked icon button');]]></xp:this.script>


Notice that it turns the icon blue by default. It does the same when inside of a link, because the browser makes link text blue by default (and these icons are implemented as a font, so therefore, the browser is correctly treating them as text).

Here’s an example of displaying an icon (with the same effect) within an XPages link:

<xp:link escape="true" text="" id="link1">
  <i id="myIconLink" class="fa fa-bullseye"></i>
  <xp:eventHandler event="onclick" submit="true" refreshMode="partial" refreshId="myPanel">
    <xp:this.script><![CDATA[console.log('clicked icon link');]]></xp:this.script>

Add an XPages Event Handler Directly to an Icon

In my last post, I mentioned that I prefer to use computed text fields with the tagName property set, because you can set a rendered formula and compute the class names as needed. Another advantage to that approach is that you can attach an XPages event handler, so you can add server side code, partial refreshes, onComplete callbacks, etc.

Now, that comes with a significant caveat, because Computed Field controls do not provide the ability for you to add events in the “pretty panels”.

However, if you add an event handler to another control, you can go into the Source and move that event handler into the Computed Field (xp:text) control and it will fire.

In this example, I created a Computed Field to display an icon and I copied the event handler from the previous example into it.

<xp:text escape="true" id="computedField2" tagName="i"
  styleClass="fa fa-bullseye fa-3x">
  <xp:eventHandler event="onclick" submit="true" refreshMode="partial" refreshId="myPanel">
    <xp:this.script><![CDATA[console.log('clicked icon link');]]></xp:this.script>

If you go into the source and click on the xp:eventHandler tag, you’ll get a property panel where you can bring up the client or server JavaScript editor or add other callbacks.


Now, I have a clickable icon with no extraneous tags around it.

It is certainly simpler to wrap an xp:span tag around an icon to get the same effect, but if you need the clickable icon without additional tags, this provides a way to do it.

Tip – Changing the Cursor when Adding an Event Handler to an Icon

If you’re going to make standalone icons clickable, the text cursor may be confusing (at least in IE and Firefox). (Remember — it’s actually a font, so this makes sense).

If you want to change the cursor when hovering over an icon, you can add this CSS:

i.fa {

Of course, this will affect the cursor over all font awesome icons in your application. You can target the CSS as needed to only modify it for icons that are clickable.

Using Font Awesome Icons in XPages

In the last post, I showed how to implement Font Awesome in your XPages application. In this post, I’ll show two ways to display Font Awesome icons on your pages.

Option 1 – Pass-through HTML

Font Awesome icons are not XPages controls, so you can add them to your page directly with pass-thru HTML, an <i> tag. The Font Awesome CSS looks for this tag and replaces it with the correct icon, based on the class name that you provide.

Icon tags generally take this form:

<i class="fa fa-XXX"></i>

Here’s an example of the crosshairs icon:

<i class="fa fa-crosshairs"></i>


This page contains all icons and their corresponding class names.

Option 2 – Computed Text

Another option you have for adding an icon within XPages is a computed text control.

Since it’s an xp control, you can do more with it, such as conditionally rendering the icon or conditionally computing the class name to change which icon is displayed.

One way to use a computed text control would be to set the Content type property to HTML (which sets escape="false" in the source) and use JavaScript to compute the HTML output.

Here’s an example that will generate the same icon shown above:

<xp:text escape="false" id="computedField1">
    <![CDATA[#{javascript:return '<i class="fa fa-crosshairs"></i>';}]]>

This adds the icon, but also puts a <span> tag around it (as the Computed Field control always does by default).

Here’s the HTML output:

<span id="view:_id1:computedField1" class="xspTextComputedField">
  <i class="fa fa-crosshairs"></i>

A better method is to use the tagName property of the Computed Field control (as I described in this post).

When you do this, you don’t have to compute any value for the control — just set the tagName to i and set the Class to define the icon that you want. You also don’t have to set the Content type to HTML.

Here’s what it looks like in the XPages source:

<xp:text escape="true" id="computedField2"
  styleClass="fa fa-crosshairs" tagName="i">

This generates only the HTML that you really want for the icon, without the extraneous <span> tag mixed in. Most of the time it’s probably not a big deal, but it has the potential affect your UI.

<i class="fa fa-crosshairs"></i>

More on Using Font Awesome

You can change the size, orientation, and color of Font Awesome icons (and much more!). You can even stack multiple icons (but not in older IE) to create unique images.

Check out this post by Russ Maher or the Font Awesome site for more information.

Up Next

In the next post, I’ll show how to add an event handler to a Font Awesome icon in XPages.

Implementing Font Awesome 4.0.3 in XPages

Font Awesome is a great library of icons (implemented as a font) that you can use in your applications. Russ Maher wrote a great post and provided a sample application to make it very easy to get up and running with Font Awesome quickly. If you want to use version 3.2.1, stop reading this post and follow Russ’ instructions, because that’s the fastest way to go. However, Font Awesome is now up to version 4.0.3 and if you want to use that (or any future version), you can follow the process outlined here — including an XPages-specific gotcha.

Adding Font Awesome to Your Application

1) Download Font Awesome

2) Extract the files somewhere on your hard drive

3) Add the files to your application

Open in Package Explorer or Navigator in DDE. Drag the font awesome folder from the file system into the WebContent folder in your application.


4) Include Font Awesome CSS

You need one of two stylesheets: font-awesome.css or font-awesome.min.css.

You can add them directly as a page resource (but you’ll have to type in a longer file path, since they’re not Style Sheet design elements — see Russ’ sample database for an example) or include them application-wide in a Theme.

  <styleSheet href="font-awesome-4.0.3/css/font-awesome.css"></styleSheet>

When going to production, use font-awesome.min.css instead of font-awesome.css.

If you’re using a version other than 4.0.3, update the file path accordingly to match the folder name under WebContent.

Common Error

To try it out, I added an icon tag to an XPage:

<i class="fa fa-users"></i>

In Firefox and Chrome, it doesn’t work by default. (Surprisingly, it does seem to work at this point in IE9+. There are special stylesheets to use font-awesome in IE8 and IE7, but that’s outside of the scope of this post.)

Here’s what it looks like in Chrome, along with the errors in the console (click the image to see it larger):


Here’s what it looks like in Firefox, along with the errors in the console (click the image to see it larger):


They’re both showing “Bad Request” errors. This has to do with URL parameters included for the font references in the Font Awesome stylesheets.

Fixing the Links

The ?v=4.0.3 appended to each font reference is what’s causing the problem. The server does not seem to like those parameters.

To allow it to work within XPages, open up the Font Awesome stylesheet (via Package Explorer or Navigator) and update the font links. You can find the lines to fix at the top of the stylesheets, in the @font-face { } rules.

@font-face {
  font-family: 'FontAwesome';
  src: url('../fonts/fontawesome-webfont.eot?v=4.0.3');
  src: url('../fonts/fontawesome-webfont.eot?#iefix&v=4.0.3') format('embedded-opentype'), url('../fonts/fontawesome-webfont.woff?v=4.0.3') format('woff'), url('../fonts/fontawesome-webfont.ttf?v=4.0.3') format('truetype'), url('../fonts/fontawesome-webfont.svg?v=4.0.3#fontawesomeregular') format('svg');

All you have to do is remove the ?v=4.0.3 from each url to fix the problem.

In the links that include anchor links (such as: ?#iefix&v=4.0.3), just remove the 4.0.3 part and you can leave the anchor link.

@font-face {
  font-family: 'FontAwesome';
  src: url('../fonts/fontawesome-webfont.eot');
  src: url('../fonts/fontawesome-webfont.eot?#iefix') format('embedded-opentype'), url('../fonts/fontawesome-webfont.woff') format('woff'), url('../fonts/fontawesome-webfont.ttf') format('truetype'), url('../fonts/fontawesome-webfont.svg#fontawesomeregular') format('svg');

(Make the change in both font-awesome.css and font-awesome.min.css.)

Now my sample page shows the “Users” icon.