jQuery in XPages #9 – PageSlide

In this article I will describe how to implement and provide examples of use the jQuery plugin PageSlide within an XPage. This is a fairly simple plugin with very few parameters but provides an alternate method for displaying information to users

PageSlide.js

Demonstration

The XPages integration of PageSlide is demonstrated here

Download

The demonstration database can be downloaded from the link above or from here

Introduction

PageSlide by Scott Robin is a simple plugin which allows external content to be displayed in a sidebar on the page. There are only two parameters, direction (left or right) and modal (true or false).  It is really quite simple. As you will see my implementation does not use XPage XML markup to add resources or to activate the capability. I found that this caused issues in the browser. The capability works well using the example code from the website, applied in an XPage.

PageSlide showing data from another XPage to the side of the main
PageSlide showing data from another XPage to the side of the main

How does it work?

I added jQuery, the pageslide js library and the pageslide.css stylesheet to my database through the WebContents folder and added them to to my XPage via script and link tags.

		  <script src="js/jquery.pageslide.js"></script>
		  <script src="js/jquery-1.7.1.min.js"></script>
		  <link rel="stylesheet" type="text/css" href="css/jquery.pageslide.css" />

The basic concept works like this:

  • You create a link on the page
    • < a href=”xSomething.xsp” class=”aClass”>
  • You select the link in question
    • $(“a.aClass”).
  • You pageslide it
    • pageslide({direction: “left”, modal: false})
	<a href="xPageSlide_1.xsp" class="myClass">Display user information</a>
	<script>$("a.myClass").pageslide({ direction: "left", modal: false});</script>

When clicking on the link this produces the effect of opening xPageSlide_1.xsp in the right hand panel of the screen (direction: left moves everything to the left).
If the modal = true paramater is included then the “slide” can only be closed programmatically. This forces user interaction with the information. If not included or modal = false then clicking anywhere in the screen will make the slide disappear.

And that is pretty much it….. nothing complicated this week 🙂

More examples
I created a custom control with custom parameters so that the capability can be added to any page.

Custom Control properties
Custom Control properties

The example page contains a demo of this custom capability and it is build like this:

  • A link with a dynamic href is added to the form along with
  • A scriptBlock which adds the PageSlide capability to the link passing the custom parameters as necessary.
<xp:link escape="true" text="CompositeData example"
	id="compositeDataExample"
	value="${compositeData.content}" styleClass="marky">
</xp:link>
<xp:scriptBlock id="scriptBlock1">
	<xp:this.value><![CDATA[
		bModal = "#{compositeData.modal}"
		bModal == "false" ? false : true
		$("[id$=compositeDataExample]").pageslide(
			{ 	direction: "#{compositeData.direction}",
				modal: bModal
			});
	]]></xp:this.value>
</xp:scriptBlock>

The other example I created involves using sessionScope variables to look up information dynamically.

sliding in a new XPage with dynamic content
sliding in a new XPage with dynamic content

There is a hidden anchor tag on the form which is has PageSlide attached to it in a similar way as described above. It is hidden becasue we are going to “click” it programmatically when a user is selected in the comboBox.

<a href="xPageSlide_1.xsp" class="marky2" style="display:none">Display user information</a>
<script>$("a.marky2").pageslide({ direction: "right", modal: true });</script>

The combobox has a simple SSJS lookup formula showing the first column of the AllContacts view
#{javascript:@DbColumn(“”, “AllContacts”, 1)}

<xp:comboBox id="comboBox1" defaultValue="Pick a person">
	<xp:selectItem itemLabel="Pick a person" itemValue="Pick a person"></xp:selectItem><xp:selectItems>
		<xp:this.value><![CDATA[#{javascript:@DbColumn("", "AllContacts", 1)}]]></xp:this.value>
	</xp:selectItems>
	<xp:eventHandler event="onchange" submit="true" refreshMode="partial" refreshId="computedField1">
	</xp:eventHandler>
</xp:comboBox>

In the onChange event I perform a partial refresh of the computedField1. computedField1 looks like this and returns some JavaScript which triggers the link “.click()”

<xp:text escape="false" id="computedField1">
	<xp:this.value><![CDATA[#{javascript:var person = sessionScope.person=getComponent("comboBox1").getValue();
		var disp = "<script>$('a.marky2').click()</script>";
		disp2 = (person == "Pick a person" ? "" : disp);
		return disp2
	}]]>
	</xp:this.value>
</xp:text>
  • If a person is picked the computed field is refreshed
    • The computed field sets a sessionScope variable based on the value selected
      • var person = sessionScope.person=getComponent(“comboBox1”).getValue()
    • The refreshed value contains a script tag which executes when the refresh is loaded.
      • var disp = “// “;
        disp2 = (person == “Pick a person” ? “” : disp);
        return disp2
    • $(‘a.marky2’).click() clicks the hidden link opening the page slide

The xPageSlide_1.xsp page takes the sessionScope variable and looks up the user’s information based on the variable set in the computedField1 above.

<xp:div id="div1" style="display:nonex">
				    <h2 style="color: white">User Information</h2>
				    <xp:br></xp:br><xp:br></xp:br>
					<xp:text escape="true" id="computedField1"><xp:this.value><![CDATA[#{javascript:var per = sessionScope.person;
@DbLookup(@DbName(), "vwContacts", per, 4)}]]></xp:this.value></xp:text>

					<xp:br></xp:br>
					<xp:br></xp:br>
					<xp:text escape="true" id="computedField5"><xp:this.value><![CDATA[#{javascript:var per1 = sessionScope.person;
@DbLookup(@DbName(), "vwContacts", per1, 5)}]]></xp:this.value></xp:text>
					<xp:br></xp:br>
					<xp:br></xp:br>
					<xp:text escape="true" id="computedField3"><xp:this.value><![CDATA[#{javascript:var per2 = sessionScope.person;
@DbLookup(@DbName(), "vwContacts", per2, 6)}]]></xp:this.value></xp:text>
					<xp:br></xp:br>					<xp:br></xp:br>
										<xp:button id="button1" value="Close" style="display: block">
		<xp:eventHandler event="onclick" submit="false">
			<xp:this.script><![CDATA[parent.$.pageslide.close()]]></xp:this.script>
		</xp:eventHandler></xp:button><xp:br></xp:br>

</xp:div>

and with a little styling we are done for a consistent look and feel

<style>
DIV {
    background-color: #333333;
    color: #FFFFFF;
    height: 100%;
    padding: 20px;
    position: fixed;
    top: 0;
    width: 260px;
    z-index: 999999;
}

H2 { color: white }
</style>

Conclusion

I could easily see myself using PageSlide if I wanted to use a hidden menu or if I wanted to have a status update bar running in the background of my webpage which was accessed and made visible to the user when they wanted it to be there.

This is certainly the simplest plugin I have written about, but this is a very elegant solution to displaying hidden information to a user on demand.

Demonstration

The XPages integration of PageSlide is demonstrated here

 

jQuery in XPages #8 – Tokeninput autocomplete

In these two articles I am going to illustrate and describe how to implement an alternative to the XPage typeAhead, using the “jQuery Tokeninput“. Unlike the XPages typeahead the jQuery Tokeninput has a large and flexible paramaterized API which allows for control over how the results are displayed, how the results are created and the source of the data. We are going to look at how to search a basic JSON string, a notes agent generated JSON feed, a twitter JSON feed, and an XPage REST JSON feed.

Tokeninput.js

Introduction
Tokeninput provides a typeAhead-like capability whereby a user is presented with matching options as they start to type into a text field. The source of the data can either be a local JSON object or a web provided JSON object.

Basic Tokeninput user interaction
Tokeninput with facebook look and feel
Tokeninput with facebook look and feel
Tokeninput with mac look and feel
Tokeninput with mac look and feel

The search results are determined from a JSON string and can come from any web source; flickr, twitter, facebook and domino to name but a few examples. What is really nice about Tokeninput is the control and flexibility provided to the developer out of the box allows you to make some very impressing, interactive webpages with very little effort. Unlike the XPage typeahead Tokeninput will also allow you to select multiple values and the display of these values can be controlled using a CSS.

Example Twitter feed with formatted results
Example Twitter feed with formatted results

Demonstration

The XPages integration of Tokeninput is demonstrated here

Download

The demonstration database can be downloaded from the link above or from here

How does it work in XPages?

For a more detailed dive into how the examples can be recreated and function in an XPage please check out the how does it work article

Tokeninput API

Tokeninput is extremely versatile and has a large number of parameters (as of v1.6) – these are taken straight from the website and you should check out all the examples on the website to get a good idea of all the capabilities

Search Settings

  • method
    • The HTTP method (eg. GET, POST) to use for the server request. default: “GET”.
  • queryParam
    • The name of the query param which you expect to contain the search term on the server-side. default: “q”.
  • searchDelay
    • The delay, in milliseconds, between the user finishing typing and the search being performed. default: 300 (demo).
  • minChars
    • The minimum number of characters the user must enter before a search is performed. default: 1 (demo).
  • propertyToSearch
    • The javascript/json object attribute to search. default: “name” (demo).
  • jsonContainer
    • The name of the json object in the response which contains the search results. This is typically used when your endpoint returns other data in addition to your search results. Use null to use the top level response object. default: null.
  • crossDomain
    • Force JSONP cross-domain communication to the server instead of a normal ajax request. Note: JSONP is automatically enabled if we detect the search request is a cross-domain request. default: false.

Pre-population Settings

  • prePopulate
    • Prepopulate the tokeninput with existing data. Set to an array of JSON objects, eg: [{id: 3, name: “test”}, {id: 5, name: “awesome”}] to pre-fill the input. default: null (demo).

Display Settings

  • hintText
    • The text to show in the dropdown label which appears when you first click in the search field. default: “Type in a search term” (demo).
  • noResultsText
    • The text to show in the dropdown label when no results are found which match the current query. default: “No results” (demo).
  • searchingText
    • The text to show in the dropdown label when a search is currently in progress. default: “Searching…” (demo).
  • deleteText
    • The text to show on each token which deletes the token when clicked. If you wish to hide the delete link, provide an empty string here. Alternatively you can provide a html string here if you would like to show an image for deleting tokens. default: × (demo).
  • animateDropdown
    • Set this to false to disable animation of the dropdown default: true (demo).
  • theme
    • Set this to a string, eg “facebook” when including theme css files to set the css class suffix (demo).
  • resultsFormatter
    • A function that returns an interpolated HTML string for each result. Use this function with a templating system of your choice, such as jresig microtemplates or mustache.js. Use this when you want to include images or multiline formatted results default: function(item){ return “<li>” + item.propertyToSearch + “</li>” } (demo).
  • tokenFormatter
    • A function that returns an interpolated HTML string for each token. Use this function with a templating system of your choice, such as jresig microtemplates or mustache.js. Use this when you want to include images or multiline formatted tokens. Quora’s people invite token field that returns avatar tokens is a good example of what can be done this option. default: function(item){ return “<li><p>” + item.propertyToSearch + “</p></li>” } (demo).

