A property is a string value identified by a name. Properties give a powerful way of parameterizing aspects of your XPages application. They can be set at a wide variety of levels to override functionality. We try to cover those areas in this article from top to bottom.
You may see some existing properties that start with xsp. These are used by the XPages runtime and should not be altered. Everything else is custom and can be consumed by the application.
To try this out create an XPage in an application with just some text, and a computed field:
When run, as-is, it presents a blank string. This property is not set anywhere and so has no value.
There is an alternate API for getProperty() that allows you to specify a default value. If all other searches fail, that is the value that will be used. If you change your computed field code to
and refresh your application, you should now see that text. This text will only appear as a default for this individual function call!
Server Wide Settings
On your Domino server - in the xsp\nsf directory for Release 8.5, in the Data\properties directory from Release 8.5.1 - is a file xsp.properties. You can set values in here and they form the topmost fallback for properties. Add the line here:
foobar=Server Wide Property
(You may need to restart the http task on your server.) When you reload your application, it now displays that text. This same code anywhere on any XPage served up by this server will see that setting.
This file is using the Java properties file format, as described here: http://java.sun.com/javase/6/docs/api/java/util/Properties.html#load(java.io.Reader)
Application Wide Settings
Analogous to the server xsp.properties file, there is also an application xsp.properties file. This is not directly shown in the Designer UI though. If it is there, however, we can do a file search and find it. The problem is that if all of your settings are defaults, then it is not there. So to ensure it is there, do the following.
Right click your application in the application browser, select Application -> Properties. Switch to the XPages tab. Make some trivial change like changing client validation. Chose File->Save. Reset the setting to the original, and do File->Save again. This will force the creation of the xsp.properties file. Be sure to close the properties editor when you are done with it. It will preserve changes you make to the xsp.properties file directly, but only if the property editor is closed while you do it.
To find xsp.properties, we do a search. Select Search -> File. Enter no text into the "Containing Text" field, a file name pattern of "xsp.properties", and select a scope of "Enclosing projects". Your dialog box should look like the following:
When you click "Search" you should get a results panel that points to a xsp.properties file under WEB-INF under WebContent in your project.
You can double click this to edit it. Add a single line
foobar=Applicatio n Wide Property
When you refresh your web app, it should now display this text. It has overridden the server wide setting. This code, anywhere in this application, will produce this result.
Another method of setting properties is within a theme. If a property is not set in either of the xsp.properties files, it will look in the theme file. There is more to this, however. A theme can inhert from another theme. And themes can be defined in the application or on the server. Your application may use one theme file that inherits from another theme file. The property evaluation logic will examine the most directly referred to theme for a property setting. If it does not find it there, it traces the tree upwards to inherited themes looking for it. So if you application uses the default server theme, and a property is set there, it will use that property in preference to one, say, in the local xsp.properties file.
Create a theme in your application. Change the XML to look like this:
From the application properties, set your application to use the theme you just created. When you refresh your web page, you should now see the theme text appear.
These values are persisted over a session. You can reset them at run time by calling context.setSessionProperty(). Add to your form a button, and add the following code to your button:
context.setSessionProperty("foobar", "Button Setting");
When you load your application, you should see the new button, plus the text showing the theme setting. When you click the button, the text changes to what the button set. If you refresh your page, it's still the button text. This will persist until the "session" with the browser is over. This is usually after a set amount of time, or after you close the browser and open it again.
The UIViewRoot object also maintains a property list. Right now, setting a property value should be done programmatically but a future release of XPages will let property values to be added from the Object Inspector.
So that's it, from bottom to top. You can set settings at all sorts of different levels and use them to parameterize almost any aspect of your XPage application.