.Domino Framework

One of today's challenges has been to find a way for a form to get access to the list of documents selected in an embedded view.  After searching high and low I finally found some code written by Julian Robichaux that came very close to providing what I wanted (thanks Julian).  So the DominoView class in the .Domino Framework has now been extended with a SelectedDocuments property that returns a NotesDocumentCollection containing the documents selected for that view in the NotuesUIWorkspace.  I imagine this can be anywhere on the workspace and not just an embedded view!

 

e.g.

Dim myview as New DominoView("myembeddedviewname&quot

Dim DocList As NotesDocumentCollection

Set DocList = myview.SelectedDocuments

.....

The core code in the property is as follows (Note: some bits of code are provided by the framework)

 

 Property Get SelectedDocuments As NotesDocumentCollection
  
  Dim hDb     As Long
  Dim viewNoteID As Long
  Dim hCollection  As Long
  Dim hIDTable   As Long
  Dim PathName  As String*256
  Dim NoteID   As Long
  Dim FirstFlag   As Integer
  Dim Result   As Integer
  Dim Count    As Long
  Dim  NID    As String  
  Dim Collection  As NotesDocumentCollection
  Dim Doc    As NotesDocument
  
Try:
  On Error Goto Catch
  If iView Is Nothing Then Exit Property  
  
' Get Collection of selected documents
  
  Call OSPathNetConstruct(0, DB.Server, DB.FilePath, PathName$)  ' Create a proper network path name with OSPathNetConstruct
  Result = NSFDbOpen(pathName, hDb)           ' Open the database and get a handle with NSFDbOpen
  If Result <> 0 Then Exit Property
  Call OSPathNetConstruct(0, DB.Server$, DB.FilePath$, PathName$) ' Create a proper network path name with OSPathNetConstruct
  Result = NSFDbOpen(PathName$, hDb)           ' Open the database and get a handle with NSFDbOpen
  If Result <> 0 Then Exit Property
  Result = NIFOpenCollection(hDB, hDB, ViewNoteID, 0, 0, hCollection, 0, 0, 0, hIDTable) ' Get the ID table of all the selected docs in the view
  If Result <> 0 Then Goto Finally
  Count& = IDEntries(hIDTable)
  If (Count& = 0) Then Goto Finally
  
' Convert collection to NotesDocumentCollection
  
  Set Collection = Application.EmptyNotesDocumentCollection
  FirstFlag = True
  Do While IDScan(hIDTable&, FirstFlag%, NoteID& > 0
    FirstFlag = False
    NID$ = ConvertNoteID(NoteID&
    If (Len(NID$) > 0) Then
     Set Doc = DB.GetDocumentByID(NID$)
     If Not Doc Is Nothing Then Call Collection.AddDocument(Doc)
    End If
  Loop
  Set SelectedDocuments = Collection
  Goto Finally

Catch:
  Stop
  ReportError
  Resume Finally
  
Finally:
  If (hCollection > 0) Then Call NIFCloseCollection(hCollection)  ' Free the memory used when we grabbed the ID table
  Call NSFDbClose(hDb)                ' Close the database with NSFDbClose
  Exit Property
End Property

I was making great progress making the .Domino Framework a little more Web 2.0-like by adding the Notes Fieldset simulation blogged about by Nathan Freeman and  Chris Blatnik.  That was until I started testing some of the forms and found a few of them no longer worked as designed.  After pulling the rest of my hair out I began to realize it was the layers that were causing the problem.  It seems that Layers can be a nice feature to add from a Presentation perspective but sometumes they do not play well with Notes (6.0).  I thought I would share the pain for anyone else playing with fieldsets and layers....

 

Lesson #1... Whilst a layer anchor can be added to any tab inside a tabbed table, the layer contents only ever display as part of the first tab.  So no fieldsets/layers inside tabbed tables except on the first tab

 

Lesson #2.. Placing a layer inside a table that is then placed in a collapsed section causes some weird things.  If the section is collapsed in designer or programmed to callapse when a form is opened then expanding the section displays the layer but any table rows below the layer disappear.  The fields even disappear inside Domino Designer.  I thought I had lost the rest of my table but found I could expand the section close the form, re-open the form, and there it was again.  So no fieldsets inside collapsed sections

 

Lesson #3.. Fields that are displayed using Hide When formulas and are initially hidden will no longer display on form refresh if the hide when formula now allows the field to display (e.g. progressive disclosure).  I can still have the "fieldset" except I can't use a layer to apply the label.

I am constantly suprised that no matter how much I learn about Notes Development there seems to be so much more I still don't know.  In the past few days both Nathan Freeman and  Chris Blatnik posted some excellent articles on how to use style sheets to simulate the HTML Fieldset capability on a Notes client.  I had always thought  Style Sheet resources were the domain of Web application development only.  It never occured to me that these could be used to style a Notes client application...

 

So I have already been busy enhancing the UI for a number of forms in the .Domino Framework that utilize the tricks they have shown.  In doing so it also occured to me that it may in fact possible to build a Notes application in such a way that the look/feel can be customized to suit individual preferences.  

 

The .Domino Framework supports a User Preferences form/profile document in which each user can (now) select from a list of available skins.  Each supported skin is represented by a Style Sheet, and an associated subform that contains this style sheet.  Various forms in the .Domino Framework can now include a computed subform that is based upon the user's preferred skin.  And voila the look/feel of the form reflects the user's preferred skin.

 

As best as I can tell a great many Notes Design elements still do not get effected by Style Sheets so this is a at best a partial solution.  The application skinning feature is still needed to apply a base theme to an application (views, embedded outlines etc.) At least now I can provide some flexibility how some aspects of the application look/feel.

It is not uncommon over time for an application to accumulate a lot of fields in documents that are no longer being used.  This will usually occur as a a result of  fields being removed from a form.  In the early stages of development this is especaially common.  The task of cleaning up the database so these fields no longer exist on documents is often a task that is either ignored or considered to be too much of an effort/pain to perform.

 

The latest release of the .Domino Framework provides a RemoveNonFormFields method for the DominoDocumentCollection class.  Running against selecetd documents it build a list of the fields used in the default form assigned to each document and removes document fields if they are not found on the form.  Field names starting with "$" are retained.. The All Document view provides an action button to invoke this method as one of the list of operations that can be perfromed against selecetd documents.

 

Note: This presently only work in situations in which subforms are NOT used and additional fields are not created via events, agents, actions etc.

 

The code is as follows:-

 

 Sub RemoveNonFormFields
  
  Dim Form     As NotesForm    ' Default form used to display document
  Dim FormName  As String      ' Name of form
  Dim FormFields  As Variant      ' List fo fields on form
  Dim Doc     As NotesDocument  ' Document in collection being processed
  Dim HasChanged  As Boolean     ' One or more fields have been removed => document must be saved
Try:
  On Error Goto Catch
  
  Set Doc = iDocumentCollection.GetFirstDocument
  While Not Doc Is Nothing
   
' Identify form used for document
   
   If Doc.HasItem("Form" Then FormName$ = Doc.GetItemValue("Form"(0) Else FormName$ = ""
   If FormName$ <> "" Then
    If Form Is Nothing  Then
     Set Form = DB.GetForm(FormName$)
    Elseif FormName$ <> Form.Aliases(0) Then
     Set Form = DB.GetForm(FormName$)
    End If
    If Not Form Is Nothing Then FormFields = Form.Fields
    
' Remove all fields not found on form
    
    If Not Form Is Nothing Then
     HasChanged = False
     Forall DocField In Doc.Items
      If Left(DocField.Name$,1) <> "$" Then
       If Isnull(Arraygetindex(FormFields,DocField.Name$,5)) Then
        Call Doc.RemoveItem(DocField.Name$)
        HasChanged = True
       End If
      End If
      If HasChanged Then Call Doc.Save(False,False)
     End Forall
    End If
   End If
   
   Set Doc = iDocumentCollection.GetNextDocument(Doc)
  Wend
  Exit Sub
Catch:
  Stop
  ReportError
  Exit Sub
  
 End Sub

For anyone else new to LEI Activities, please note that having a replica of the Notes database on the LEI server can have a significant impact on the performance of LEI activities.  I have an application that transfers data from Sybase to Notes using a Direct Transfer activity.  In development the Notes database resides on the LEI server.  The transfer of 7,000 records is taking an average of 1 hour every night.  In QA the Notes database is on a separate server to the LEI server.  The same Sybase server/database is being used as the source and the same Data Transfer activitiy is taking an average of 3 hours to run.

 

Update:

Subsequent testing identified the cause of the issue was pointing the ELI activities located on a server located in another facility.  Running an LEI activties that point to another server in the same facility resulted in almost no fifference in perfromance.

A new feature is now ready for the next beta release of the .Domino Framework that will extend the Application Skin feature to assign a consistent look and feel to design components that support the htmlclass element.  This includes tables, table cells, fields, frames, and framesets.  Assigning a class to a design component is traditionally only done with Web applications to assign UI characteristics via a CSS.  Now a .Domino design rule can be added to define the UI characteristics in a similar manner to a CSS.  Using XSLT the design elements themselves are updates so that the UI is rendered to the Notes client.

Here is an example of the XSLT code that is generated by the process to apply to a table assigned the htmlclass DataEntry:-

  <xsl:template match="dxl:table[@htmlclass='DataEntry']/@colorstyle">
    <xsl:attribute name="colorstyle">left</xsl:attribute>
  </xsl:template>

  <xsl:template match="dxl:table[@htmlclass='DataEntry']/@bgcolor">
    <xsl:attribute name="bgcolor">#E0E8F0</xsl:attribute>
  </xsl:template>

  <xsl:template match="dxl:table[@htmlclass='DataEntry']/@altbgcolor">
    <xsl:attribute name="altbgcolor">#FFFFFF</xsl:attribute>
  </xsl:template>

  <xsl:template match="dxl:table[@htmlclass='DataEntry']/@cellbordercolor">
    <xsl:attribute name="cellbordercolor">#8091A5</xsl:attribute>
  </xsl:template>

  <xsl:template match="dxl:table[@htmlclass='DataEntry']/@rowspacing">
    <xsl:attribute name="rowspacing">0.02in</xsl:attribute>
  </xsl:template>

  <xsl:template match="dxl:table[@htmlclass='DataEntry']/@columnspacing">
    <xsl:attribute name="columnspacing">0.05in</xsl:attribute>
  </xsl:template>

  <xsl:template match="dxl:table[@htmlclass='DataEntry']">
    <xsl:copy>
      <xsl:attribute name="colorstyle">left</xsl:attribute>
      <xsl:attribute name="bgcolor">#E0E8F0</xsl:attribute>
      <xsl:attribute name="altbgcolor">#FFFFFF</xsl:attribute>
      <xsl:attribute name="cellbordercolor">#8091A5</xsl:attribute>
      <xsl:attribute name="rowspacing">0.02in</xsl:attribute>
      <xsl:attribute name="columnspacing">0.05in</xsl:attribute>
      <xsl:apply-templates select="@*|node()"/>
    </xsl:copy>
  </xsl:template>

One of the advantages of profile documents is that these documents do not display in views.  One of the disadvantages of profile documents is that these documents do not display in views.  So just how do you see a list of the profile documents in your database?

 

The following is some code I developed to display a list of profile documents in a database.  The options for displaying the output vary.  The text will often be too large for a Prompt or MessageBox so I have opted for a DialogBox.  I have created a generic subform with a single Body field as a way of displayng the output such as this.

 

Dim ProfileDocList As NotesDocumentCollection
 Dim ProfileDoc   As NotesDocument
 Dim ProfileList()  As String
 Dim ProfileIndex  As Long
 Dim Doc     As NotesDocument
 
 Set ProfileDocList = DB.GetProfileDocCollection
 If ProfileDocList.Count > 0 Then
  Redim ProfileList(ProfileDocList.Count-1)
  Set ProfileDoc = ProfileDocList.GetFirstDocument
  While Not ProfileDoc Is Nothing
   If ProfileDoc.HasItem("$Name" Then
    ProfileList(ProfileIndex& = ProfileDoc.GetItemValue("$Name"(0)
    ProfileIndex& = ProfileIndex& + 1
   End If
   Set ProfileDoc = ProfileDocList.GetNextDocument(ProfileDoc)
  Wend  
 End If
 Set Doc = New NotesDocument(DB)
 Call Doc.ReplaceItemValue("Body",ProfileList)
 Call UIW.DialogBox("sfGeneric",False,False,True,True,True,True,"The following Profile Documents have been found in this database",Doc)

 

This will be added to the next release of the .Domino Framework as a method of the DominoDatabase class.

One of the limitations in LotusScript for OOP is the lack of support for method overloading i.e. the ability to invoke a method passing a different number of parameters and/or a different combination of parameter types.....

This limitation can be negated in part by making parameters of type Variant.  parameters not needed can have a value of Nothing passed.  I have found this particularly useful in creating the class constructor.  Most applications have core objects that are stored in a NotesDocument and invariably accessed via a Form.  So many classes I create are extensions of the NotesDocument class.  The .Domino Framework provides a DominoDocument class that extends both the NotesDocument and NotesuIDocument classes for each core object.  The constructor for this class takes a single parameter (Source) of type variant.  This allows me to instantiate the class by passing a reference to (a) a background NotesDocument object, (b) a foreground NotesUIDocument object, (c) a string which could represent the DocumentUNID of the document or some other single key, or (d) an array which contains partial keys for the document.  The single constructor evaluates the type of parameter passed and processes each type differently achieving a similar result to other programming labhuages that allow multiple constructors.

Update: The example has been updated to include some of the great ideas posted as comments.  I still have just one parameter but that variable could contain an array or a list....

e.g.

 

Sub New(Source As Variant)

  Select Case Typename(Source)
    Case "NOTESDOCUMENT"
     Set iDocument = Source
    Case "NOTESUIDOCUMENT"
     Set iUIDocument = Source
     If Source.Document Is Nothing Then On Event PostOpen From Source Call OnPostOpen Else Set iDocument = Source.Document
    Case "STRING"
     Call GetByKey(Cstr(Source))

    Case "STRING()"
     Call GetByPartialKeys(Cstr(Source(0),Cstr(Source(1))

    Case "VARIANT LIST"
     Forall parameter in Source
       Select Case Listtag(parameter)
         Case "document"
            Set iDocument = parameter
    End Select

  End Select

End Sub

Did you ever want to lose the list of Notes IDs that have modified a particular set of Notes documents?  It would seem it is not possible to edit the existing contents of the $UpdatedBy using either @commands or LotusScript.  I assume this is a data integrity issue to ensure the contents of the edit history for any document cannot be manipulated.  This field can be modified (or removed) for design documents (see SuperNTF project at OpenNTF).  Interestingly, it is possible to edit or remove the contents of this field using XSLT.   I am not 100% sure this is a good thing to have, but it is possible!

 

The following is the XSLT code necessary to apply against documents exported from a Notes database as DXL before reimporting.....

 

<?xml version='1.0'?>

<xsl:stylesheet xmlnssl="http://www.w3.org/1999/XSL/Transform"

xmlns:dxl="http://www.lotus.com/dxl" version="1.0">

<xsl:template match="@*|node()" priority="-1">

<xsl:copy>

<xsl:apply-templates select="@*|node()"/>

</xsl:copy>

</xsl:template>

<xsl:template match="dxl:noteinfo/dxl:updatedby">

</xsl:template>

</xsl:stylesheet>

 

After doing this the $UpdatedBy field will only contain the NotesID of the agent that executed the XSLT transformation.  All previous entries will be removed.  e.g. I have used this technique to refresh the content of the .Domino Framework so that it does not contain the various Notes IDs I have used as a developer in creating and maintaining content for this project.

 

Warning: Not all Notes documents can be exported and reimported into Notes without losing something on the way, so test this out in a safe environment first.

The latest beta of the .Domino Framework was released on the weekend.  This latest beta contains a number of tweaks to the existing framework as well as adding a few new features.  This includes integration with OpenLog and a new application skin feature.

 

The application skin works at three levels:-

 

The first level involves the creation of XSLT code to transform various aspects of an applications design.  It requires a good working knowledge of DXL and XSLT, but offers the most flexibility.  Examples of where this would be best used includes making a global change to use a specific font in all design elements.  The XSLT code to do this is provided with the latest template.  XSLT can be applied to all selected design elements.

 

The second level involved the creation of a "Design Rule".  A Notes form exposes many of the design parameters of Forms, View, Framesets, an Pages and allows a developer to indicate which attributes are to be set and what the setting should be.  (e.g. Form background color, action bar background color, view grid style,...).  Once the design parameters are defined, XSLT is built from the "Design Rules" and can then be applied to selected design elements.  Design Rules can be a sophisticated as defining the enture UI/Skin for an application to something as simple as setting the background color for view/form/page action bars.  This approach does not require any knowledge of DXL/XSLT but is limited to the design elements exposed in the Design Rule.  The XSLT generated for the Design Rule can be copied and adapted using the first approach to provide additional flexibility.

 

The third level allows a developer to clone existing design elements creating a Design Rule from selected design elements.  This approach can be used to take a look/feel of an existing form/page/frameset/view and apply it to all/selected other design elements.  Once the cloned design rule has been cretaed it can be further modified using either of the two previous approaches.

 

The next step in the evolution of this feature will be the ability to assign design attributes to CSS classes much in the same way as can be done Web applications.  Various design components (frames, tables, table cells, computed text etc.) already support the assignment of a CSS classes within Domino Designer.  There is nothing in the rules that says these have to be for Web applications use!  By defining the attributes of a CSS class as part of a Design Rule it should be possible to use XSLT to generate the apply the  design changes to design elements (e.g. font, background color, line width).  I am hoping to have this next capability available with beta 0.4 in May.