Tokenization Settings

  • tokenLimit
    • The maximum number of results allowed to be selected by the user. Use null to allow unlimited selections. default: null (demo).
  • tokenDelimiter
    • The separator to use when sending the results back to the server. default: “,”.
  • preventDuplicates
    • Prevent user from selecting duplicate values by setting this to true. default: false (demo).
  • tokenValue
    • The value of the token input when the input is submitted. Set it to id in order to get a concatenation of token IDs, or to name in order to get a concatenation of names. default: id

Callbacks

  • onResult
    • A function to call whenever we receive results back from the server. You can use this function to pre-process results from the server before they are displayed to the user. default: null (demo).
  • onAdd
    • A function to call whenever the user adds another token to their selections. defaut: null (demo).
  • onDelete
    • A function to call whenever the user removes a token from their selections. default: null (demo).
  • onReady
    • A function to call after initialization is done and the tokeninput is ready to use. default: null


jQuery in XPages #8 – Tokeninput autocomplete – how does it work?

This article is written in support of the original jQuery in XPages #8 – Tokeninput autocomplete article

Demonstration

The XPages integration of Tokeninput is demonstrated here

Download

The demonstration database can be downloaded from the link above or from here

How to add Tokeninput to your database

Tokeninput consists of one js file and three css files. These can be added to your database by dragging and dropping them into the WebContents folder of the database (available through the Package Explorer)

Token2

The js files can be added to our database (along with the jQuery library) using the following XML markup in the XPage source

	<xp:this.resources>
		<xp:script src="js/jquery.tokeninput.js" clientSide="true"></xp:script>
		<xp:script src="js/jquery-1.7.1.min.js" clientSide="true"></xp:script>
		<xp:styleSheet href="css/Tokeninput/token-input.css"></xp:styleSheet>
		<xp:styleSheet href="css/Tokeninput/token-input-facebook.css"></xp:styleSheet>
		<xp:styleSheet href="css/Tokeninput/token-input-mac.css"></xp:styleSheet>
	</xp:this.resources>

Basic inner workings of Tokeninput

Tokeninput searches a given JSON string for a specified search parameter. As with many jQuery plugins there are set default which can be over-riden with user provided parmeters. By default the expected string format is:

	{{"id": "12345", "name": "Marky Roden"}]

and the code to add this to your XPage is as simple as the following where inputText3 is our text field and .tokenInput is out plugin instantiation:

	<xp:inputText value="#{sample.Custom}" id="inputText3">
	</xp:inputText>

	<xp:scriptBlock id="scriptBlock4">
		<xp:this.value>
		<![CDATA[
			$(document).ready(function() {
				$("#[id$=inputText3]").tokenInput("xTokeninput.xsp/contactjson", {
				  propertyToSearch: "email"
				});
			});
		]]>
		</xp:this.value>
	</xp:scriptBlock>

As we will see later, “xTokeninput.xsp/contactjson” is a REST service we are going to create on the page and propertyToSearch: “email” is the JSON string property we want to search

Example selecting from a REST service
Example selecting from a REST service

Changing the theme
Using the “theme” paramater we are able to determine the style in which the selected “tokens” are displayed to the user. Adding the facebook theme which comes with the plugin we change the way the results are displayed (not the results themselves).

			$(document).ready(function() {
				$("#[id$=inputText3]").tokenInput("xTokeninput.xsp/contactjson", {
				  propertyToSearch: "email",
				  theme: facebook
				});
			});
Example REST data with facebook theme
Example REST data with facebook theme

Data sources for Tokeninput

As you can see from the provided example we are able to GET (or POST) the JSON data from many sources, I have provided just a few examples, but really the options are only bounded by your needs and imagination.

A boring old Notes Agent

Before I get any grief for not using an XAgent the reason I use this as my first example is that it is probably the easiest to understand and will demonstrate how Tokeninput can generate and manage the search results itself (using it’s own internal ajax calls).
By default if you provide a URL (not a JSON object) to Tokeninput it will assume that is the URL to search and it will add “q=” to the end of the provide URL string, and look for the results. This really is as simple as it gets for Tokeninput, not a single parameter, all assumed default values. custom1 is the name of our text field and peopleLookup is our notes agent.

		$(document).ready(function() {
			$("#[id$=custom1]").tokenInput("peopleLookup?openagent?open&", {
			})
	    });

The peopleLookup agent provides a JSON string based on document fields values in a view, a snippet is below and the original is provided in the sample database

sQuery = StrRight(doc.Query_String_Decoded(0), "&q=")
Set docNAB = viewNAB.getdocumentbykey(sQuery)
i=0
Print {content-type: text/json}
	Print "["
	'loop for 10 results
	Do While Not docNAB Is Nothing And i<10

		'Because this ia JSON string each entry needs to have a comma after it except the first and last
		'so we add a comma because we know we are adding another value here
		If i>0 Then
			Print {, }
		End If
			Print |{"id":"|+docNAB.id(0)+|","name":"|+docNAB.FirstName(0)+| |+docNab.MiddleInitial(0)+| |+docNAB.LastName(0)+|"}|
			Set docNAB=viewNAB.getnextdocument(docNAB)
		i=i+1
	Loop
	Print "]"

