Tuesday, 15 November 2016

Using WebUI Popover in XPages - A lightWeight jQuery Popover Plugin with some Awesome New Features

For a project I was looking for a lightweight Popover plugin with some additional options as backdrop and iframe support. In my search I came across the WebUI Popover Plugin, a lightWeight Popover Plugin using jQuery that enchances the Popover plugin of bootstrap with some awesome new features. It works well with bootstrap, but bootstrap is not necessary! In this blog post I will show how this plugin can be used in an XPages application.
In order to use the WebUI Popover Plugin, the JavaScript and CSS file(s) need to be included on the XPage / Custom Control. The latest version can be downloaded from GitHub: WebUI Popover.

Features
- Fast,lightweight
- Support more placements
- Auto caculate placement
- Close button in popover
- Multipule popovers in same page
- Different styles
- Support url and iframe
- Support async mode
- Different animations
- Support backdrop

Default options
placement:'auto' (values: auto,top,right,bottom,left,top-right,top-left,bottom-right,bottom-left,auto-top,auto-right,auto-bottom,auto-left,horizontal,vertical)
container: document.body (The container in which the popover will be added i.e. The parent scrolling area. May be a jquery object, a selector string or a HTML element.)
width:'auto' (can be set with  number)
height:'auto (can be set with  number)
trigger:'click' (values:  click,hover,manual,sticky(always show after popover is created)
selector:false (jQuery selector, if a selector is provided, popover objects will be delegated to the specified.)
style:'' (Not to be confused with inline `style=""`, adds a classname to the container for styling, prefixed by `webui-popover-`. Default '' (light theme), 'inverse' for dark theme)
animation:null (pop with animation,values: pop,fade; only take effect in the browser which support css3 transition)
delay: {show and hide delay time of the popover, works only when trigger is 'hover',the value can be number or object
show: null,
hide: 300
},
async: {
type:'GET' (ajax request method type, default is GET)
before: function(that, xhr) {} (executed before ajax request)
success: function(that, data) {} (executed after successful ajax request)
error: function(that, xhr, data) {} (executed after error ajax request)
},
cache:true (if cache is set to false,popover will destroy and recreate)
multi:false (allow other popovers in page at same time)
arrow:true (show arrow or not)
title:'' (the popover title, if title is set to empty string,title bar will auto hide)
content:'' (content of the popover,content can be function)
closeable:false (display close button or not)
direction:'' (direction of the popover content default is ltr ,values:'rtl';)
padding:true (content padding)
type:'html' (content type, values:'html','iframe','async')
url:'' (if type equals 'html', value should be jQuery selecor.  if type equels 'async' the plugin will load content by url.)
backdrop:false (if backdrop is set to true, popover will use backdrop on open)
dismissible:true (if popover can be dismissed by  outside click or escape key)
autoHide:false (automatic hide the popover by a specified timeout, the value must be false,or a number(1000 = 1s)
offsetTop:0 (offset the top of the popover)
offsetLeft:0 (offset the left of the popover)
onShow: function($element) {} (callback after show)
onHide: function($element) {} (callback after hide)

Adding the JS and CSS files
The JavaScript and CSS files must be added to the WebContent Folder in the Package Explorer.
In this example a Folder webuipopover has been added in the WebContent Folder.
Next the JavaScript and CSS files, jqueru.webui-popover.js and jquery.webui-popover.css, must be included on the XPage or Custom Control. In this example I add the files to an XPage.

<link rel="stylesheet" href="webuipopover/jquery.webui-popover.css" />
<script type="text/javascript" src="webuipopover/jquery.webui-popover.js"></script>

Adding the x$ jQuery selector for XPages
Furthermore I recommend to use the the great XSnippet by Mark Roden, x$ jQuery selector for XPages, to initialize the plugin. The XSnippet can be added to the Script Libraries.

The script itself can be made up as follows. In this example I use a few Options.

<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:button1}" ).webuiPopover({
title:'WebUI Popover',
content:'Popover trigged by mouse hover, placement right.',
trigger:'hover',
placement:'right',
closeable:true,
backdrop:false,
multi:true,
delay: {
show: 0,
hide: 9000
}
});
}
);

AMD Loader Fix
Finally, the JavaScript files jquery.webui-popover.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 jquery.webui-popover.js
2. Select Open With - Client/Server JS Editor
3. Removed define.amd and replace it with false
4. Save the JavaScript file jquery.webui-popover.js

Note: There are other solutions for the AMD Fix. For more information about these solutions see my blog post Bootstrap Plugins in XPages Part VI - jQuery and JavaScript AMD (Asynchronous Module Definition) Fixes (2).

The final result is a responsive WebUI Popover with some additional functionality in the initial setup.


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 rel="stylesheet" href="webuipopover/jquery.webui-popover.css" />
<script type="text/javascript" src="webuipopover/jquery.webui-popover.js">
</script>
<xp:scriptBlock id="scriptBlock1">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:button1}" ).webuiPopover({
title:'WebUI Popover',
content:'Popover trigged by mouse hover, placement right.',
trigger:'hover',
placement:'right',
closeable:true,
backdrop:false,
multi:true,
delay: {
show: 0,
hide: 9000
}
});
}
);
]]></xp:this.value>
</xp:scriptBlock>
<xp:scriptBlock id="scriptBlock2">
<xp:this.value><![CDATA[
$(document).ready(
function() {
x$( "#{id:button2}" ).webuiPopover({
type:'iframe',
url: "http://sandywalker.github.io/webui-popover/demo/",
title:'WebUI Popover IFrame',
placement:'bottom-right',
multi:true,
closeable:true
});
}
);
]]></xp:this.value>
</xp:scriptBlock>
<xc:ccLayout><xp:this.facets>
<xp:panel xp:key="facetMiddle">
<h5>WebUI Popover</h5>
<h5>A lightWeight popover plugin with jquery ,enchance the popover plugin of bootstrap with some awesome new features. It works well with bootstrap ,but bootstrap is not necessary!</h5>
<br />
<div class="row">
<div class="col-sm-5">
<xp:inputText id="inputText1"></xp:inputText></div>
<div class="col-sm-2">
<xp:button value="Info" id="button1" styleClass="btn btn-info"></xp:button>
</div>
</div>
<br/>
<div class="row">
<div class="col-sm-5">
<xp:inputText id="inputText2"></xp:inputText></div>
<div class="col-sm-2">
<xp:button value="Info" id="button2" styleClass="btn btn-info"></xp:button></div>
</div>
</xp:panel>
</xp:this.facets>
</xc:ccLayout>
</xp:view>

More info and examples: WebUI Popover Dev

No comments:

Post a Comment