Type Ahead: The “Tokens” Property

In my Notes Client workflow applications, I use mail templates where the owner of the application can define the recipients and the content of the emails being sent out. The way it works is, I set up 2 keyword documents: One with a list of name-field names and one with field names. The user can then use the list of name-field names to select the recipients for the email and the field names to define so called placeholders. The placeholders then can be used in the subject line and body of the email template. During the generation of the email, say while submitting a new request, the placeholders are being replaced with actual values from the underlying document (i.e. Request Number, Requester, Description etc.).

This gives the user the ability to set up and change their emails as needed without having to change any code.

Obviously, I’d like to provide a similar mail template functionality in XPages and I was wondering if I could somehow use the type-ahead functionality to select and insert the placeholders in the subject and body. You see, in the Notes Client, the user clicks a button which opens a layer with the list of defined placeholders. The user selects one, clicks OK and the placeholder is added at the end of the text. If the user would like to use the placeholder in a different position in the text, he has to cut and paste the placeholder. Not very elegant but unfortunately no way around it.

If I could use the type-ahead functionality, the user could write the text and then trigger the type-head, providing the list of placeholders and select from it, adding it to the current position of the cursor.

This is where the tokens property of the type-ahead comes into play. Usually, when you use type-ahead, you trigger it by starting to type a word. The type-ahead gives you a list of suggestions, you select the value you want and that is it. To trigger the type-ahead again, you have to delete the selected word and start typing again.

The tokens property is like the multi-value separator you can select for text fields. As soon as you type the token you’ve defined (be it comma, semicolon etc.) the type-ahead will be triggered again.

In Notes, I put the placeholder word in between the percentage sign, which would look something like this: %REQUESTNO%. So, my thinking was, as a token that would trigger the type-ahead again I’d use space and in the type-ahead code I would check if the user entered the percentage sign and only then return the list of placeholders. And, what do you know, it actually works (I’ve tried it with edit boxes and multiline edit boxes).

So, here is how I implemented it:

Add an edit box to your XPage / Custom Control, select the Type Ahead section and change the following properties:

– Enable Type Ahead

– Mode: Partial

– Minimum characters: 1

Next, click on the blue diamond beside “Client separators”, select “Compute value…” and enter the following JavaScript into the prompt:

return ' ';

If you select “AJAX Type ahead” from the outline, you’ll see that we’ve just set the tokens property:

We stay in the “AJAX Type ahead” properties and make the following changes:

Under the section “data”, enter a value in the field “var”. This variable will then contain the entered value to be used for the lookup. I name my var “lupkey”:

Now set the field “valueMarkup” to “false”:

Lastly, we need to add the JavaScript code that will check the value of the var “lupkey” and if it starts with “%”, return the value list. In this example, I am doing a lookup to a keyword view and return the value of a multi-value field. Click on the blue diamond beside “valueList” and in the prompt, enter the following code:

//Declarations
	//Notes Objects
	var oView:NotesView = database.getView('$vwSYSLookupKeywords');
	var oDocKeyword:NotesDocument = oView.getDocumentByKey('.DBProfile', true);

	if(lupkey == '%'){
		oDocKeyword.getItemValue('iTxtTest');
	}

And you are all set. If you open your XPage in the browser, every time you enter a new word and it starts with “%”, you will be presented with a list of suggestions:

Demo video