| |
|
|
How can I include custom dialogs to allow users to enter filter criteria?
 Custom dialog boxes are used by the Integra Profile Creator to present the user with a dialog box on running of a particular Integra profile which is used to allow entry by the end-user of parameters that govern the export or import being done using that Integra profile. An example could be presenting a dialog box to allow the user to enter a date range resulting in Integra exporting only data that has met that date range. See the screenshot.
There are three ways of achieving this, both are utilising the Script Callback field in the Advanced tab of the Integra profile:
- Lotus Script (LS) Inputbox() function
- stats.ShowUserDialog(Formname,Dialogtitle)- only available in Integra 4.1 onwards
- Using custom dialogs with the NotesUiWorkspace.Dialogbox() method (versions of Integra up to and including 4.0)
NOTE: Do not place any of the following code into the CustomCode script library of the Integra database in an attempt to optimize performance since the code contains the use of UI functionality which, when included into the CustomCode library, will cause Integra's scheduled profile functionality to fail .
Lotus Script (LS) Inputbox() function
 A simple way to include a dialog box to be presented at runtime is to use the LS function Inputbox(). This function is similar to the Notes formula function @Prompt(), however, the @Prompt() function cannot be used in the various formula definition fields of the Integra profile as there is a limitation within LotusScript that does not allow any UI formula functions to be used when evaluated with LS at runtime. This is what Integra does with formulae defined in the profile.
