Auto-focus – Do it! It’s just lazy not to.

In this article I will discuss the need as a developer to use an auto-focus on your XPages. You do this when the end-user needs to type something onto your webpage and should not have to use their mouse to click in the field first.

Introduction

You’ve been there – you go to a website internal or external to your company and you have to login in or type something into the page – the search field or something of that ilk. It is the only field on the whole page and you have to use your mouse to focus on the field – frustrating beyond belief and quite frankly, lazy on the part of the developer. It is a pet peeve of mine when something as simple as one line of code can make a big difference to the first thing a user does on your site.

Can you imagine going to Google.com and having to focus on the field to get started on your search? Stupid idea – or so you would think.

Login Pages

The login page is perhaps the most obvious thing – as the developer you should ALWAYS focus on the username field – it is just lazy not to! It is harder on the user to have to click in the field and they are entering your website with an irritation on their mind already.

Auto-focus on the Username field
Auto-focus on the Username field

 

So how do we do this?

Well it depends on what takes your fancy that day…..but this is normally something you would do within some <script> tags on your web page.

Using the plain old JavaScript method

  document.getElementById("username").focus()

In Dojo

  dojo.byId("username").focus()

In jQuery

  $("#username")[0].focus()

NOTE

We use the [0] to get the DOM Node element and use the HTML focus() method
.focus() when applied to a jQuery object is an event handler which determines what happens when you focus on something  – be careful to use correctly

$('#target').focus(function() {
  alert('Handler for .focus() called.');
});

In HTML5

The autofocus attribute of a field is new in HTML5 (thanks to David Walsh). You can also focus on a button and other DOM objects

<input autofocus="autofocus" />
<button autofocus="autofocus">Hi!</button>
<textarea autofocus="autofocus"></textarea>

Change the name of your file with – HTML5 “Download” attribute

In this article I will show you a very simple way to change the name of a file when the user downloads it using the new HTML5 “download” attribute.

The download Attribute 

This is unfortunately only support in Chrome so far but it is coming – the HTML5 download attribute – very simple and very effective. In the old days we had to fiddle with content-type and content-disposition to rename a file on the way out of the server – now much easier.

What we are trying to create is HTML which looks like this

	<a href="/jQInX.zip" class="xspLink" download="MarkySampleDatabase">
		Download the sample database - with download attribute
	</a>

The download=”MarkySampleDatabase” is the important part – it changes the name of the file in the a href to be “MarkySampleDatabase”

The XPages code

The following is 8.5.3 Xpage Source Code adding the download Attribute via the attr properties of the


	<xp:link escape="true" text="Download the sample database - with download attribute" id="link1" value="http://demo.xomino.com/xomino/jQinX.nsf/SampleDB/jQInX.zip">
		<xp:this.attrs>
			<xp:attr name="download" value="MarkySampleDatabase"></xp:attr>
		</xp:this.attrs>
	</xp:link>

Demonstration

And that is pretty much it – from the example which can be seen here there are two links both link to the sample jQinX.nsf sample database

Demo Page
Demo Page

Viewing the source shows us both links are the same…

The same link
The same link

But the one with the download attribute, downloads with a completely different name

Download Attribute in action
Download Attribute in action

Custom date field format in an XPage – mm/dd/yyyy

I was banging my head against the desk this morning for way too long…….

I have a date field which is displaying the date as 1/2/2012 and I need 01/02/2012 and that isn’t an option

Date field options
Date field options

And as I poked around I found “Custom date range” and looky there it is – wasted WAY too much time on this

Custom date options
Custom date options

And then 79 search and replaces in the database and we are all updated – YAY eclipse client

YAY search and replace
YAY search and replace

Using jQuery plugins – the version is important

A couple of times in the last week I have been trying to help a community member with their jQuery in XPages and it has turned out that the problem was because of the new jQuery v1.8 core library – something I had not thought about and wanted to clear up. I am always tell people in my article to just go to jQuery.com and get the latest core library – well now I have a caveat and will be more specific in future articles.

As best as they can, like all library developers, the jQuery team (unless otherwise stated) try to ensure the jQuery core library should be backwards compatible but there are specific things which are deprecated and dropped in subsequent versions. There are thousands of qUnit test modules created to do regression testing on the jQuery core but that doesn’t mean everything is caught – it is impossible to foresee every combination in every project – does this sound familiar…

When you download a plugin, you should always check the release notes to determine which version of jQuery core this plugin was written for/with. Especially with the older plugin written circa 2008/2009 they are many version of jQuery core behind and might not be forward compatible.

