wissel.net :: Domino Design Code Injection

Version	Support end
5.0
6.0
6.5
7.0

In an earlier entry I discussed how to maintain custom system databases. It works well when you add design elements or change them wholesale. However it doesn't work very well when you tweak design elements. Something like: adding one action in a form or using a different subform for a specific task. Once an updated system template is available, you have to go back and recreate all your changes in your template.
This entry discusses how to automate these little fixes. There are a number of moving parts involved:

Export the design element using DXL. (You might need to set NotesDXLExporter.RichTextOption = RICHTEXTOPTION_RAW to make sure the fidelity of forms is maintained)
Locate the entry/replace point. The best mechanism for that is XPath
Locate the new code. This could be as easy as provide a string with the XML Snippet to pointing to an existing design element elsewhere. (We would use XPath again)
Perform the insertion/replacement. We will have the option: before/after/replace
Write back your changes and test it

What type of code injections come to my mind:

Add an action to a form/view
Add a subform to a form
Replace a validation formula in a field
Insert a script library and a custom class into a form
Add a field at the top or bottom of a form (our favorite hidden fields $$Return anyone

Understanding DXL and XPath is key to make this work. As a Domino developer (and you are one? Otherwise all this might sound Greek and Latin to you) you have seen DXL and its description in the help file. XPath might be less familiar. In a nutshell: XPath is to XML what SQL is to relational data. When you develop XML Stylesheets (a.k.a. XSLT) you use XPath selectors to define your template matches. XPath is a set language, so you better remember your kindergarden days (give me all shapes that are blue, triangle and big). It is easy to get an overview and to get started and can get as complex as you can take it. One little caveat (you see Latin is creeping it): XPath is case sensitive
Some simple examples:

* selects ANY element.
/ selects the root element, basically before any tags in the XML
/database/form/actionbar selects the actionbar elements in all forms in our XML
/database/form[1]/actionbar selects the actionbar element in the first form in our XML
/database/form[@name='Message']/actionbar selects the actionbar element in the form Message in our XML
/database/form[@name='Message'] //field[@name='Subject'] /code[@event='defaultvalue'] /formula Select the default value formula for the field "Subject". Please note the double slashes in front of the field. They are intentional. One slash says: a child, two slashes says any decendant down the document. Also: no spaces before/after the slashes. They are here for readablitity only.
//field[code/@event='inputvalidation'] Any field that has an input validation formula

You get the idea. You want to have a good XML editor.

First you need a routine that can pull out a design element and write it back. Here is the example for a form:


Sub InjectCodeIntoForm(formName As String, xPath As String, codeSnippet As String)
	
	'Errorhandling omitted for clarity
	Dim s As New NotesSession
	Dim db As NotesDatabase
	Dim f As NotesForm
	Dim out As NotesStream
	
	Dim ex As NotesDXLExporter
	Dim importer As NotesDXLImporter	
	Dim col As NotesNoteCollection
	
	'The strings holding the DXL
	Dim rawDXL As String
	Dim resultDXL As String
	
	Set db = s.CurrentDatabase
	
	'Create a Note collection and add the form
	Set col = db.CreateNoteCollection(False)
	Set f = db.GetForm(formName)	
	col.BuildCollection
	Call col.Add(f)
	
	'Create the exporter and run the stuff out
	Set ex = s.CreateDXLExporter
	Set out = s.CreateStream
	ex.RichTextOption = RICHTEXTOPTION_RAW 'This is to get rawitems for untranslatable stuff
	ex.ValidationStyle = VALIDATIONSTYLE_NONE 'To make sure we don't generate a schema reference
	Call ex.setinput(col)
	Call ex.setOutput(out)
	ex.process
	
	'Reset the stream and manipulate the DXL
	out.Position = 0
	rawDXL = out.ReadText
	resultDXL= injectCode(rawDXL, xPath, codeSnippet)
	
	'Write it back
	out.Truncate
	Call out.WriteText(resultDXL)
	out.Position = 0
	Set importer = s.CreateDXLImporter
	
	'Having the right importer options is important
	importer.CompileLotusScript = True
	importer.ReplaceDBProperties = False
	importer.ReplicaRequiredForReplaceOrUpdate = True
	importer.ACLImportOption = DXLIMPORTOPTION_IGNORE
	importer.DesignImportOption = DXLIMPORTOPTION_REPLACE_ELSE_IGNORE 'We only want to update the current form
	importer.DocumentImportOption = DXLIMPORTOPTION_IGNORE 'This is for design only
	importer.ExitOnFirstFatalError = False
	
	'Standard import execution
	Call importer.setInput(out)
	Call importer.setOutput(db)
	On Error Resume Next	
	Call importer.Import
	
	Msgbox importer.log
End Sub

This LotusScript was converted to HTML using the ls2html routine,
provided by Julian Robichaux at nsftools.com.

Now we need a pice of code that can do the transformation of the DXL. Unfortunately the LotusScript XML Parser is lacking, so we use some Java code to perform this step. After creating the class (without parameters, for LS2J comfort, we need to set the DXL as Document and then call injectCode with 3 parameters: xPath expression, codeSnippet to insert (must be an XML fragment) and insertion type (before/after/replace). See Part 2 for the Java code.

Comments

1 - Thanks! I once had problems with XPath and found a couple of video tutorials on the issue. When the problem with XPath was settled, I could go futher learning in detail your article Emoticon

Posted by XPath At 18:47:36 On 06/07/2010 | - Website - |

2 - Thanks! Great article, but i have one problem. I need to change design of mail\username.nsf file which located on the server. So i cant change UI for it (Under admin account it works). May be it because of my access level? Anyone knows how to solve this problem?
Or what permission needed for such action?

Posted by maksym At 22:01:34 On 02/01/2011 | - Website - |