Monday, 17 November 2014

Select2 Placeholder Combo Box

Following the XPages And More Demo Database I got some questions regarding a placeholder in Select2 for a single value field.
In this blog post I describe how to add a placeholder to a Combo Box.
The placeholder can be declared via a data-placeholder attribute attached to the select, or via the placeholder configuration element.
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.
Optionally, a clear button (visible once a selection is made) is available to reset the select box back to the placeholder value.

A. Declaration via a data-placeholder attribute

<xp:scriptBlock id="scriptBlock2">
<xp:this.value><![CDATA[
  $(document).ready(
    function() {
      x$( "#{id:comboBox1}" ).select2();
               }
           );
  ]]></xp:this.value>
</xp:scriptBlock>

<div class="panel panel-default">
<div class="panel-body">
Select2 - Combo Box
<xp:comboBox id="comboBox1"
value="#{document1.Categories}">
<xp:this.attrs>
<xp:attr name="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>
</div>
<div class="panel-footer">Combo Box - Single Value</div>
</div>

Result


B. Declaration via placeholder configuration element

<xp:scriptBlock id="scriptBlock2">
<xp:this.value><![CDATA[
  $(document).ready(
    function() {
      x$( "#{id:comboBox1}" ).select2({
      placeholder: "Select a category",
      allowClear: true
      });
               }
           );
  ]]></xp:this.value>
</xp:scriptBlock>

<div class="panel panel-default">
<div class="panel-body">
Select2 - Combo Box
<xp:comboBox id="comboBox1"
value="#{document1.Categories}">
<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>
</div>
<div class="panel-footer">Combo Box - Single Value</div>
</div>

The required empty tag can be added through an empty array 'value' as a first selection.
var arr = new Array("")
A possible problem can be that there is no empty value present in the selection list itself.
If a value has been selected it can not be put back to an empty value.
To deselect the selected value an 'allow clear' element can be added to the comboBox.
Note that this option only works with non-multi-value based selects because multi-value selects always provide such a button for every selected option. 

Result



Sample Code Custom Control

<?xml version="1.0" encoding="UTF-8"?>
<xp:view xmlns:xp="http://www.ibm.com/xsp/core">
<xp:this.data>
<xp:dominoDocument var="document1" formName="Contact"></xp:dominoDocument>
</xp:this.data>
<xp:this.resources>
<xp:script
src="/.ibmxspres/domino/xsp/.ibmxspres/.extlib/bootstrap/select2/select2.min.js"
clientSide="true">
</xp:script>
<xp:styleSheet
href="/.ibmxspres/domino/xsp/.ibmxspres/.extlib/bootstrap/select2/select2.css">
</xp:styleSheet>
<xp:styleSheet
href="/.ibmxspres/domino/xsp/.ibmxspres/.extlib/bootstrap/select2/select2-bootstrap.css">
</xp:styleSheet>
<xp:script src="/JQueryXSnippet.js" clientSide="true"></xp:script>
</xp:this.resources>
<xp:scriptBlock id="scriptBlock2">
<xp:this.value><![CDATA[
  $(document).ready(
    function() { 
      x$( "#{id:comboBox1}" ).select2({
      placeholder: "Select a category",
      allowClear: true
      });
               }
           );
  ]]></xp:this.value>
</xp:scriptBlock>
<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
  $(document).ready(
    function() { 
      x$( "#{id:listBox1}" ).select2({
      placeholder: "Select a software category"      
      });
               }
           );
  ]]></xp:this.value>
</xp:scriptBlock>
<xp:panel>
<div class="page-header">
<h1>
Select2
<xp:span style="color:rgb(255,255,255)">.</xp:span>
<small>Combo Box / List Box</small>
</h1>
</div>
<div class="panel panel-default">
<div class="panel-body">
Select2 - Combo Box
<xp:comboBox id="comboBox1"
value="#{document1.Categories}">
<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>
</div>
<div class="panel-footer">Combo Box - Single Value</div>
</div>
<div class="panel panel-default">
<div class="panel-body">
Select2 - List Box
<xp:listBox id="listBox1"
value="#{document1.Categories}" multiple="true">
<xp:selectItems>
<xp:this.value><![CDATA[#{javascript:@Text("");
@DbLookup("", "byKeyWord", "Software", 2);}]]></xp:this.value>
</xp:selectItems>
</xp:listBox>
</div>
<div class="panel-footer">List Box - Multiple Values</div>
</div>
</xp:panel>
</xp:view>

In one of the next blog post I will also be discussing some other features of Select2.

No comments:

Post a Comment