Many plugins (especially when downloading from gitHub) package a version of jQuery with that version – I recommend you first test with that version of the core and make sure it works in your xPage before moving to a newer version of the core library.

You also need to be careful that the plugin you are using is compatible with an older core library you might be using – sounds like common sense but it might not always be possible in a production environment.

Personally I have not had any issues with jQuery core v1.7.x running older plugins but I have not yet tried v1.8.

If you need an older version of the jQuery core they are all available here…

http://code.jquery.com/

Keeping your XPage session alive – without keepSessionAlive

There appears to be an issue keeping XPage sessions alive – even with the ExtLib keepSessionAlive control – which keeps the web session alive from the server’s perspective but does not keep the XPages session alive. This is a solution which works – especially for those people who are unable to use the Extension Library Add the following to the bottom of your XPage and what it will do is refresh the DIV preiodically based on your setting (in milliseconds) (300000 = 300 seconds = 5 minutes) – the longest I have had a successful test is 3.5 hours.

<xp:div id="keepSessionAlive"></xp:div>
<xp:scriptBlock id="scriptBlock1">
    <xp:this.value>
    <![CDATA[   
        XSP.addOnLoad(function(){
            setInterval(function(){
                XSP.partialRefreshPost("#{id:keepSessionAlive}", {});   
            }, 300000)
        })]]>
    </xp:this.value>
</xp:scriptBlock>

You need to set a value at least one minute less than the session timeout length set in the application properties for your database.

XPages session timeout parameter
XPages session timeout parameter

Do not set a short refresh time as this will needlessly waste bandwidth and also bloat IE’s RAM usage which is not well managed by the browser. Understand that this is a SECURITY ISSUE at the same time – by basically keeping an idle computer’s session alive you leave it open to hijack without the user’s knowledge – that is the part of the point of a timeout Thanks to Jeremy Hodge who helped figure out the optimal amount of code to do this in

Notes in 9 – adding a jQuery library to your XPage – 100th Post

Today marks the release of my third Notes in 9 video entitled Adding a jQuery library to your XPage. I am always talking about how quick and easy it is to find and add a jQuery plugin to an XPage and in this video I have tried to demonstrate that. This video is in addition to my previous post on the trunk8 plugin

The Notes in 9 video can be found here

In less than 15 minutes I:

  • show the plugin homepage (trunk8)
  • download the library
  • add the library files to my database
  • add the files as a resource to my XPage
  • configure the plugin using Firebug
  • add the plugin code to my XPage
  • finish

This blog post is here for questions/comments and general discussion if anyone feels like it 🙂

It is also my 100th blog post – thanks to Dave Leedy without who’s support I don’t think I would be where I am today.

Notes In 9 - Drive to 99
Notes In 9 – Drive to 99

Code Snippets

The code snippets can be found here

Video Notes and code snippets

jQuery in XPages #15 – Trunk8 (Adding “read more” to your paragraphs)

In this article I will describe how to implement and use the jQuery plugin Trunk8. “trunk8 is an intelligent text truncation extension to jQuery. When applied to a large block of text, trunk8 will cut off just enough text to prevent it from spilling over.”

Demonstration

The XPages integration of Trunk8.js is demonstrated here

Download

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

Trunk8.js

Introduction

Trunk8 is a really neat and simple jQuery plugin which can neaten up your XPages and provide a truncated paragraph of text and can turn large sections of text into something a little more manageable and easier on the eye:

Trunk8 your paragraphs
Trunk8 your paragraphs

How does it work

We add the jQuery library and the trunk8.js library file to the database by adding them to the Web-Contents folder accessible via the package explorer.  (Window–>Show Eclipse Views–>Package Explorer) and drag and drop the two libraries from your computer into the “js” folder.

We add the libraries to our XPages like this in the source panel

<script type='text/javascript' src='/xomino/jQinX.nsf/jquery-1.7.1.min.js'></script>
<script type='text/javascript' src='/xomino/jQinX.nsf/js/trunk8.js'></script>

The trunk8.js plugin comes with a number of parameters which can help control how the plugin interacts with your page and how it displays the resulting trunk8ed text.

settings = {
    fill: '<a href='#'> read more </a>',  //this is what is inserted into the text as placeholder
    lines: 1, //the number of lines of orginal text displayed
    side: 'right', //the placement of the 'read more' left center right
    tooltip: true, //show a tooltip of the original text
    width: 'auto' // style the final text to fit the container.
}

