This is the third in a 4-part series concerning creating MS Word documents in LotusScript. In the first tip, we talked about the basics of creating a Word document and adding text to it. In the second tip, we got a bit more advanced with some formatting options. In this tip we'll talk about updating headers and footers and some other advanced topics. In the last tip we'll talk about even more advanced topics like adding tables to your document.

Headers and footers are special sections in your document. It's pretty easy to get a handle to them. Once you get a handle to them, you can add text just like any other part of your document. If you've worked with headers and footers manually in Word, you know that there are three built-in "columns". By pressing the tab key, you can move from text that is left-aligned in the header, to text that is centered, to text that is right-aligned. Our function takes in a document and the text to insert, just like the AppendTextToDoc function does. The developer using this code has to be aware that the text will, by default, be inserted into the first column. The first character should be a Chr$(9) if they want the text to be centered. The developer should add two Chr$(9) characters if the text should be right-aligned. The reason we did it this way instead of accepting a third parameter is to give more control to the developer using the function. They could insert some text, then a tab, then more text, then another tab, and more text and they would end up with text in all three columns.

Function AppendTextToHeader(doc As Variant, text As String) As Variant
   Dim header As Variant
   Dim lastParagraph As Variant
   Dim newRangeStart As Long
   ' Get a handle to the header
   Set header = doc.Sections(1).Headers(1)
   ' Find the last paragraph in the header
   Set lastParagraph = header.Range
   newRangeStart = lastParagraph.End-1 ' This is where the new text will be placed
   Call lastParagraph.InsertAfter(text)
   ' Reset the range handle to include the text we just entered and only that text
   Set lastParagraph = header.Range
   Call lastParagraph.SetRange(newRangeStart, lastParagraph.End)
   Set AppendTextToHeader = lastParagraph
End Function

The function works in a similar fashion to the function that appends text to the document. The range is returned, so you can set the font information or bolding or other settings on the text can be applied using existing subroutines. The footer code is very similar to the header code:

Function AppendTextToFooter(doc As Variant, text As String) As Variant
   Dim footer As Variant
   Dim lastParagraph As Variant
   Dim newRangeStart As Long
   ' Get a handle to the footer
   Set footer = doc.Sections(1).Footers(1)
   ' Find the last paragraph in the footer
   Set lastParagraph = footer.Range
   newRangeStart = lastParagraph.End-1 ' This is where the new text will be placed
   Call lastParagraph.InsertAfter(text)
   ' Reset the range handle to include the text we just entered and only that text
   Set lastParagraph = footer.Range
   Call lastParagraph.SetRange(newRangeStart, lastParagraph.End)
   Set AppendTextToFooter = lastParagraph
End Function

In headers and footers, there are additional things you can do like set the current page number and the total number of pages. These aren't "regular text". In MS Word terms, they are fields inside the header or footer. So we wrote functions to append a field to the header or footer. These functions take a MS Word document (just like the other functions) and a "key" to indicate what should be added. The key is an integer value where 1 means Page Number, 2 means Total Number Of Pages, 3 means Current Date and 4 means Current Time. (Note that the internal script library that we use has "wrapper" functions so the developer won't have to remember the key number values - they can call a function to insert the page number, and that function will call this function with the right key value).

Function AppendFieldToHeader(doc As Variant, key As Integer) As Variant
   Dim header As Variant
   Dim lastParagraph As Variant
   Dim newRangeStart As Long
   ' Get a handle to the header
   Set header = doc.Sections(1).Headers(1)
   ' Find the last paragraph in the header
   Set lastParagraph = header.Range
   newRangeStart = lastParagraph.End-1 ' This is where the new field will be placed
   Call lastParagraph.SetRange(newRangeStart+1, newRangeStart+1)
   Select Case key
      Case 1 : Call lastParagraph.Fields.Add(lastParagraph, 33) ' Page Number
      Case 2 : Call lastParagraph.Fields.Add(lastParagraph, 26) ' Total Number Of Pages
      Case 3 : Call lastParagraph.Fields.Add(lastParagraph, 31) ' Current Date
      Case 4 : Call lastParagraph.Fields.Add(lastParagraph, 32) ' Current Time
   End Select
   ' Reset the range handle to include the field we just entered and only that field
   Set lastParagraph = header.Range
   Call lastParagraph.SetRange(newRangeStart, lastParagraph.End)
   Set AppendFieldToHeader = lastParagraph
End Function

The important difference with this function is that a new ranage, restricting the code to the very end of the header, is set before the field is appended to the header. A field will "take over" the entire range, so the code has to make sure that it is really pointing to the end of the paragraph. Again, this function returns a handle to the field that was added, so you can apply things like bold or italics or whatever to the field. The footer code is also very similar:

Function AppendFieldToFooter(doc As Variant, key As Integer) As Variant
   Dim footer As Variant
   Dim lastParagraph As Variant
   Dim newRangeStart As Long
   ' Get a handle to the footer
   Set footer = doc.Sections(1).Footers(1)
   ' Find the last paragraph in the footer
   Set lastParagraph = footer.Range
   newRangeStart = lastParagraph.End-1 ' This is where the new field will be placed
   Call lastParagraph.SetRange(newRangeStart+1, newRangeStart+1)
   Select Case key
      Case 1 : Call lastParagraph.Fields.Add(lastParagraph, 33) ' Page Number
      Case 2 : Call lastParagraph.Fields.Add(lastParagraph, 26) ' Total Number Of Pages
      Case 3 : Call lastParagraph.Fields.Add(lastParagraph, 31) ' Current Date
      Case 4 : Call lastParagraph.Fields.Add(lastParagraph, 32) ' Current Time
   End Select
   ' Reset the range handle to include the field we just entered and only that field
   Set lastParagraph = footer.Range
   Call lastParagraph.SetRange(newRangeStart, lastParagraph.End)
   Set AppendFieldToFooter = lastParagraph
End Function