As you can see from the picture below the JSON string maps directly to the Tokeninput displayed user options. The URL this JSON came from was http://demo.xomino.com/xomino/jQinX.nsf/peopleLookup?openagent?open&q=b

JSON data shown in firebug along with results
JSON data shown in firebug along with results

XPage REST Data Source

Using the fantastic OpenNTF extension library (and included out of the box in 8.5.3 UP1) we are able to add a REST service to the XPages. What does that mean? Well what the REST service allows us to do at its most basic is it allows us to create a JSON object from a notesview in a format that makes sense. Unlike the readviewentries option (discussed later in the article) the format created is easy to parse, easy to read and most importantly for Tokeninput, flat. If you want to take a look at the feed you will notice that it within the url of the example page (xTokeninput.xsp)

The code for the REST service is shown below:

	<xe:restService id="restService1" pathInfo="contactjson">
		<xe:this.service>
			<xe:viewJsonService viewName="AllContacts2" var="entry"
				contentType="text/plain" count="10">
				<xe:this.columns>
					<xe:restViewColumn name="id" columnName="id">
					</xe:restViewColumn>
					<xe:restViewColumn name="email"
						columnName="email">
					</xe:restViewColumn>
				</xe:this.columns>
				<xe:this.keys><![CDATA[#{javascript:return facesContext.getExternalContext().getRequest().getParameter("q")}]]></xe:this.keys>
			</xe:viewJsonService>
		</xe:this.service>
	</xe:restService>

and this is how it breaks down…..

  • viewName=”AllContacts2″ specifies the view which we want to pull the data from
  • var = Entry gives us access to the viewentry for further manipulation (see OpenNTF sample database for examples)
  • name = “name” is the name of the JSON Object [{“name”: “marky@whatever.com”}]
  • columnName = “email” is the programmatic name of the view column which is the object value [{“name”: “marky@whatever.com”}]
  • count=10 determines the number of results returned.

For each column we want provided in the feed we add a restViewColumn and give it the matching columnName and the JSON object value to display as (name=”id”)

The View Column Programmatic name must be used not the column Header
The View Column Programmatic name must be used not the column Header
	<xe:restViewColumn name="id" columnName="id"></xe:restViewColumn>

We can provide a “key” to the REST service which acts likes a getDocumentByKey.

	<xe:this.keys><![CDATA[#{javascript:return facesContext.getExternalContext().getRequest().getParameter("q")}]]></xe:this.keys>

The service is called every time the user enters a new key value “ma” would create the URL request to

http://demo.xomino.com/xomino/jQinX.nsf/xTokeninput.xsp/contactjson?q=ma

The key then extract the “ma” from the Query_String and provides the first document matching “ma” and then 10 documents after that. These become the displayed results from Tokeninput. A picture of the results was shown above in the initial discussion.

Standard Domino ?ReadViewEntries&OutputFormat=JSON

Since version 8 (officially) we have been able to get view data in a JSON format using the following type of URL
blah.nsf/viewname?ReadViewEntries&StarkKey=x&OutputFormat=JSON. But unfortunately the domino creation wizards at IBM decided to make the output format look more like a notesview than anything which works in Javascript (kinda the point of JSON). It ugly. So we have to work to get it into the format we need for Tokeninput. Click here to see an example of the JSON format and then you’ll have to take it to jsBeautifier.org to see the indentation. The major headache is that “@” values are properties and not objects values which makes for confusing code.

I have working proof of concept for this but I do not like the solution so it is really hard for me to write about it. With so many “better” ways to get the data from a notes view this is not something I recommend. If anyone is interested please contact me directly (@MarkyRoden) and we can discuss.

Twitter Data Source

The specification for the publically available twitter API is available from and the simplified format looks like this (looking at the feed for @MarkyRoden)

Click Here for the Feed link

[{
    "created_at": "Sat Apr 28 15:42:51 +0000 2012",
    "id": 196263215288684545,
    "id_str": "196263215288684545",
    "text": "@byrd1089 jQuery Tokeninput - hopefully will figure out how to parse readviewentires to the necessary format :)",
    "source": "\u003ca href=\"http:\/\/www.tweetdeck.com\" rel=\"nofollow\"\u003eTweetDeck\u003c\/a\u003e",
    "truncated": false,
    "in_reply_to_status_id": 196254762453303296,
    "in_reply_to_status_id_str": "196254762453303296",
    "in_reply_to_user_id": 92247920,
    "in_reply_to_user_id_str": "92247920",
    "in_reply_to_screen_name": "byrd1089",
    "user": {
        "id": 463110112,
        "id_str": "463110112",
        "name": "Mark Roden",
        "screen_name": "MarkyRoden",
        "location": "Reston, VA USA",

The source code for my example twitter pull is below. What I am doing is loading the data via “screen_name” value (e.g. edbrill or openntf) for the last 100 entries and returning the 10 entries matching the search parameter.  The parameters do the following thing:

  • propertyToSearch: the field to be searched “text”
  • queryParam: the Object name to query from the API “screen_name”
  • tokenFormatted: the HTML describing the way the results are displayed to the user
  • results formatted: the HTML describing the way the select result is stored
  • onResult: a callback function (in this case correcting a bug in Tokeninput replacing ( and ) in the return string)
			$(document).ready(function() {
				$("#[id$=inputText6]").tokenInput("https://api.twitter.com/1/statuses/user_timeline.json?include_entities=true&include_rts=true&count=10", {
					propertyToSearch: "text",
					queryParam: "screen_name",
					resultsFormatter: function(item){ return "<li>" + "<img src='" + item.user.profile_image_url + "' title='" + item.user.screen_name + "' height='40px' width='40px' />" + "<div style='display: inline-block; padding-left: 10px; width:80%'><div class='full_name'>" + item.text  + "</div></div></li>" },
					tokenFormatter: function(item) { return "<li>" + "<img src='" + item.user.profile_image_url + "' title='" + item.user.screen_name + "' height='40px' width='40px' />" + "<div style='display: inline-block; padding-left: 10px; width:80%'><div class='full_name'>" + item.text  + "</div></div></li>" },
					onResult: function (results) {
      					jQuery.each(results, function (index, value) {
				        	value.text = value.text.replace(/\(/g, '(').replace(/\)/g, ')');
						});
				      return results;
				    }
			    });
		    });

And this to me with where Tokeninput takes the typeahead autocomplete to the next level…..

Example Twitter feed with formatted results
Example Twitter feed with formatted results

so what happens when this is submitted? If you remember the default submitted value in the Tokeninput is “id”….and If you look at the feed there is an id tag for every tweet…..

([{
    "created_at": "Sat Apr 28 15:42:51 +0000 2012",
    "id": 196263215288684545,
    "id_str": "196263215288684545",
    "text": "@byrd1089 jQuery Tokeninput - hopefully will figure out how to parse readviewentires to the necessary format :)",
    "source": "\u003ca href=\"http:\/\/www.tweetdeck.com\" rel=\"nofollow\"\u003eTweetDeck\u003c\/a\u003e",
    "truncated": false,

and when we submit the value back to the database we get a multivalue field containing all the tweet ids. If you want to change the field stored use the “tokenValue” parameter. The Tokeninput field is mapped to the “Custom” field in the XPage through the data source.

Showing the submitted tweet ids stored in the notesdocument
Showing the submitted tweet ids stored in the notesdocument

Scratching the surface

The possibilities with Tokeninput are only limited by the developers imagination and the data source available. I have demonstrated how we can create our own JSON Feed using a REST feed, how to create a simple JSON feed using a notesagent, how to parse an existing notes view readviewentries JSON feed and how to parse an external feed (twitter) and display some fantastic result results while maintaining data control.

In my opinion (from a user experience) this trumps the XPages typeAhead field capability hands down . This also trumps the XPages typeAhead from a developer perspective as well because it will take data from sources other than an internal notes view and will return multiple values which the current type ahead will not.

Demonstration site

This article is published in conjunction with the original post and  demonstration site

And then what?

To be submitted to OpenNTF – I am working on a custom control to add a dynamic Tokeninput field to any XPage. It will provide a direct alternative to the dojo typeAhead and provide greater flexibility for users.

It’s just going to be ready for this week’s article 🙂

Work in progress - custom control for adding tokenizer to an XPage using REST
Work in progress - custom control for adding tokenizer to an XPage using REST

jQuery in XPages #7 – Pines Notify

In this article I will demonstrate how to implement a cool notification technique using Pines Notify.  This small (7k min) js library provides a wealth of flexibility and a feature set second to none. It can use multiple different CSS libraries (bootstrap, jQueryUI and others) so integration into your site is quick and simple.

Introduction

Pines Notify is a notification popup capability which is easily integrated into a website. Like most jQuery plugins there is a methods to instantiate the capability and the ability to pass in multiple parameters.  There are certainly other popup style plugins but this is easy to grasp and the examples are very good.

We are going to look at how to make some complex function popups like these…

Examples of Pines Notify popups
Examples of Pines Notify popups

Demonstration

There are two demonstration pages this week

The first demonstration is a basic port of the Pines Notify buttons from the original example into an XPage.

The second demonstration shows how the Pines Notify could be used in a real application

Download 

Click on the link to download the complete jQuery in XPages demonstration database (including Pines Notify).

Pines Notify

Pines Notify provides a basic shell for popup creation and the capability for multiple custom configurations. A “popup” by default is created on the top right of the screen and disappears after a fixed period of time. The the position, CSS, length of time shown, transparency, contents, callbacks and other features can be controlled through the use of parameters. There are too many to mention in one article but they can all be seen at the example website.

Sample Notification
Sample Notification

Adding Pines Notify to an XPage

The Pines Notify download contains the .js files (readable and minified) and a basic css file. These are easily added to our database as files in the WebContent folder.

Adding Pines Notify js and css fields to our database
Adding Pines Notify js and css fields to our database

Once we have added the js and css files to the database they can be added to our XPage as a resource(s)

	<xp:this.resources>
		<xp:script src="js/jquery.pnotify.min.js" clientSide="true"></xp:script>
		<xp:styleSheet href="css/jquery.pnotify.default.css"></xp:styleSheet>
	</xp:this.resources>

jQuery UI and jQuery

Pines Notify uses the jQuery library and jQuery UI CSS for display. These are added to the XPage as additional resources

	<xp:this.resources>
		<xp:script src="js/jquery-1.7.1.min.js" clientSide="true"></xp:script>
		<xp:styleSheet href="css/jquery.custom-theme/images/jquery-ui-1.8.18.custom.css"></xp:styleSheet>
	</xp:this.resources>

Using Pines Notify

Pines Notify has a basic format for activating. Here is a sample button from the website:

<button class="btn source" onclick="$.pnotify({
 	pnotify_title: 'Regular Notice',
 	pnotify_text: 'Check me out! I\'m a notice.'
});">Regular Notice</button>

In this format the button does not work correctly when added to an XPage as it causes a page refresh when clicked. To turn this into an functioning button we must use an <xp:button> like this one

<xp:button value="xPages Lower Timer" id="button1" styleClass="btn source">
<xp:eventHandler event="onclick" submit="false">
	<xp:this.script>
		<![CDATA[$.pnotify({
			pnotify_title: 'Regular Notice',
		 	pnotify_text: 'Check me out! I\'m a notice.'
		});]]>
	</xp:this.script>
</xp:eventHandler>
</xp:button>

The Pines Notify examples website gives us the code we need to create each button

Taking the sample code from the Pines Notify examples page
Taking the sample code from the Pines Notify examples page

And to convert this to our XPages button we just need to copy and paste this code and insert it into the <![CDATA[ code section above. Using this we can quickly and easily convert the examples into functioning XPages buttons.

Pinning Notifications

By default all Notifications have the ability to “pin” them to the screen. Should they contain information the user wishes to retain, they can do so

Pinning your notification
Pinning your notification

Closing Notifications

By default all notifications can be closed before they fade out using the X in the notification

Stacking notifications

Pines Notify notifications always stack on top of each other, so you never have to worry about position or overlaying issues, they will organize themselves nicely.

Showing all notifications

By default there is a bar added to the screen which allows user to see the last and/or all previous notifications.

Showing all previous notificaitons
Showing all previous notificaitons

Working this into XPages functionality

Javascript alert boxes have been used since the start of the web but they require a user click and an unnecessary interaction from the user if the point of the notification is just that – to notify the user of something.

In our XPages applications we could potentially notify the user after:

  • Successful REST update from the server
  • partialRefresh completion
  • form submission
  • Pager completion
  • General application workflow progress
  • Validation failure

really the possibilities are endless and really up to you the developer.

Examples

My demonstration site examples page has illustrated a number of buttons taken directly from the website and I have also added some notifications to the other jQuery in XPages examples (linked in through the menu).

On my second Demonstration page There are 4 simple examples of real application uses for Pines Notify

Dojo Toaster Widget

On the XPages server without the need for jQuery you can use the dojo toaster widget to provide a notification capability. You should take a look at Chris Toohey’s well written article on Mastering the Dojo Toaster for XPages to get a comparison.

Thanks

To Alan Hurt for pointing me in the direction of this plugin 🙂

Re-styling dynamic content with jQuery Mobile

We are going to quickly look at how using trigger(“create”) can solve the problem of adding dynamic content to a jQuery Mobile application within an XPage.

I will get to writing an article on jQuery Mobile in the future but in the mean time here is something which I came across – how do you re-style the page when new content is created?

Problem

How to re-style newly added content in a jQuery Mobile application.

Situation

I have an acceptance form which I am creating in my XPage application. I have a mobile only view which is determined using a re-direct based on the browser’s user.agent when the device access the application.

jQuery Mobile acceptance form
jQuery Mobile acceptance form

Users are able to add an unknown number of guests. To achieve this functionality I am inserting a new row into the Guest Name table using normal jQuery

$('[id$=add]').click(function() { // when you click the add link
        $('[id$=theTable] tr:last').before('<tr><td><input name="person"'+i+' id=person'+i+' type="text" value="" /></td><td><label id="label'+i+'" for="check'+i+'">Yes</label><input type=checkbox name=check1 id=check'+i+'></td><td><center><img border=0 id=img'+i+' onclick="removeInput(this.id)" src="images/badge-circle-cross-24-ns.png"></center></td></tr>');
        i++;
    });

Unfortunately when I do this out of the box the sweet looking jQuery mobile look and feel is not applied to the new content.

(This problem also occurs if you perform a partialRefresh on the content) and you get something not so nice looking

Adding dynamic content does not style well
Adding dynamic content does not style well

Solution

Fortunately the guys at jQuery Mobile, smart fellows that they are, overcome this issue very easily with a simple one line command which re-applies the mobile style to any element within the supplied container.

Selecting the parent table and applying .trigger(“create”) solves the problem nicely, and it does it so fast it is imperceptible to the naked eye.

$('[id$=theTable]').trigger("create")

And here’s the result – this “looks” so good I would almost rather replace the desktop browser version of this application and have everyone use this look and feel!

jQuery mobile page with the correct styling applied
jQuery mobile page with the correct styling applied

jQuery in XPages #5 – jQueryUI (Accordion)

This week we are going to look at one of the capabilities offered by the jQueryUI website, that accordion. I am going to walk through how I added it to my demo website (because the menu was getting too large). jQueryUI is a jQuery plugin – it extends jQuery using the $selector.doSomething() notation.

We are going to turn a long inflexible menu

Old demo.xomino.com menu
Old demo.xomino.com menu

into this

jQueryUI Accordion Menu
jQueryUI Accordion Menu

Demonstration

To see the new menu in action go to demo.xomino.com

Download

You can download the sample database for all the jQuery in XPages article from here or the demo website.

jQueryUI

jQueryUI is a website which “provides abstractions for low-level interaction and animation, advanced effects and high-level, themeable widgets, built on top of the jQuery JavaScript Library, that you can use to build highly interactive web applications.

What that means for you and I is “a set of really cool visual effects to add to your website really easily” 🙂

The jQueryUI website is very easy to use and a lot of fun to look over. There are multiple demonstrations of everything from accordions, to popup boxes, to date pickers, to sliders, to tabs and many other of the capabilities similarly found within the dojo toolkit.

Individual Packages

In an analogous way to dojo, each of the different capabilities jQueryUI provides can be individually added to the webpage or you can select the ones you need and combine them into one single js file. Adding the capability is just a different process from dojo.

Building your jQueryUI download bundle
Building your jQueryUI download bundle

Themeroller

jQueryUI comes with many pre-built styles

jQueryUI styles
jQueryUI styles

Using the Themeroller you can modify these styles to match your own websites style (in my case oneui2.1_onyx). I happen to like the darkness ui (I am sure it is nothing psychological) and they go nicely together but we are going to adapt the theme to match onyx.

The Accordion

The accordion is created by adding a number of jQuery effects together. If you break it down, what is happening when you click on the header is that the open panel is being reduced in size to zero at the same time as the panel the user clicked on is being opened. There are many jQuery accordion knockoffs from the original – some are really sweet like RhinoSlider and may appear in later articles..

How does it work?

Check out the how does it work article to see how I put all this together

jQuery in XPages #5 – jQueryUI (Accordion) – How does it work?

In this article I will show you how to add a jQueryUI accordion to your XPage as a menu.

Demonstration site

This article is published in conjunction with the original post and the demonstration site

Download

The sample database is available from the link above and (here)

Rolling my theme

Using the jQueryUI themeroller I modified the darkness ui theme to match the colors used by the oneui2.1_onyx CSS which the site now uses

Marky's Rolled theme

Once complete I downloaded the theme via the download builder. I included everything in the download because if I use jQueryUI at a later date I don’t want to have to go through this again – it is a demo site after all and page load time is not on my list of priorities (or I am lazy).

Being serious for a moment:

If you are going to use only one of the capabilities included in the builder for production you should remove everything else. The difference can be as much as over 150k and that will make a huge difference in pageload time.

The download

The contents of the jquery-ui-1.8.18.custom.zip are the necessary javascript and css files to create the visual effect and stylize the webpage. The folder content must be maintained with the structure and the css files refer to the images within the folder structure. You can change this at your own risk but I strongly suggest you don’t. The contents of the folder are as follows:

  • js folder
    • jquery-ui-1.8.18.custom.min.js
    • jquery-1.7.1.min.js
  • css
    • custom-theme
      • jquery-ui-1.8.18.custom.css
      • images
        • 14 images supporting the style

Adding the files to your database

The js file and the css file should be dragged and dropping into the WebContent folder of your database. Visible from the package explorer view of your database.

Adding the jQuerUI files to your database WebContent folder
Adding the jQuerUI files to your database WebContent folder

Adding the file references to your XPage

Within my demo database I have a commonContainer Custom Control that controls my look and feel. I am going to add the file references to that custom control in the following manner. In the source panel at the top of the page I add a reference to each of the necessary js and css files (the paths are relative the XPage)


Adding the Accordion to the menu

Currently the menu is created using this XML markup

<ul>
	<li><strong>#1 High Charts</strong></li>
	<li></li>
	<li></li>
	<li>
</li>
</ul>
etc etc.........

which generates the following HTML when viewed through the webpage

<div class="lotusMenu">
<div class="lotusBottomCorner">
<div class="lotusInner">
<ul>
	<li><a id="view:_id1:_id2:link9" class="xspLink" href="SampleDB/jQInX.zip">Download the Sample DB</a></li>
</ul>
<ul>
	<li><strong>#1 High Charts</strong></li>
	<li><a id="view:_id1:_id2:link1" class="xspLink" href="/xomino/jQinX.nsf/xFruit_Data.xsp">Binding to a Data Table</a></li>
	<li><a id="view:_id1:_id2:link2" class="xspLink" href="/xomino/jQinX.nsf/xFruit.xsp">Binding to a View Panel</a></li>
	<li><a id="view:_id1:_id2:link3" class="xspLink" href="http://www.highcharts.com/demo" target="_blank">Highcharts.com Demos</a></li>
</ul>
<ul>
	<li><strong>#2 Labelify</strong></li>
	<li><a id="view:_id1:_id2:link4" class="xspLink" href="/xomino/jQinX.nsf/xLabelify.xsp">Visual Field Enhancement</a></li>
</ul>
 etc.....</div>

looking at the jQueryUI Accordion example page the menu is created from HTML looking like this….

<div id="accordion">
<h3><a href="#">Section 1</a></h3>
<div>Mauris mauris ante, blandit et, ultrices a, suscipit eget, quam. Integer ut neque. Vivamus nisi metus, molestie vel, gravida in, condimentum sit amet, nunc. Nam a nibh. Donec suscipit eros. Nam mi. Proin viverra leo ut odio. Curabitur malesuada. Vestibulum a velit eu ante scelerisque vulputate.</div>
<h3><a href="#">Section 2</a></h3>
<div>Sed non urna. Donec et ante. Phasellus eu ligula. Vestibulum sit amet purus. Vivamus hendrerit, dolor at aliquet laoreet, mauris turpis porttitor velit, faucibus interdum tellus libero ac justo. Vivamus non quam. In suscipit faucibus urna.</div>
</div>

The critical thing to grasp is that the HTML for each part of the must eventually look like this

<h3><a href="#">Section 1</a></h3>
<div>Text of the link - can be HTML here</div>

And my menu currently does not – time for some basic re-coding. Not hard just tedious (and like the good programmer I am – I am so glad I planned out the website before I started coding it) (*coughs politely*) As this menu is going to grow each week (I assume) it would be foolish to hard code it every week – so I am going to create some documents to represent the menu items and using a Repeat Control I am going to display the documents as HTML to build the Accordion.

Creating the Menu documents

I am going to use a “menu” form to create the documents (not worth an XPage as I am doing this through the client on the back end), and a vwMenu view. The form is very basic (like I said – this is back end only for me, not a production-worthy creation).

Simple menu creation form
Simple menu creation form

The view is categorized with the HTML I am going to need already written into the view columns. Because some of the links are to external websites we have to make a check and if so include the whole URL and not a relative one to the XPage

vwMenu Columns

To generate the HTML for the menu I used a repeat control – I use the repeat control to @DbColumn() the first column of vwMenu and then for each value in that list I am @DbLookup() the values in the 2nd column.

I was doing this with a computed text field and that initially caused me a problem. As you can see from the image below there is a lot more HTML generated that I need for the accordion…..there are way too many SPANS and DIVS

<span class="xspTextComputedField">
</span>
<h3><a href="#">#1 HighCharts</a></h3>
<div>
<a href="/xomino/jQinX.nsf/xFruit_Data.xsp">Binding to a Data Table</a>

<a href="/xomino/jQinX.nsf/xFruit.xsp">Binding to a View Panel</a>

<a href="http://www.highcharts.com/demo">Highcharts.com</a></div>
<span class="xspTextComputedField">
</span><span class="xspTextComputedField">
</span>
<h3><a href="#">#2 Labelify</a></h3>
<div>
<a href="/xomino/jQinX.nsf/xLabelify.xsp">Visual Field Enhancement</a></div>
<span class="xspTextComputedField">
</span><span class="xspTextComputedField">
</span>
<h3><a href="#">#3 Masked Input</a></h3>
<div>
<a href="/xomino/jQinX.nsf/xMaskedInput.xsp">Visual Field Enhancement</a></div>
<span class="xspTextComputedField">
</span><span class="xspTextComputedField">
</span>
<h3><a href="#">#4 prettyPhoto</a></h3>
<div>
<a href="/xomino/jQinX.nsf/xPrettyPhoto.xsp">A lighbox</a></div>
<span class="xspTextComputedField">
</span><span class="xspTextComputedField">
</span>
<h3><a href="#">#5 jQueryUI</a></h3>
<div>
<a href="http://jqueryui.com/demos/accordion/#collapsible">jQueryUI.com accordion</a></div>
<span class="xspTextComputedField">
</span>

This would not work for the accordion which needs a very specific format to work – so thanks to Mark Leusink – I have a new XPages *Best Friend Forever* – disableTheme=”true”.

To remove the <span id=”blah” and return to the HTML I really want from the view there are two steps:

  1. Remove the id from the field
  2. In the All Properties tab select disabledTheme=true
remove the id and select disableTheme=true
remove the id and select disableTheme=true

And this gives us the final code to make the menu


								<![CDATA[#{javascript:@DbColumn(@DbName(), "vwMenu", 1)}]]>

									<![CDATA[#{javascript:
										var temp = vwMenuCol1Repeat;
										var temp1 = "
<h3><a href=\"#\">"+temp+"</a></h3>
"
										temp1+"
<div>"+@Implode(@DbLookup(@DbName(), "vwMenu", temp, 2))+"</div>
"
									}]]>

I added a DIV wrapper to the Menu HTML so that the jQuery function would have an object I could select on. The selector uses [id$=menuContainer] rather than my x$ function just for variety. [id$=] selects all elements which finish with menuContainer. Activating the accordion plugin inside of a scriptblock at the bottom of the page completes the menu code.


									<![CDATA[ 									$(function() { 										$( "[id$=menuContainer]" ).accordion({ 											collapsible: true} 										}); 									}); 								]]>

and we have a menu……with two remaining issues……

  1. The links are black – being inherited from the lotusui class in the Oneui stylesheet
  2. The 1st Highcharts panel always opens (not the section we clicked on)

To remove the black links we add a style to the control to override the oneUI black links

 .ui-state-active a, .ui-state-active a:link, .ui-state-active a:visited {
 color: #FFFFFF !important;
 }
 .ui-state-default a, .ui-state-default a:link, .ui-state-default a:visited {
 color: #FFFFFF !important;
 }
 .lotusMenu h3 {line-height: 0.3}
 

To overcome the panel not opening as a user would expect it, we are going to use a scoped Variable, scoped only to this page. We are going to set the menuOpen viewScope variable in the preloading of the page – in this case

	<![CDATA[#{javascript:viewScope.menuOpen=3}]]>

and activate the panel with the scoped variable in the accordion build code – active: #{viewScope.menuOpen}.


									<![CDATA[ 									$(function() { 										$( "[id$=menuContainer]" ).accordion({ 											collapsible: true, 											active: #{viewScope.menuOpen} 										}); 									}); 								]]>

and we have a new menu 🙂

The accordion menu

Demonstration site

This article is published in conjunction with the original post and  demonstration site

PS

I know I am going to run out of space on this accordion menu within 10 articles or so – an excuse for a new article? 😉