Monday, 10 October 2016

Using SelectBoxIt a A jQuery Plugin that Enhances an HTML Select Box into a Single Option Dropdown List in XPages

In previous blog posts I wrote about Select Boxes in XPages using Select2 and Chosen. A third option that I want to mention is SelectBoxIt. Although the jQuery Plugin sadly is no longer actively maintained I think it still belongs in the overview for Select Boxes in XPages.
SelectBoxIt is a A jQuery plugin that progressively enhances an HTML Select Box into a single option dropdown list. The dropdown list can be optionally styled with Twitter Bootstrap, jQueryUI ThemeRoller, or jQuery Mobile, optionally animated with jQueryUI show/hide effects, and works on Desktop, Tablet, and Mobile browsers.

Features
  • Styleable with Twitter Bootstrap, jQueryUI Themeroller, and jQuery Mobile
  • Supports Desktop, Tablet, and Mobile browsers
  • Supports all jQuery and jQueryUI show/hide effects (optional)
  • Supports all Twitter Bootstrap (Glyphicons) and jQueryUI/custom icons
  • Includes ARIA (Accessible Rich Internet Applications) support
  • Full keyboard search and navigation support
  • An event API triggered on the original select box element that calls the plugin
  • A method API providing methods to interact with the dropdown list (i.e. Search, Open, Disable, Set Options)
  • Passes jsHint with no errors
  • Selected, Disabled, and Optgroup Support
  • Easily extendable to allow developers to create new widgets

SelectBoxIt allows you to replace ugly and hard to use Select Boxes with gorgeous and feature rich drop downs. Twitter Bootstrap, jQueryUI, and jQuery Mobile themes are supported right out of the box. If you don't want to use these a library theme, then you can use the SelectBoxIt default theme, which closely resembles the Twitter Bootstrap theme.
To use SelectBoxIt, you do not have to rewrite any of your existing form validation logic or event handling. SelectBoxIt just works. SelectBoxIt also provides first-class support for mobile, tablet, and desktop browsers, triggering the native "wheel" interface for mobile and tablet devices.

Requirements
  • jQuery 1.8.3+ (It is always recommended to use the latest version of jQuery)
  • jQueryUI Widget Factory 1.10.0+ (It is always recommended to use the latest version of the jQueryUI Widget Factory)
In order to use SelectBoxIt the JavaScript, jQuery-UI and CSS file(s) need to be included on the XPage / Custom Control. The latest version can be downloaded from GitHub: SelectBoxIt.

Adding the JS and CSS files
The JavaScript and CSS files must be added to the WebContent Folder in the Package Explorer.
In the example below a Folder Chosen has been added in the WebContent Folder.


Next the JavaScript, jQuery-UI and CSS files, jquery.selectBoxIt.js, jquery.selectBoxIt.css and jquery-ui.js must be included on the XPage or Custom Control. In this example I add the files to an XPage.

<link type="text/css" rel="stylesheet" href="selectBoxit/css/jquery.selectBoxIt.css" />
<script src="selectBoxIt/jquery-ui.js"></script>
<script src="selectBoxIt/js/jquery.selectBoxIt.js"></script>

Adding the x$ jQuery selector for XPages
Furthermore I use the the great XSnippet by Mark Roden, x$ jQuery selector for XPages, to initialize the plugin and include it on the XPage. The XSnippet can be added to the Script Libraries. In this example the name of the Script Library is JQueryXSnippet.js.

<xp:this.resources>
<xp:script src="/JQueryXSnippet.js" clientSide="true"></xp:script>
</xp:this.resources>

The script itself can be made up as follows. The name of the id in the script must correspond with the id of the Combo Box. In the example below I used some extra options.

<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:comboBox1}" ).selectBoxIt({
// Uses the jQuery theme for the drop down
theme: "jquery",  
// Uses the jQuery 'fadeIn' effect when opening the drop down
showEffect: "fadeIn",
// Sets the jQuery 'fadeIn' effect speed to 400 milleseconds
showEffectSpeed: 400,
// Uses the jQuery 'fadeOut' effect when closing the drop down
hideEffect: "fadeOut",
// Sets the jQuery 'fadeOut' effect speed to 400 milleseconds
hideEffectSpeed: 400,  
// Sets default text to appear for the drop down
defaultText: "Select a Category"
});
});
]]></xp:this.value>
</xp:scriptBlock>

AMD Loader Fix
Finally, the jQuery file jquery-ui.js needs to be adjusted. Reason: newer jQuery plugins try to use its AMD loader, but that doesn't play well with the Dojo implementation in XPages. The source code of the library can be adjusted in a very simple way with just a slight modification.

1. Go to the WebContent Folder and select the JavaScript file select2.js
2. Select Open With - Client/Server JS Editor
3. Removed in the second line define.amd and replace it with false
4. Save the JavaScript file select2.js

Note: See also other solutions for the AMD loader fix described in the blog post Bootstrap Plugins in XPages Part VI - jQuery and JavaScript AMD (Asynchronous Module Definition) Fixes.

Basic Setup Combo Box in XPages
There is no empty tag required as a first option for the display of an placeholder.
<xp:comboBox id="comboBox1">
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript:var lookup = @DbLookup("", "byKeyWord", "Category", 2);
return lookup;
}]]></xp:this.value>
</xp:selectItems>
</xp:comboBox>

The result is a Bootstrap look and feel Select Box in XPages.


Code XPage
<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core"
xmlns:xc="http://www.ibm.com/xsp/custom">
<xp:this.resources>
<xp:script src="/JQueryXSnippet.js" clientSide="true"></xp:script>
</xp:this.resources>
<link type="text/css" rel="stylesheet" href="selectBoxit/css/jquery.selectBoxIt.css" />
<script src="selectBoxIt/jquery-ui.js"></script>
<script src="selectBoxIt/js/jquery.selectBoxIt.js"></script>
<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:comboBox1}" ).selectBoxIt({
// Uses the jQuery theme for the drop down
theme: "jquery",  
// Uses the jQuery 'fadeIn' effect when opening the drop down
showEffect: "fadeIn",
// Sets the jQuery 'fadeIn' effect speed to 400 milleseconds
showEffectSpeed: 400,
// Uses the jQuery 'fadeOut' effect when closing the drop down
hideEffect: "fadeOut",
// Sets the jQuery 'fadeOut' effect speed to 400 milleseconds
hideEffectSpeed: 400,  
// Sets default text to appear for the drop down
defaultText: "Select a Category"
});
});
]]></xp:this.value>
</xp:scriptBlock>
<xc:ccLayout><xp:this.facets>
<xp:panel xp:key="facetMiddle">
<div class="col-md-7">
<h3>SelectBoxIt</h3>
<h4>A jQuery plugin that progressively enhances an HTML Select Box into a single option dropdown list. The dropdown list can be optionally styled with Twitter Bootstrap, jQueryUI ThemeRoller, or jQuery Mobile, optionally animated with jQueryUI show/hide effects, and works on Desktop, Tablet, and Mobile browsers.</h4>
</div>
<div class="col-md-7">
<xp:comboBox id="comboBox1">
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript:var lookup = @DbColumn("C1257C43:002CD36F", "($ChooseResourceNotes)", 0);
return lookup;
}]]></xp:this.value>
</xp:selectItems>
</xp:comboBox>
</div>
</xp:panel>
</xp:this.facets>
</xc:ccLayout>
</xp:view>

For more information: Documentation SelectBoxIt

No comments:

Post a Comment