We then apply the plugin to the page via a selector. In this example is I am going use the same viewPanel as, and this can be seen as an alternate to my original blog post regarding Dynamically expanding viewPanel rows.

We are going to select the 4th column in the viewPanel1 table

selecting the 4th column in the table
selecting the 4th column in the table

the jQuery selector for this is shown below – we select the viewPanel1 table by id an within that table we select the TR table rows and then within those the 4th TD table cell (i.e. the 4th column)

	$('[id$='viewPanel1'] tr td:nth-child(4)')

and then to that we apply the trunk8 method and its parameters

		<script>
			XSP.addOnLoad(function(){
				$('[id$='viewPanel1'] tr td:nth-child(4)').trunk8({
					fill: '<a href='#'> read more </a>',  //this is what is inserted into the text as placeholder
					lines: 3, //the number of lines of orginal text displayed
					side: 'right', //the placement of the 'read more' left center right
					tooltip: true, //show a tooltip of the original text
					width: 'auto' // style the final text to fit the container.
				});
			})
		</script>

And we get the following – much neater and easier on the user

Trunk8'd viewPanel column
Trunk8’d viewPanel column

Flexible

The parameters are fairly self explanatory and allow you to control the way the output looks. What I like about this plugin over others of a similar vein is that the width is dynamically calculated correctly and always fills the container. With a little more imagination you could have the “read more” link to a better tooltip or even click to open a dialog – because you can insert your own HTML the choice is yours – love it!

Conclusion

Every time I see a new plugin like this it just re-enforces to my why I evangelize using jQuery in XPages so much. It took me less than 10 minutes to implement the demonstration and took longer to write up this article. This is a real business requirement which is met with no effort at all on the part of the XPage developer. It’s a no brainer!

Demonstration

The XPages integration of Trunk8.js is demonstrated here

Firefox 15 out now – with integrated JavaScript debugger

This week the new FireFox 15 browser was released with a nice new list of goodies

http://www.mozilla.org/en-US/firefox/15.0/releasenotes/?utm_source=html5weekly&utm_medium=email

One thing which caught my eye was the integrated debugger within the native Firefox developer tools. This is not a new feature to those of us used to FireBug debugging but a very nice addition to the toolkit. Firebug is a fantastic tool and I cannot do without it – but it takes up memory and slows things down a bit. having an integrated debugger (I assume) will be quicker and less disruptive. We will have to have a play and see.

Here is a screenshot from my MWLUG 2012 presentation which was demonstrating the Firebug debugger

FireFox 15 integrated JavaScript debugger
FireFox 15 integrated JavaScript debugger

Productive !

jQuery in XPages #14 – TOC (Create a menu to scroll to a form section)

In this article I will demonstrate how to implement the jQuery plugin TOC (Table of Contents) into your XPage and let your users select the section of the document they want to scroll to at the click of a link.

Introduction

When you are dealing with a long complex form and you need to open the document, edit one field and exit – it can be a pain to scroll down and find the section. Another frustration is having to scroll up and down the page comparing two different fields. The TOC jQuery plugin can help with this and it works especially well within the confines of the OneUI construct with the Left Column already provided as a perfect spot to put the menu.

The Demonstration

The demonstration can be found here

Download

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

What does it do?

Well the TOC plugin creates a “menu” of sorts on the page and allows the user to click on the menu and scroll to that place on the page.

The menu is created on the left and scrolls with the user – clicking on the link

Clicking on the TOC link
Clicking on the TOC link

Scrolls the user down the page to the section

Scrolls to the new section
Scrolls to the new section

 

Setting up the database

As with many of the jQuery plugins this one is very simple and easy to implement within your XPage. You first need to download jQuery and the TOC plugin and add them to your database.

jQuery TOC can be found here and the source code can be downloaded from here.

The latest version of jQuery can be downloaded from the jQuery.com website

The jQuery and TOC JavaScript libraries are added to the database through the WebContents folder. Change the Designer perspective to show the Package Explorer (Window–>Show Eclipse Views–>Package Explorer) and drag and drop the two libraries from your computer into the “js” folder. (You can see the demo database as an example)

The js libraries are added to our XPage Source as follows

	<script src="js/jquery-1.8.min.js" clientSide="true"></script>
	<script src="js/toc.js" clientSide="true"></script>

The CSS is added to our XPage like this

	<link rel="stylesheet" href="toc.css"/>

Adding TOC to our XPage

Instantiating TOC on the XPage uses code which looks like this. I just used the basics but I changed highlightOffsets to be 200 as I think that works better:

$('document').ready( function(){
	$('#toc').toc({
	    'selectors': '.inTOC', //elements to use as headings
	    'container': 'body', //element to find all selectors in
	    'smoothScrolling': true, //enable or disable smooth scrolling on click
	    'prefix': 'toc', //prefix for anchor tags and class names
	    'onHighlight': function(el) {}, //called when a new section is highlighted
	    'highlightOnScroll': true, //add class to heading that is currently in focus
	    'highlightOffset': 200, //offset to trigger the next headline
	    'anchorName': function(i, heading, prefix) { //custom function for anchor name
	        return prefix+i;
	    },
	    'headerText': function(i, heading, $heading) { //custom function building the header-item text
	        return $heading.text();
	    }
	});
});

Where #toc is a <div with id=”toc” as an attribute and .inTOC are the HTML elements (class=”inTOC”) which are used to determine the titles of the TOC and the sections on the webpage which they refer to. In my demo database you will find the toc <div> in the commonContainer custom control.

In my case I added a <Span to the page above the section I wanted – but to “hide” it from being seen I used a style. The reason I did this is because of the dijitTitlePane which did not lend itself well to being a selector for this purpose.

	<style>
		.inTOC {visibility: hidden;}
	</style>

	<xp:span styleClass="inTOC">Personal Information</xp:span>
	<xp:div id="titleChildren" dojoType="dijit.TitlePane" title="Personal Information" style="font-weight:bold">
		Panel contents
	</xp:div>

Scrolling up and down the page

A really nice feature of the TOC plugin is that when you scroll up and down the page the menu highlights to show that you are looking at that section. Can seem fairly obvious but that is a really nice touch for the user experience.

Overall

I really like this plugin – it is very simple, very, and fulfills a common requirement perfectly.

 

jQuery side note

As I have told many people my purpose of these jQuery in XPages examples is not to make you use them today – but when the requirement comes along you know it is there. Just this week my customer said to me that they wanted a menu on their LONG web form to be able to click on it and scroll to the section in question. I had seen the TOC plugin and bookmarked it a few months ago – I knew it existed and within 2 hours it was implemented within the design of their application.

2 hours !

And that is why jQuery rocks – not just the code itself but the fact that so many people have written so many cool plugins for the rest of us to take advantage of.

 

 

Nice simple OneUI XPage layout section with dijit.TitlePane

In this article I will demonstrate how to make a nice looking layout section on your XPages which goes well with OneUI

Introduction

I have a requirement to lay out a form into sections with headers which “looks good” within the OneUI framework. There are many ways I could do this but the reason I chose dojo.TitlePane was because of the original requirement to make “collapsible sections” and I am already using OneUI and wanted to conform to that look and feel.

Demonstration

The collapsible and non-collapsible sections are demonstrated here

Creating a collapsible section

Could not be easier. We add the script tag to “require” the loading of the titlePane library and then tell the web page which “div” elements we want to be TitlePanes. The dojoType=”dijit.TitlePane” tells the dojo code on page load to convert this div to a nice looking TitlePane.

<script type="text/javascript">
	dojo.require("dijit.TitlePane");
</script>

<xp:div id="titleChildren" dojoType="dijit.TitlePane" title="Collapsible Pane - Click on me">
	HERE IS YOUR CONTENT
</xp:div>

And you fill your content into the <xp:div> section – couldn’t be easier!

Collapsible dojo.TitlePane
Collapsible dojo.TitlePane

Creating a non-collapsible pane

And then my requirements changed and the section had to be non-collapsible – of course……

So I had to come up with a simple way to turn what I had into the new requirement.

There is a parameter on the TitlePane “toggleable” which when set to false dictates that the title bar cannot be clicked on and there is no mouse over color. Don’t hurt yourself but here is the dojo API documentation for the TitlePane

<script type="text/javascript">
	dojo.require("dijit.TitlePane");
</script>

<div id="titleChildren" dojoType="dijit.TitlePane" class="noToggle" title="Collapsible Pane - Click on me" toggleable="false">
	HERE is the text
<div>

In this case I used a <div> and not an <xp:div> so that it will work in R<8.5.3. If you have 8.5.3+ then you can add the <attr> toggleable to your <xp:div>.

The last thing we need to do is to add a CSS to hide the expandable icon

<style>
	.noToggle .dijitArrowNode {
		background-image: url("") !important
	}
</style>

so there we have it

Non-Collapsible TitlePane
Non-Collapsible TitlePane

Demonstration

The collapsible and non-collapsible sections are demonstrated here