Tuesday, 17 May 2016

Bootstrap Plugins in XPages Part VIII - Bootstrap Maxlength A Visual Feedback Indicator For The Maxlength Attribute

Bootstrap Maxlength is a visual feedback indicator for the maxlength attribute.
The Bootstrap Maxlength plugin integrates by default with Twitter bootstrap using badges to display the maximum lenght of the field where the user is inserting text. Uses the HTML5 attribute "maxlength" to work. The indicator badge shows up on focusing on the element, and disappears when the focus is lost.

Bootstrap Plugins in XPages
Part I : Bootstrap-select - A jQuery plugin that utilizes Bootstrap's dropdown.js
Part II : Bootstrap FileStyle - Customization of input file for Bootstrap
Part III : Dialog Boxes using Bootbox
Part IV : Awesome Bootstrap Checkbox
Part V : jQuery and JavaScript AMD (Asynchronous Module Definition) Fixes
Part VI : jQuery and JavaScript AMD (Asynchronous Module Definition) Fixes (2)
Part VII : MagicSuggest A Multiple Selection Combobox

Below a description of the setup of the Bootstrap Maxlength plugin. Bootstrap Maxlength can be downloaded from GitHub.

A. Configurable options
  • alwaysShow: if true the threshold will be ignored and the remaining length indication will be always showing up while typing or on focus on the input. Default: false.
  • threshold: this is a number indicating how many chars are left to start displaying the indications. Default: 10.
  • warningClass: it's the class of the element with the indicator. By default is the bootstrap "label label-success" but can be changed to anything you'd like.
  • limitReachedClass: it's the class the element gets when the limit is reached. Default is "label label-important label-danger" (to support Bootstrap 2 and 3).
  • separator: represents the separator between the number of typed chars and total number of available chars. Default is "/".
  • preText: is a string of text that can be outputted in front of the indicator. preText is empty by default.
  • postText: is a string outputted after the indicator. postText is empty by default.
  • showMaxLength: if false, will display just the number of typed characters, e.g. will not display the max length. Default: true.
  • showCharsTyped: if false, will display just the remaining length, e.g. will display remaining lenght instead of number of typed characters. Default: true.
  • placement: is a string, define where to output the counter. Possible values are: bottom ( default option ), left, top, right, bottom-right, top-right, top-left, bottom-left and centered-right.
  • appendToParent: appends the maxlength indicator badge to the parent of the input rather than to the body.
  • message: an alternative way to provide the message text, i.e. 'You have typed %charsTyped% chars, %charsRemaining% of %charsTotal% remaining'. %charsTyped%, %charsRemaining% and %charsTotal% will be replaced by the actual values. This overrides the options separator, preText, postText and showMaxLength. Alternatively you may supply a function that the current text and max length and returns the string to be displayed. For example, function(currentText, maxLength) { return '' + Math.ceil(currentText.length / 160) + ' SMS Message(s)'; }
  • utf8: if true the input will count using utf8 bytesize/encoding. For example: the '£' character is counted as two characters.
  • showOnReady: shows the badge as soon as it is added to the page, similar to alwaysShow
  • twoCharLinebreak: count linebreak as 2 characters to match IE/Chrome textarea validation.
  • customMaxAttribute: String -- allows a custom attribute to display indicator without triggering native maxlength behaviour. Ignored if value greater than a native maxlength attribute. 'overmax' class gets added when exceeded to allow user to implement form validation.
  • allowOverMax: Will allow the input to be over the customMaxLength. Useful in soft max situations.
  • placement: is a string, object, or function, to define where to output the counter. Possible string values are: bottom ( default option ), left, top, right, bottom-right, top-right, top-left, bottom-left and centered-right. Custom placements can be passed as an object, with keys top, right, bottom, left, and position. These are passed to $.fn.css. A custom function may also be passed. This method is invoked with the {$element} Current Input, the {$element} MaxLength Indicator, and the Current Input's Position {bottom height left right top width}.

