XPages and Me

My Journey into XPages Development

Replicating the Notes Client “Allow Values Not in List” function used by Dialog List and Combobox on a XPage form (Part 2 – How to use the Custom Control on your form)

In part 1 I showed you how to create the Custom Control that you can use on any of your XPages form, where you’d like to give the user the ability to add values that might not be in the list of keywords.

Now I’ll show you how to use this Custom Control.

Using the Custom Control for a multi-value field

Open the Custom Control / Xpage containing your form and find the field for which you’d like to use this functionality. In this example, I am using a Dojo Text List Box for the field and a Value Picker for the Keyword selection. Both controls are part of the OpenNTF Extension Library, but the Custom Control can also be used with the regular set of controls.

Image 5

From the list of Custom Controls in your “Controls” panel, simply drag and drop the Custom Control below the field and value picker:

Image 6

Now, we need the set the values we’d like to pass on to the Property Definitions we defined in Part 1. Select the Custom Control and the “Properties” tab, select the tab “Custom Properties”:

Image 7

The first property is the data source. Even though I selected “Data Source Picker” as the editor for this property, we are going to pass on the data source thru JavaScript. The reason being that sometimes selecting the data source with the “Data Source Picker” won’t actually pass on the data source, causing issues and error messages. Using JavaScript to pass it on works all the time. So, just click on the blue diamond beside “oUIDoc” and select “Compute value…”:

Image 8

In the script editor that’ll pop up, simply type in the name of your data source (in my example it is oDocFirm):

oDocFirm

Close the editor and move on to the next property. Enter your labels for the toggle link and button, the name of field you want to tie your custom control to, the ID of the part of your form that you’d like to run a partial refresh on, once you added the new value and that your field is a multi-value field:

Property Name: Value Value passed on / entered thru Comment:
oUIDoc oDocFirm JavaScript Script Editor Even though we have the Data Source Picker to select the data source, it is safer to pass on the data source thru JavaScript.
sMultiValue Yes Selected from Combo Box
sFieldName FirmOtherLocations Typed into the property field  Name of the field as defined on your Notes form
sLinkLabel Please click here to add Locations not in the List Typed into the property field
sButtonLabel Add Location Typed into the property field
sPartialUpdate tblFirmData Typed into the property field In this example, the name of the table containing all the form fields.

After setting all the values, the “Custom Properties” list should look like this:

Image 9

Next, we need to set the option when the Custom Control should be visible, which should only be when the data source is in edit mode. Select the tab “Custom Control”, click on the blue diamond beside “Visible” and select “Computed value…”:

Image 10

In the Script Editor, enter the following SSJS (again, my data source is called oDocFirm):

oDocFirm.isEditable()

Close the Script Editor and we are done with the Custom Control settings.

In order for this to work properly, we need to add the field, we tied the Custom Control to, as a Value List source for our Data Picker. The Custom Control we’ve created doesn’t actually add the values to the list of selectable values but to the actual field. If we don’t add the field as a Value List source, the values the user added won’t show up in the list of selectable values and, if the user selects additional values from the Data Picker, it will override the existing data of the field and all values added manually will be gone.

In my example I use the xe:simpleValuePicker and the values for the Data Picker come from a keyword document and I am using the following SSJS code to read the values from the keyword document:

//Declarations
	//Notes Objects
	var oVWKeywords:NotesView = database.getView("$vwSYSLookupKeywords");
	var oDocKeyword:NotesDocument = oVWKeywords.getDocumentByKey(".States", true);

//Check if we found the Keyword document.
//If so, we pull the information from the profile document
	if(oDocKeyword != null){
		oDocKeyword.getItemValue("iTxtsKWValues");
	}
	else{
		"Keyword Document not found.";
	}

We need to modify this SSJS to also include the values of the field “FirmOtherLocations”. Select the Data Picker and on the “Properties” tab open the tab “All Properties”. Under “basics” expand the property “dataProvide” and click on the blue diamond beside “valueList” and select “Computed value…” to open the Script Editor:

Image 11

Change the code to the following:

//Declarations
	//Notes Objects
	var oVWKeywords:NotesView = database.getView("$vwSYSLookupKeywords");
	var oDocKeyword:NotesDocument = oVWKeywords.getDocumentByKey(".States", true);

	//String
	var sValueString:String = "";

//Check if we found the Keyword document.
//If so, we pull the information from the profile document
	if(oDocKeyword != null){
		sValueString = @Implode(oDocKeyword.getItemValue("iTxtsKWValues"),",") + "," + @Implode(oDocFirm.getItemValue("FirmOtherLocations"),",");
		@Unique(@Explode(sValueString,","));
	}
	else{
		"Keyword Profile not found."
	}

Note: Obviously your way of providing values for the Data Picker is going to be different from the example here. Just modify your way to include the values from the field.

Close the Script Editor, save your Custom Control / XPage and you are all set. As you might notice, I am working with @Implode / @Explode rather than arrays. I ran into some issues using arrays (i.e. Validations wouldn’t work right) and went on to use @Implode / @Explode.

Using the Custom Control for a single value field

This works exactly the same way as described above. However, for the Custom Property “sMultiValue” you’d select “No” instead of “Yes” and the way you provide the list of selectable values doesn’t need to be changed.

I hope you like this functionality and I’d like to hear from you if you were able to use it in your application, how it worked for you and if you ran into any problems.

Thank you.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: