Friday, 30 September 2016

Using Chosen a jQuery Plugin for more User-Friendly Select Boxes in XPages

As everyone knows I'm still a "cheer leader" when it comes to IBM Notes Domino. Although I sometimes have my doubts about the future of XPages given the current IBM Roadmaps hereby nevertheless a blog post on XPages.
Chosen is a jQuery plugin that makes long, unwieldy select boxes much more user-friendly. Chosen is an excellent alternative to Select2. Chosen has some great options as Hide Search on Single Select, Default Text Support, Limit Select Options in Multi-Select and Allow Deselect on Single Selects. It is also very simple to integrate into any XPages Application.
In order to use Chosen the JavaScript and CSS file(s) need to be included on the XPage / Custom Control. The latest version can be downloaded from GitHub: Chosen 1.6.2.

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 and CSS files, chosen.jquery.js and chosen.css, must be included on the XPage or Custom Control. In this example I add the files to an XPage.

<script type="text/javascript" src="chosen/chosen.jquery.js"></script>
<link rel="stylesheet" href="chosen/chosen.css" />

Note: Not shown in the picture above is the required file chosen-sprite.png. This file should also be added to the WebContent Folder in the Package Explorer.

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 / List Box. In the example below I used some extra options.

<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:listBox1}" ).chosen({
disable_search_threshold: 10,
allow_single_deselect: true ,
max_selected_options: 2,
width:"100% !important;"
});
}
);
]]></xp:this.value>
</xp:scriptBlock>

Remark: When a placeholder is used for a non-multi-value select box such as a Combo Box, an empty tag is required as a first option. One possibility is to generate computed items, including an empty tag, as values for the Combo Box.

var arr = new Array("");
var res = @DbLookup("", "byKeyWord", "Category", 2);
var list = arr.concat(res);
return list;

Responsive design - Percent width
Chosen's width can be set to a percentage of its parent to support responsive design.
The best way to ensure that Chosen is using a percent based width is to add the width declaration into the scriptBlock of the listBox and comboBox, width:"100% !important;".

Basic Setup Combo Box in XPages
For using a place holder it is necessary to add the Attribute data-placeholder in the Properties of the Combo Box.
<div class="col-md-7">
<xp:comboBox id="comboBox1" >
<xp:this.attrs>
<xp:attr name="data-placeholder" value="Select a category...."></xp:attr>
</xp:this.attrs>
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript:var arr = new Array("");
var res = @DbLookup("", "byKeyWord", "Category", 2);
var list = arr.concat(res);
return list;}]]></xp:this.value>
</xp:selectItems>
</xp:comboBox>


Basic Setup List Box (multi value)
Chosen also supports multi-value select boxes.

<xp:listBox id="listBox1" multiple="true">
<xp:this.attrs>
<xp:attr name="data-placeholder" value="Select a category..."></xp:attr>
</xp:this.attrs>
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript: @DbLookup("", "byKeyWord", "Software", 2);}]]></xp:this.value>
</xp:selectItems>
</xp:listBox>
</div>


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>
<script type="text/javascript" src="chosen/chosen.jquery.js"></script>
<link rel="stylesheet" href="chosen/chosen.css" />
<xp:scriptBlock id="scriptBlock2">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:comboBox1}" ).chosen({
disable_search_threshold: 10,
allow_single_deselect: true,
width: "100% !important;"
});
}
);
]]></xp:this.value>
</xp:scriptBlock>
<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:listBox1}" ).chosen({
allow_single_deselect: true ,
max_selected_options: 2,
width:"100% !important;"
});
}
);
]]></xp:this.value>
</xp:scriptBlock>
<xc:ccLayout>
<xp:this.facets>
<xp:panel xp:key="facetMiddle">
<div class="col-md-7">
<h3>Chosen</h3>
</div>
<div class="col-md-7">
<xp:comboBox id="comboBox1">
<xp:this.attrs>
<xp:attr name="data-placeholder" value="Select a category....">
</xp:attr>
<xp:attr name="no_results_text" value="No results found!">
</xp:attr>
</xp:this.attrs>
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript:var arr = new Array("");
var res = @DbLookup("", "byKeyWord", "Category", 2);
var list = arr.concat(res);
return list;}]]></xp:this.value>
</xp:selectItems>
</xp:comboBox>
<xp:br></xp:br>
<xp:br></xp:br>
<xp:listBox id="listBox1" multiple="true">
<xp:this.attrs>
<xp:attr name="data-placeholder" value="Select a category...">
</xp:attr>
</xp:this.attrs>
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript: @DbLookup("", "byKeyWord", "Software", 2);}]]></xp:this.value>
</xp:selectItems>
</xp:listBox>
</div>
</xp:panel>
</xp:this.facets>
</xc:ccLayout>
</xp:view>

For more information about Chosen : Documentation Chosen

No comments:

Post a Comment