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.
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;
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;
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.
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.
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;
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!
ErrorHandler:
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.
With "imagery" I mean this;
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;
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.
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.
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;
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!
ErrorHandler:
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.
| Permalink | 
Comments
"CreateEXLExporter method"
Posted by Art At 00:45:21 On 20.05.2008 | - Website - |
Posted by Robert Ibsen Voith At 14:44:32 On 22.05.2008 | - Website - |