« Part 2; Programming details on Icon and Images - Enumerating files | Main| First impressions of Denver TFD-1906, a 19" LCD TV with DVD player »

Part 3: Using DXL to create imagery in documents

Tags: Lotus Notes Software DXL LotusScript
In this third article about the Icon and Images database (see this article), I will cover how I use DXL to create the imagery in Notes documents.
This is the third article explaining how the Icons and Images database was built. In order to have maximum benefit of this article, please read the first article to get an overview. The second article dives into how I find all files to import. In other words, this article will process files found in the previous step.

With "imagery" I mean this;

A picture named M2

This Notes document contains of several images, all with so-called action links  enabling the user to click on an icon. This will start an agent, showing the user the following dialog box;

A picture named M3

By using an action hotspot, I separate what I want to do from the actual click operation when the user clicks on an icon. I can easily add additional features to my palette of actions.

The size-information just beneath the icon contains a popup hotspot. All this can easily be created manually, but is not just straight forward if you want to create it programmatically.

How do I do it then? The steps are;
1. Create a document with a dummy table manually! This will make sense in a minute!
2. Export the dummy document as DXL to a file.
3. Analyze the exported DXL file to understand the construction of DXL
4. Recreate an DXL file similar to the one Notes exported in the second step.
5. Use the NotesDXLImporter to import the handmade DXL file from the previous step.

Below I will dive into each of the steps above!

1. Create a dummy document with your  design. This is the template

In order to be able to create anything programatically, we need to know how to do it manually! The best way to do this in my opinion, is to let Notes tell me  how it wants things to be done. Therefore I make a template document, export it to DXL, and later try to programmatically create a DXL file similar to how Notes exported it. You could of course read the DTD, which describes all DXL rules in raw details. However, its much easier to make Notes teach me the correct syntax.

The first step is therefore to create a simple form with just a title field and a Body richtext field. Using the simple form, I create a document with the table as I want it to look and work.

A picture named M4

The most important idea when you create template-document is to use all the bells and whistles you need. Remember, you will let Notes show you how its done later! Use images, hotspots, code and formatting as you like it. When I for example created the popup hotspot text, I entered some easily recognizable text to ease the identification later in the exported DXL.

A picture named M5

I use use the similar idea to create the action hotspot when I click on the icon itself. For the time being the agent behind the action hotspot doesn't necessarily need to do anything sensible. Also note that I have some table cells with  images and actions, an some empty  cells too. The reason is that the DXL might be slightly different between filled- and empty tablecells. You need to know what Notes does with empty cells.

2. Export the template to DXL

Now you are ready to let Notes teach you how the DXL should be built! The immediate problem is to get the document exported! For some strange reason, the Designer does not include document  exporter, only a exporter tool for the design elements such as forms. Luckily there are some options, where I will dive into the LotusScript-way of doing it. You could also take a look at the DXLEXPORT tool supplied or even use the API. Below you see the code behind my agent, which is set up to export the selected documents within a view;

A picture named M6
There is nothing special about the code above. It first asks where the user want to store the DXL file with the BrowseForCatalog-function call. This function is stored within a script library "Browse For Catalog Processing". The code then gets the collection of unprocessed documents (in other words here, the selected  documents) and feeds that collection into the ExportSelectDocsAsDXL-function. The ExportSelectDocsAsDXL-function is stored within the "Import Processing" script library. Below we take a look at the ExportSelectDocsAsDXL function;

Function ExportSelectDocsAsDXL(session As NotesSession, _
db As NotesDatabase, _
coll As NotesDocumentCollection, _
pstrExportPath As String, _
pstrExportFileName As String) As Integer
        Dim strFileName As String
        Dim exporter As NotesDXLExporter
        Dim strTempDir As String        
        Dim stream As NotesStream
        Dim strMsg As String
        Dim doc As NotesDocument
        On Error Goto ErrorHandler
        Set stream = session.CreateStream
        ' Ensure path has correct ending        
        strTempDir = pstrExportPath
        If strTempDir = "" Then strTempDir = "C:\"
        If Right(strTempDir, 1) <> "\" Then strTempDir = strTempDir & "\"
        strFileName = strTempDir & pstrExportFileName
        ' Open the output stream (in other words, the DXL file )....
        If Not stream.Open(strFileName) Then
                Messagebox "Cannot open " & strFileName, 16, "Error"
                ExportSelectDocsAsDXL = 1
                Exit Function
        End If
        ' Empty it if the file already exists ...
        Call stream.Truncate
        ' Set up the DXL exporter to work with the input collection of documents and the output stream
        Set exporter = session.CreateDXLExporter(coll , stream)
        ' Set some DXL Exporter options
        exporter.ConvertNotesBitmapsToGIF = True
        exporter.OutputDOCTYPE = True
        ' And export the documents in the collection
        Call exporter.Process
        Call stream.Close ' EXTREMELY IMPORTANT, otherwise the file will be truncated at 65535 bytes!!!!!
        Exit Function
        ' Print some detailed error messages if we have a crash!
        Const LSI_THREAD_PROC = 1
        Const LSI_THREAD_CALLPROC=10
        Dim messageString As String
        messageString = Now & "-" & "Error in ExportSelectDocsAsDXL;"  & _
        Getthreadinfo(LSI_THREAD_CALLPROC) & ", Erl()=" & _
        Cstr(Erl()) &  " ,Err()=" & Cstr(Err()) & " ,Error()=" & Error()
        Msgbox messageString
        Resume Next
End Function

The concept of the code above is to let the DXL Exporter export the documents referenced by the input collection (remember, the selected documents in the view...) with an output stream. This is done in two steps, where the code above opens a NotesStream first. Note how the code also remove any potentially existing content with the Truncate-method. Then the code create a connection between the input collection of documents and the freshly opened NotesStream with the CreateDXLExporter method. It sets some options and then kick off the export operation with the Call exporter.Process line. Note that DXL exporting take far more time than DXL importing, due to handling of potential images, attachments and objects..

This article continues in this article.


Gravatar Image1 - small type in explanation..
"CreateEXLExporter method"

Gravatar Image2 - Thanks! Article updated!

Post A Comment