{"id":1007,"date":"2010-11-04T17:22:33","date_gmt":"2010-11-04T17:22:33","guid":{"rendered":"http:\/\/salientsoft.co.uk\/?p=1007"},"modified":"2010-11-04T19:00:27","modified_gmt":"2010-11-04T19:00:27","slug":"creating-primefaces-icon-buttons-using-the-built-in-theme-icons","status":"publish","type":"post","link":"https:\/\/salientsoft.co.uk\/?p=1007","title":{"rendered":"Creating Primefaces icon buttons using the built in theme icons"},"content":{"rendered":"<p>There is a quite a large collection of useful built in icons, such as those used for the table paginator buttons. It is useful to be able to reuse these in your own buttons:-<\/p>\n<ul>\n<li>It simplifies coding as you don\u2019t need to roll your own icons.<\/li>\n<li>The Unicode character set has quite an extensive library of symbols (see <a title=\"http:\/\/salientsoft.co.uk\/?p=668\" href=\"http:\/\/salientsoft.co.uk\/?p=668\"><strong>here<\/strong><\/a>\u00a0for details of how to use numeric unicode references in HTML to access them), and it is at first\u00a0tempting to use them as they are readily available. The font color used for them will change automatically with your chosen theme, so it seems like you might be home free with minimal effort for buttons with symbols on, by just using them as text labels on a button. However, \u00a0you are at the mercy of the\u00a0theme font stack\/Browser font fallback\/font rendering\u00a0as to how well they are represented in a given font. When I tried some of them out the rendering was very poor in some Primefaces themes, and getting them centrally positioned on buttons of various sizes involved some quirky bits of CSS which were dependent on your chosen font size, particularly if you wanted multiple symbols on a button (e.g. 2 triangles to give a double arrow). I decided this was a blind alley and in the end discovered\u00a0that using the theme icons\u00a0was better and easier.\u00a0<\/li>\n<li>You don\u2019t need to tweak a set of new ones <em>for each theme<\/em>. Themeroller may assist with recolouring them for a theme (haven\u2019t used it yet) but even if it does reusing is still easier than running themeroller to tweak every theme.<\/li>\n<li>It promotes consistency \u2013 your own e.g. arrow buttons can have the same look and feel as e.g. the table paginator ones, so as well as making your life easier you have scored points for better user interface design. When a user sees the same icon used consistently in different places this gives a strong visual cue on how the interface works and what to expect.<\/li>\n<li>Reusing them minimises downloading and caching additional icons.<\/li>\n<\/ul>\n<p>After quite a bit\u00a0a bit of experimentation with both commandButtons and commandLinks, and learning about how JQuery (which Primefaces is based on) works,\u00a0 I came up with the following example page which illustrates how to add a built in theme icon to a commandButton:-<\/p>\n<p>\u00a0<\/p>\n<p>&lt;!DOCTYPE HTML&gt;<br \/>\n&lt;html xmlns=&#8217;<a href=\"http:\/\/www.w3c.org\/1999\/xhtml'\">http:\/\/www.w3c.org\/1999\/xhtml&#8217;<\/a><br \/>\n\u00a0\u00a0 xmlns:f=&#8217;<a href=\"http:\/\/java.sun.com\/jsf\/core'\">http:\/\/java.sun.com\/jsf\/core&#8217;<\/a><br \/>\n\u00a0\u00a0 xmlns:h=&#8217;<a href=\"http:\/\/java.sun.com\/jsf\/html'\">http:\/\/java.sun.com\/jsf\/html&#8217;<\/a><br \/>\n\u00a0\u00a0 xmlns:p=&#8217;<a href=\"http:\/\/primefaces.prime.com.tr\/ui'\">http:\/\/primefaces.prime.com.tr\/ui&#8217;<\/a>&gt;<br \/>\n&lt;f:view contentType=&#8217;text\/html&#8217;&gt;<br \/>\n&lt;h:head&gt;<br \/>\n\u00a0\u00a0\u00a0 &lt;link type=&#8221;text\/css&#8221; rel=&#8221;stylesheet&#8221;<br \/>\n\u00a0\u00a0\u00a0\u00a0 href=&#8221;#{request.contextPath}\/themes\/cupertino\/skin.css&#8221; \/&gt;\u00a0\u00a0\u00a0\u00a0<br \/>\n\u00a0\u00a0\u00a0\u00a0<br \/>\n\u00a0\u00a0\u00a0 &lt;style type=&#8221;text\/css&#8221;&gt;\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 .ui-widget, .ui-widget .ui-widget {<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 font-size: 80% !important;<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 .ss-iconbutton {<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 height:21px;<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 width:30px;<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 .ss-spacer {margin-right:4px;}<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 .ss-iconbutton-icon {<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 background-color: transparent;<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 border:none;<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }<br \/>\n\u00a0\u00a0\u00a0 &lt;\/style&gt;<br \/>\n&lt;\/h:head&gt;<br \/>\n&lt;h:body&gt;<br \/>\n&lt;h:form&gt;<br \/>\n\u00a0\u00a0\u00a0 &lt;p:commandButton styleClass=&#8221;ss-iconbutton ss-spacer&#8221; onclick=&#8221;alert(&#8216;Previous button clicked&#8217;)&#8221;<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0 image=&#8221;ss-iconbutton-icon ui-icon ui-icon-seek-prev&#8221;\/&gt;<br \/>\n\u00a0\u00a0\u00a0 &lt;p:commandButton styleClass=&#8221;ss-iconbutton&#8221; onclick=&#8221;alert(&#8216;Next button clicked&#8217;)&#8221;<br \/>\n\u00a0\u00a0\u00a0\u00a0\u00a0 image=&#8221;ss-iconbutton-icon ui-icon ui-icon-seek-next&#8221;\/&gt;\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0<br \/>\n&lt;\/h:form&gt;\u00a0<br \/>\n&lt;\/h:body&gt;<br \/>\n&lt;\/f:view&gt;<br \/>\n&lt;\/html&gt;<\/p>\n<p>\u00a0<\/p>\n<p>Note the following points about the example:-<\/p>\n<ul>\n<li>The image property of the commandButton accepts a CSS class which loads the icon as a background property. If you inspect one of the command buttons e.g. with Firebug you will note that it applies this class to a &lt;span&gt; tag. The advantage of this is that the icon is defined in theme switched CSS rather than HTML. Note that as is normal when applying CSS classes, multiple classes may be passed as a space separated list as I have done.<\/li>\n<li>The example uses some of the standard jQueryCSS classes from <em>WebContent\/themes\/cupertino\/skin.css<\/em> which is the skinning css present for each theme (in this case, the theme used is <em>cupertino)<\/em>.<\/li>\n<li>Class <em>ui-icon<\/em> defines and loads an icon file for the theme. The chosen file may be modified by the jQuery state classes such as <em>ui-state-default, ui-state-disabled, ui-state hover<\/em> etc. Therefore,the added benefit of using the standard jQuery classes and icon files is that mouse hover automatically causes a switch of icon file to change the colour as determined by the theme, and things like enable\/disable of the button also have the correct effect. In short \u2013 it all just works as it should with no effort if the built-in classes are correctly used.<\/li>\n<li>A fundamental mechanism used by jQuery for states like hover is to use Javascript functions triggered by the hover\/mouseover to dynamically add and remove CSS classes from elements. For example, class <em>ui-state-hover<\/em> is added and removed on hover. this may be seen within Firebug when you hover over the button with the mouse. Note that therefore jQuery does not only use CSS Pseudo-classes such as <em>:hover, :active<\/em> to support this as one might expect. Examples of the latter will be found in <em>skin.css<\/em>\u00a0 but they do not give the whole picture about what is going on internally. This is presumably done for reasons of browser compatibility as CSS pseudo classes do not work consistently across different element types and browsers (IE is especially limited in this regard).<\/li>\n<li>Primefaces\/jQuery stores multiple icons in a single icon file, and uses the css <em>background-position <\/em>property with appropriate X and Y pixel coordinates in the file to pick out the desired icon. If an icon file is examined with Windows you will see all the icons store in the file in a matrix fashion. A set of classes is defined in <em>skin.css<\/em> , one for each icon, to encapsulate the position of that icon within the icon file. In the above example, <em>ui-icon-seek-prev<\/em> and <em>ui-icon-seek-next<\/em> have been used to select the next and previous icons used on the dataTable paginator.<\/li>\n<li>By default, the icon in a commandButton is given a border and a background colour, which in this case we do not want. These are removed by class <em>ss-iconbutton-icon<\/em> above which is also passed as one of the classes to the <em>image<\/em> attribute of the commandButton.<\/li>\n<li>Whilst we are to an extent going \u201cunder the hood\u201d and using mechanisms and CSS classes which are not part of the documented Primefaces interface, they are a standard part of jQuery upon which Primefaces is based. When extending a user interface a fashion similar to the above, it is highly recommended to gain familiarity with the workings and operation of jQuery, as this can allow additional functionality to be harmonised with the existing functionality. This will typically make adding functionality easier, promote consistency with the existing feature set, and as in this case can give a number of side benefits for no extra work. Of course, using features that are not part of a formally documented Primefaces interface may mean that your code needs to change with later releases, but in this case, as these are jQuery features, it definitely feels the right way to go.<\/li>\n<\/ul>\n<p>\u00a0<\/p>\n<p>The jQuery UI web site, which contains full documentation, tutorials and demos,\u00a0 may be found <a href=\"http:\/\/jqueryui.com\/\"><strong>here<\/strong><\/a>. In my opinion it is certainly worth delving into further to augment your understanding of Primefaces, especially when you want to extend or reuse features and components in ways like the above example.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>There is a quite a large collection of useful built in icons, such as those used for the table paginator buttons. It is useful to be able to reuse these in your own buttons:- It simplifies coding as you don\u2019t need to roll your own icons. The Unicode character set has quite an extensive library [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[22],"tags":[184,112,16,15],"_links":{"self":[{"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/1007"}],"collection":[{"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=1007"}],"version-history":[{"count":11,"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/1007\/revisions"}],"predecessor-version":[{"id":1008,"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=\/wp\/v2\/posts\/1007\/revisions\/1008"}],"wp:attachment":[{"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=1007"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=1007"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/salientsoft.co.uk\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=1007"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}