B. Adding the JS file to the WebContent Folder and XPage
First the JavaScript file bootstrap-maxlength.js must be added to the WebContent Folder in the Package Explorer. Also the JavaScript file bootstrap-maxlength.js must be included on the XPage or Custom Control. In this example I add the files to an XPage.

<script type="text/javascript" src="bml/bootstrap-maxlength.js"></script>

C. Adding the x$ jQuery selector for XPages
Furthermore I use in this example the the great XSnippet by Mark Roden, x$ jQuery selector for XPages, to initialize the plugin and include it on the Custom Control / XPage. The XSnippet can be added to the Script Libraries.

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

The name of the id in the script must correspond with the id of the Edit Box or Multiline Edit Box (textarea field).

D. Setup Edit Box
In order to make the plug-in work properly an attribute maxlength needs to be added to the Edit Box.

<xp:this.attrs>
<xp:attr name="maxlength" value="25"></xp:attr>
</xp:this.attrs>.

The script itself can be made up as follows.

<xp:scriptBlock id="scriptBlock2">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:inputText1}" ).maxlength({
alwaysShow: true,
threshold: 10,
warningClass: "label label-info",
limitReachedClass: "label label-warning",
placement: 'top',
preText: 'used ',
separator: ' of ',
postText: ' chars.'
});
}
);
]]></xp:this.value>
</xp:scriptBlock>

E. Setup Multiline Edit Box
In order to make the plug-in work properly an attribute maxlength needs to be added to the Multiline Edit Box.The script for a Multiline Edit Box can be made up as follows.

<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:inputTextarea1}" ).maxlength({
alwaysShow: true,
threshold: 10,
warningClass: "label label-success",
limitReachedClass: "label label-danger",
separator: ' of ',
preText: 'You have ',
postText: ' chars remaining.',
validate: true
});
}
);
]]></xp:this.value>
</xp:scriptBlock>

The final result is a nice Bootstrap look an feel feedback indicator for the maxlength attribute of an Edit Box and MultiLine Edit Box.


F. Code XPage (Gisthub Gist)
<?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="bml/bootstrap-maxlength.js">
</script>
<xp:scriptBlock id="scriptBlock2">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:inputText1}" ).maxlength({
alwaysShow: true,
threshold: 10,
warningClass: "label label-info",
limitReachedClass: "label label-warning",
placement: 'top',
preText: 'used ',
separator: ' of ',
postText: ' chars.'
});
}
);
]]></xp:this.value>
</xp:scriptBlock>
<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:inputTextarea1}" ).maxlength({
alwaysShow: true,
threshold: 10,
warningClass: "label label-success",
limitReachedClass: "label label-danger",
separator: ' of ',
preText: 'You have ',
postText: ' chars remaining.',
validate: true
});
}
);
]]></xp:this.value>
</xp:scriptBlock>
<xc:ccLayoutBootstrap>
<xp:this.facets>
<xp:panel xp:key="facetMiddle">
<h3>Bootstrap Maxlength</h3>
<h4>Bootstrap Maxlength is a visual feedback indicator for the maxlength attribute.
The Bootstrap Maxlength plugin integrates by default with Twitter bootstrap using badges
to display the maximum lenght.</h4>
<xp:br></xp:br>
<div class="col-sm-6">
<label class="control-label"><strong>Text Field</strong></label>
<xp:inputText id="inputText1">
<xp:this.attrs>
<xp:attr name="maxlength" value="25"></xp:attr>
</xp:this.attrs></xp:inputText>
<xp:br></xp:br>
<label class="control-label"><strong>Textareas</strong></label>
<xp:inputTextarea id="inputTextarea1">
<xp:this.attrs>
<xp:attr name="maxlength" value="125"></xp:attr>
</xp:this.attrs></xp:inputTextarea></div>
</xp:panel>
</xp:this.facets>
</xc:ccLayoutBootstrap>
</xp:view>

For more information: Bootstrap Maxlength
See also my Video Bootstrap Maxlength.

No comments:

Post a Comment