So back to the Inputbox() function: the following example can be used with the example profile "Export Contacts" delivered with Integra that exports contacts stored in the NAB (Name & Address book) into an Excel spreadsheet. The following code using the Inputbox() function could be placed into the Script Callback field in the Advanced tab of the Integra profile to requests a from-to letter range for the export of contacts:
Const CB_INITIALISE = 3
Const CB_BFORREADNOTES = 6
Const CB_BFORREADCOM = 7
Const CB_BFORWRITECOM = 1
Const CB_BFORWRITENOTES = 8
Const CB_BFORCOMACTION = 5
Const CB_BFORNOTESACTION = 2
Const CB_TERMINATE = 4
select case stats.cbstatus
case CB_INITIALISE
from_range = Inputbox("Please enter the letter from which the export should start from", "Letter Range: From","A")
from_range = ucase(left(from_range,1))
if from_range = "" then
end if
' temporarily disable the Integra progress bar
If stats.pbar.enabled Then
Call stats.pbar.DisableProgressBar()
to_range = Inputbox("Please enter the letter which should be exported last", "Letter Range: To","Z")
' Call stats.pbar.EnableProgressBar() ' Integra for Notes 4.0
Call stats.pbar.EnableProgressBar(false) ' Integra for Notes 4.1+
else
to_range = Inputbox("Please enter the letter which should be exported last", "Letter Range: To","Z")
end if
to_range = ucase(left(to_range,1))
if to_range = "" then
end if
dim ltr_range(1) as string
ltr_range(0) = from_range
ltr_range(1) = to_range
stats.uservar = ltr_range
case CB_BFORREADNOTES
case CB_BFORREADCOM
case CB_BFORWRITECOM
if ucase(left(trim(stats.expdoc.lastname(0)),1)) < stats.uservar(0) then
' ingore document as it is not in range
' export.continue = false in the CB_BFORWRITECOM event will stop
' the export of the currently processed document
export.continue = false
elseif ucase(left(trim(stats.expdoc.lastname(0)),1)) > stats.uservar(1) then
end if
case CB_BFORWRITENOTES
case CB_BFORCOMACTION
case CB_BFORNOTESACTION
if not stats.savdoc is nothing then
else
end if
case CB_TERMINATE
end select
stats is one of Integra's runtime objects derived from the StaticVars object class. It provides global information regarding the import or export process and it also includes the property uservar of type Variant, which can be utilised to temporary store information to be carried forward from event to event (execution of the Script Callback code). It is similar to the use of a variable declared as Static, however this type of declaration is not available for Lotus Script executed at runtime and therefore we have provided this property in which one can store any type of information needed throughout the import or export process.
Using Custom Dialog Boxes
A more sophisticated method is to create custom dialog forms in the Integra database. As an example we created a form called "LetterRange" in the Integra database for the same Integra example profile mentioned above and protected it from being overwritten by the next update. Note that the form is created in the Integra database and not in the source database from which the data is to be exported or into which it is to be imported.
The form contains three fields SaveOptions, FromLetter and ToLetter which have the following default values, translation formulas and input validations:
SaveOptions
Type: Text; Default Value: "0"
FromLetter & ToLetter
Type: Combobox with the choice A-Z; Default Value: "A" / "Z"
Input Validation:
@If(FromLetter>ToLetter;
@Failure("<From Letter> has to be less or equal to <To Letter>");
@Success
)
The formula in the QueryClose event writes the user's input into two environment variables which can then be read once the user closes the dialog.
The code to be placed into the Script Callback field in the Advanced tab of the Integra profile will vary depending on whether you are using Integra for Notes 4.1 or any older version. The two available techniques are:
- Using the NotesUiWorkspace.Dialogbox() method
- Using the stats.ShowUserDialog() method
Using the stats.ShowUserDialog() method
Use this method only if you are using Integra for Notes 4.1 or greater.
Below is some example code to be placed into the Script Callback field in the Advanced tab of the Integra profile when using Integra 4.1 or greater:
Const CB_INITIALISE = 3
Const CB_BFOREXPORT = 10
Const CB_BFORREADNOTES = 6
Const CB_BFORWRITECOM = 1
Const CB_AFTERWRITECOM = 9
Const CB_BFORCOMACTION = 5
Const CB_BFORNOTESACTION = 2
Const CB_TERMINATE = 4
select case stats.cbstatus
case CB_INITIALISE
If stats.ShowUserDialog("CustomFormName","Title for the custom dialog") Then
' dialog closed with OK
' retrieve input from environment variables which have to be set
' in the custom dialog form
Else
' dialog canceled, discontinue export
export.continue = False
End if
case CB_BFOREXPORT
case CB_BFORREADNOTES
case CB_BFORWRITECOM
case CB_AFTERWRITECOM
case CB_BFORCOMACTION
case CB_BFORNOTESACTION
if not stats.savdoc is nothing then
else
end if
case CB_TERMINATE
end select
Using custom dialogs with the NotesUiWorkspace.Dialogbox() method
Use this method only if you are using Integra for Notes 4.0 or older If this method is used with Integra 4.1 a runtime error will occur.
Below is some example code to be placed into the Script Callback field in the Advanced tab of the Integra profile when using Integra 4.0 or older versions:
Const CB_INITIALISE = 3
Const CB_BFORREADNOTES = 6
Const CB_BFORREADCOM = 7
Const CB_BFORWRITECOM = 1
Const CB_BFORWRITENOTES = 8
Const CB_BFORCOMACTION = 5
Const CB_BFORNOTESACTION = 2
Const CB_TERMINATE = 4
Dim session As New NotesSession
Dim ws As New NotesUIWorkspace
Dim db As NotesDatabase
Dim doc As NotesDocument
Dim LF As Integer
Dim LT As Integer
Dim c As Integer
select case stats.cbstatus
case CB_INITIALISE
Set db = session.CurrentDatabase
Set doc = db.CreateDocument
' temporarily disable the Integra progress bar
If stats.pbar.enabled Then
Call stats.pbar.DisableProgressBar()
If Not ws.DialogBox("LetterRange",True,True,False,True,True,False,"Letter Range",doc,True,False) Then
End If
' Call stats.pbar.EnableProgressBar() ' Integra for Notes 4.0
Call stats.pbar.EnableProgressBar(false) ' Integra for Notes 4.1+
else
If Not ws.DialogBox("LetterRange",True,True,False,True,True,False,"Letter Range",doc,True,False) Then
End If
end if
case CB_BFORREADNOTES
case CB_BFORREADCOM
case CB_BFORWRITECOM
LF = Asc(Ucase(session.GetEnvironmentString("FromLetter")))
LT = Asc(Ucase(session.GetEnvironmentString("ToLetter")))
c = Asc(Ucase(Left(stats.expdoc.LastName(0),1)))
If Not c >= LF Then
elseIf Not c <= LT Then
end if
case CB_BFORWRITENOTES
case CB_BFORCOMACTION
case CB_BFORNOTESACTION
if not stats.savdoc is nothing then
else
end if
case CB_TERMINATE
Call session.SetEnvironmentVar("FromLetter","")
Call session.SetEnvironmentVar("ToLetter","")
end select
See Related FAQ's
How do I filter selected data based on a value entered by the user at RunTime? |
. |
|
FAQ# 0043
|
|
|
| |