Skip to main content link. Accesskey S

The useful resource for IBM Lotus Domino XPages development

Submit Search

Home > Server JavaScript > Work with documents and fields on the XPage
is maintained by 
Julian Buss.
You can hire me.

Work with documents and fields on the XPage

ShowTable of Contents

Get and set a field on the XPage

Server JS


Note: you cannot access or set fields with visible=false. If you want to work with a field, but don't want to display it, give the field a CSS class with "display:none".

Get submitted value before validation


Client JS


Get a computed field's value:


(thanks, Jerry Shelly!).

Access backend Notes document

Fields on the XPage are bound to a datasource. If the datasource represents a Notes document, you can access that with:

var doc:NotesDocument = datasourcename.getDocument();

Note: the variable "doc" is typed with "NotesDocument" here so that the IDE can give us a help for properties and methods.

Note: use datasourcename.getDocument(true) to get a backend document which has the changes which were applied to the UI document (kind of NotesUIDocument.refresh).

To work with a field, you can use

var doc:NotesDocument = datasourcename.getDocument();
doc.replaceItemValue("somefield", "somevalue");

Or to get a field which is in the backend doc but not on the XPage:

var v = datasourcename.getValue("fieldname");

Work with a document in the click event of a submit button

You can access the document and set fields as described above in the onClick event of a submit button.
But you have to redirect to another XPage after that by yourself using context.redirect() then.

Run a agent on document save

Something like the "WebQuerySave" agent in classic domino development. In datasource -> querySave event run

var agent:NotesAgent=database.getAgent("agentname");;
Im Agent bekommt man das Dokument dann via notesDatabase.GetDocumentByID( NotesAgent.ParameterDocID )

In the agent you get the noteID of the saved document with

set session = new notesSession
set database = session.currentDatabase
set agent = session.currentAgent
set doc = database.getDocumentByID(agent.parameterDocID);

Check for edit mode and set edit mode


returns true if is in editmode.

To set a mode the the "current" document, you can use


With the possible parameters "edit", "readOnly", "autoEdit" and "toggle".
(Thanks to Michelle).

To set mode for a specific document data source, use

context.setDocumentMode(String nameOfDataSource, String mode)

First parameter is the name of the document data source as string (!), not the data source variable itself!
Second parameter is "edit", "readOnly", "autoEdit" or "toggle".

if the context.setDocumentMode() method does not work for your for some reason, you can use this:

function setEditMode(doc:NotesXSPDocument, editmode:boolean) {
	try {
		var cl:java.lang.Class ="");
		var method:java.lang.Method;
		var paramTypes = new Array();
		paramTypes[0] = java.lang.Boolean.TYPE;
		method = cl.getMethod("setEditable", paramTypes);
		var params = new Array();
		params[0] = new java.lang.Boolean(editmode);
		method.invoke(doc, params);	
	} catch (e) {
		print("setEditMode error: "+e);

Update 15th march 2011: code updated since the old cold didn't worked in 8.5.2 anymore. This function uses undocumented features and may break in future versions of Domino.
Use context.setDocumentMode() if possible.

As an alternative, you can use the tip from John Mackey from our blog:

var url=view.getPageName()+"?action=editDocument&documentId="+document.getNoteID();
context.redirectToPage(url, false);

Check if a field is disabled


returns true if the field is disabled.

Set fields in backend document in QuerySave event

XPage -> events -> Datasource-Name -> querySave: use

Datasource.replaceItemValue("fieldname", "value");

instead of

Datasource.getDocument().replaceItemValue("fieldname", "value");

Use dynamic value binding for a field

( Discovered by Tommy Valand )
You can change / set the value binding for a field at runtime:

var application = facesContext.getApplication();
var scopeKey = "exampleKey"
var valueBinding = application.createValueBinding( '#{viewScope.' + scopeKey + '}')
getComponent( 'id-of-a-field' ).setValueBinding( 'value', valueBinding );

(In this example a viewScope field is used for value binding.)

Define dynamic value binding for a field at development time in the XML source

In the XML source of your XPage, you can write something like this:

<xp:inputRichText id="rtBody" 

which would bind the RichText field to the 42nd field of the document datasource "dominoDoc". While using an index number here is of limited usage, you can also use a fieldname in the brackets:

<xp:inputRichText id="rtBody" 

And finally you can use EML syntax to dynamically compute a fieldname, for example using an applicationScope variable:

<xp:inputRichText id="rtBody" 

Set a group of fields to readonly

You can use a xp:panel to wrap a group of fields and set the readonly property to all of them at once:

<xp:panel disableTheme="true">
... fields ...

Note the disableTheme="true" attribute which prevents rendering a div-tag for the panel. That means you can for example wrap some table rows inside such a panel, too.

Check if a panel is readonly

If you want to hide some components inside a panel depending on it's readOnly state, you can read the state with:

Use custom converter to change submitted and displayed value of a field

Add a xp:customConverter to a field and implement the getAsObject and getAsString properties.
getAsObject is called when the user gave a value, bevore the value is stored to the appropriate NotesItem.
getAsString is called before the value is displayed in the field.

There is the standard variable "value" which contains the actual value of the field.

Example: limit the value of a field to 20 chars:

in getAsObject:
@Left(value, 20)

in getAsString:

(in this exampel we don't want to alter the displayed value but the stored value, therefore we just return the current value in getAsString).

Set different style to required and invalid fields

Required fields get the attribute aria-required=true and invalid fields get the attribute aria-invalid=true automatically.
You can style them with CSS with code like this:

[aria-invalid=true] { background-color: #fee; border-color: red; }
[aria-required=true] { background-color: #ffe; }

Found by Tommy Valand

Dynamically change data binding of a field with SSJS

You can change the data binding for a field (component) dynamically with SSJS.
For example in a custom control, you can define a custom parameter to define the data binding for a field inside the custom control.

Example code for the "afterPageLoad" event of a custom control:

if (compositeData.fieldDataBinding) {
	var application = facesContext.getApplication();
	var valueBinding = application.createValueBinding( "#{"+compositeData.fieldDataBinding+"}");
	getComponent( 'fileUpload' ).setValueBinding( 'value', valueBinding );

In this example, the custom control has a custom property "fieldDataBinding" and a file upload control with the id "fileUpload".
The file upload control has a default data binding to "document.Body", but when the "fieldDataBinding" custom paramter is set, the default data binding will be changed.

In the XPage, the custom parameter can be set to "document.files" or any other EML string.

Hold documents in memory

You store documents in memory, for example to do some caching. But you cannot do this with standard Notes objects, you need the DominoDocument/NotesXSPDocument wrapper.
See this blog entry from Frank van der Linden.
Created by Anonymous on May 22, 2009 12:10:44 AM

Thank you, very useful :)

Created by Anonymous on Jan 26, 2010 9:29:06 PM

Could I suggest adding to the "Client JS" paragraph of the "Get and set a field on the XPage" section the use of


to access a Computed Field's value.

Thank you for a wonderful XPages resource. Jerry Shelley.

Created by Anonymous on Mar 25, 2010 11:07:28 AM

I created a standard control for all addresses (street, town, country and so on)

I want now use it into various Xpages working on various type of documents (customer, persons, commands, projects) needing an address.

How can I bind the document fields (they may have a different name from those of the control) and the fields of the control ?

I try to add compositeData to the control giving the names of the document source fields. But it doesn't work.

As the control is embedded into different Xpages, I want to be sure that the document binded in the control is the same one binded in the xpages (the submit button is in the xpage)

If I get the notes document twice (once in the control and other in the xpage) , I guess I will get update conflicts, no ?

And, if its possible this way, how can I give the good name fields to the control ?

Thanks for response if there is...

Pierre Frappé

Created by Julian Buss on Apr 11, 2010 8:28:53 PM

one possiblity is to use the "currentDocument" data source, it's always there and points to the current document data source.

If you have more than one document data source on your xpage, you can throw it into a scope variable and get it back from the scope in your custom control.

Created by Anonymous on Sep 9, 2010 8:52:58 PM

I've just been bitten by overuse of getComponent().

I was running an SQL Query in a Hidden Input field, and then accessing the results in several Computed Fields. But every getComponent causes a re-execution of the code in the Hidden Input field! No wonder my page was taking ages to load.

I'm sure this is documented elsewhere, but I can't quite find it at the mo.

Hope this helps someone not make the same misktakes as me. Jerry Shelley.

Created by Anonymous on Nov 16, 2010 12:18:22 PM

I simply used :


and seems working to put current page document in edit mode.

Possible parameters are: edit, readOnly, autoEdit, toggle.


Created by Julian Buss on Nov 29, 2010 11:40:22 AM

thanks, I added that!

Created by vijayasree on Mar 28, 2011 10:54:37 AM

Thank you very much this helps me alot

Created by Andreas on Apr 3, 2011 2:16:46 PM

THX for nice post. One question.

Can i load an additional document in a xpages from another database and work with this field to add some additional information ?

Created by Bunk on May 31, 2011 9:33:36 AM

This's very nice post

Created by Terry on Jun 15, 2011 12:26:35 AM

I've tried the 'Define dynamic value binding for a field at development time in the XML source' inside a repeat control containing a Edit Box. What I find is the control renders in a instead of an tag when the value computes the item name.

So if the formula is value="#{dominoDoc['field1']}", the HTML displays an element. However, if the formula is value="#{dominoDoc['field'+rID]}" where rID is a string element, the HTML displays in a tag.

I have tried many variations on this form, and nothing seems to work. Am I being dense? or is this a problem?

Created by Hitesh Basera on Aug 5, 2011 6:59:32 PM

Thanks a greaqt help...

Created by Arunthathi on Mar 13, 2012 1:13:33 PM

I want to replace the images in view while editing that document.

Created by vijayasree on Apr 2, 2012 9:39:42 AM

Can you provide the java script code for ui document collection

Created by padma priya on Apr 20, 2012 4:05:20 AM

thankyou:) very useful

Created by Ronaldo M. Martinez on Jun 5, 2013 11:37:54 AM

Nicely done.

Thanks. :)

Created by Bill Fox on Sep 26, 2013 12:54:18 AM

Not sure I understand the Access Notes Back end section. If I read it correctly var doc:NotesDocument = datasourcename.getDocument(true); refreshed the backend document with any changes that were made to the datasource, but it seems that is what happens with var doc:NotesDocument = datasourcename.getDocument();

I have made some changes to the doc and I need to refresh the datasource with them. IS that what the var doc:NotesDocument = datasourcename.getDocument(true); really does?

Created by 83.70x33 on Feb 19, 2014 8:57:45 AM

Add Comment

How to take your XPages App to the iPhone, iPad, Android: use Domino To Go!
Do you look for an XPages Workflow solution? Take YouAtNotes Workflow.