Jeremy Hodge, Jan 17, 2011 3:27:23 PM
Resource bundles are .properties files that you can include in your XPages design that allow you to set properties/values for your app, without the need to modify the design or recompile your XPages application when the values change.
To create a properties file, you open the Package Explorer view in your IDE, expand the WebContent/WEB-INF folder and create a new file, naming it something.properties, such as"myapp.properties" for example. Then you edit the file, and enter any name/value pairs you want. For example, here is an application.properties file I created for an application I am working on now:
# application.properties
# Defines properties and behaviors for the general application
#
# usually, here i put a description of the settings and possible values
# to help the user configure the app, but I've ommitted it for brevity.
# General Settings
appName=WebSpaceX
namePickerNsf=/names.nsf
# Widgets
enableSametime=true
sametimeUrl=http://stweb.bleedyellow.com/stwebclient/popup.jsp
# Welcome Page
enableWelcome=true
welcomePage=welcomePage.xsp
welcomeClosable=true
welcomeTabTitle=Welcome
Then, in my XPage, I define a bundle resource type to access the values within this properties file, like this:
Now I can reference the values contained in my application.properties file from within any javascript expression like this:
application['appName'] + " Administration Console"
}]]>
The important piece there is application['appName'] -- That's right, all the values within the property file become a named member of an object with the named I specified in the var attribute of my xp:bundle definition.
Depending on how tightly you integrate this into your application, you can allow your user to now easily control settings, values, properties and more of your XPages application, without ever modifying the design or creating computationaly more costly (and riskier, since its easier for users to access/modify/corrupt) configuration documents within the database.
Go ahead, give Resource Bundles and try, and Happy Coding!
15 responses to Using Bundle Resources to Super User Charge Your XPages Application
Mirek Navratil, February 7, 2011 2:21 PM
Really valuable piece of information (as usual). Looking forward for the upcoming entries.
Sean Cull, January 27, 2011 6:38 AM
@Patrick, we use them in the Resources/Files section and they work fine.
<xp:bundle src="/db_settings.properties" var="dbsettings"></xp:bundle>
@Rods point is an interesting one about design refresh - I must try that. In our case we have notes documents that are used to define the contents and then populate the file so we would wouldn't loose any data but we would have have to run that process.
The article link in the first comment explains how we use it. it is also in the Designer Wiki
http://www-10.lotus.com/ldd/ddwiki.nsf/dx/Creating_an_Xpage_resource_file_via_DXL_without_a_temporary_file
Rajeev Menon, January 25, 2011 12:20 PM
Excellent post Jeremy. Taking time to answer the questions of readers is something that only few bloggers do. Keep up the good work.
Jeremy Hodge, January 23, 2011 5:24 PM
@Patrick I am going to cover how to get these files in java, etc in my next post, and how to read/write to them using that. I'll cover some best practices there. As for hosting them in the File Resources of designer, i've never tried, but my first inkling is it may not work ... not sure. They loading of the files is semi-automated and the underlying code may expect the files to be in the WebContent folder tree. I'll have to experiment to see.
Patrick Kwinten, January 23, 2011 7:32 AM
Is there any difference in files when you place them in the Resource \ Files section?
What are best practices in placing values for lookups in these properties files?
Rod Weaver, January 20, 2011 2:37 PM
Far out! I just tried it and it worked! But it raises another question: is there anyway to protect the .properties file when I refresh from a dev environment? Some of these "variables" would be different in production than in dev. I don't see a "Don't refresh" option anywhere.
Another question: you seem to indicate that users are able to control these settings. How is that done outside Designer? Can it be done from the browser?
Thanks.
Jeremy Hodge, January 20, 2011 2:15 PM
Yes, you can use the java.util.Properties class to load/read/write/save a properties file. See http://download.oracle.com/javase/6/docs/api/java/util/Properties.html
J Cooper, January 19, 2011 8:41 PM
Are there any java calls to change the values in the properties file?
J Cooper, January 19, 2011 4:39 PM
Are there Java calls you can use to change the values in the properties file programmatically?
Jeremy Hodge, January 19, 2011 3:42 PM
@Rod - Yes, think of resource bundles as global settings for your application. As mentioned above, they can be used for more, like localization, and you can even use different sets of bundles based on certain settings. You can replace your documents that hold settings with a resource bundle pointed to a .properties file to retrieve all your settings. They are less costly to use than looking your values up in documents, etc. Conceivably, you could use the xsp.properties file, but I wouldn't recommend it, I think its good practice to have a separate file, just because their are fields and values in xsp.properties that affect other things that you do not control, and you would want some separation there. I don't know of any more basic level documentation that exists beyond what I have included here. There are some articles about this on the ldd wiki, mostly around localization [ http://www-10.lotus.com/ldd/ddwiki.nsf/xpViewRecent.xsp?searchValue=xpages+resource+bundle ] ...
Rod Weaver, January 18, 2011 3:17 PM
Sorry if my question is ignorant. I've never even heard of "resource bundles" before, much less understand them.
So what are we doing here? Are we setting "global variables"? Is this like a "database defaults" for XPages? For instance, in one of my apps, I have default documents that hold parameters for lookups (server, path, filename, viewname, etc). Would the .properties file be able to replace that so that when I write my code to access that lookup I would just get it from the .properties file?
Second Q: do I need to create a separate .properties or can I just use the xsp.properties?
Third Q: Is there any documentation out there that covers the use of these resource bundles at a pretty basic level?
Jeremy Hodge, January 18, 2011 1:06 PM
@Stephan - Yes, planned subject for another post :)
Stephan H. Wissel, January 18, 2011 4:58 AM
Isn't there also a mechanism that allows you to have multiple bundle files with different language extensions and the runtime automatically picks the right one based on Browser (or programmatic) settings?
Baiju Thomas, January 17, 2011 5:23 PM
Jeremy,
Thanks for posting.. As usual another very usefull blog entry from you..
Sean Cull, January 17, 2011 4:00 PM
This article on using DXL to manipulate file resources in XPages applications may be useful to anyone interested in allowing users to manipulate the file properties
http://www.seancull.co.uk/public/seancull.nsf/dx/sntt-modifying-an-xpage-resource-file-via-dxl-without-a-temporary-file.htm
Sean