Using the Collaboration Objects

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Morley Tooke
Microsoft Corporation

April 2001

Applies to:
   Microsoft® FrontPage® 2002

Summary: The Microsoft FrontPage 2002 collaboration objects allow you to share data between multiple users and multiple webs. The BasicList object, DocumentLibrary object and Survey object comprise the collaboration objects. Each object contains a collection of fields that allow you to customize the information in your object. In order to use these objects, you need to create a web on a Microsoft SharePoint Portal Server. This article describes and provides examples of creating and managing lists. (9 printed pages)

Contents

Introduction Creating a List Managing Lists Conclusion

Introduction

The Microsoft FrontPage 2002 collaboration objects allow multiple users to share information and ideas between webs. This allows for greater collaboration among users.

Now, instead of many users working on separate goals, they can work together by sharing information and working towards a common goal. Because lists are customizable and because there are three different types of lists, users are not restricted by the types of information they can display. Lists are an efficient medium for sharing information online.

Each list type is based on the List object. The List object defines a simple list and contains the basic elements needed to create and manage an effective list.

There are three different types of lists, as shown in the table below.

Table 1. List types

Each list type also contains a reference to the ListFields collection that defines the fields contained within each list. Fields are completely customizable and can be added, removed or modified to meet the needs of a list type. In addition, there are a number of different types of lists that were designed to display different data types. For example, the ListFieldTrueFalse object field type accepts a Boolean value and displays a user's True or False response. This is useful for surveys and for displaying and collecting simple data types.

The following table displays the different ListField object types.

Table 2. ListField types

Creating a List

Before you create a list, it is important to determine the key factors that will govern the effectiveness of your list. Design is the most important step when designing a list. There are several key points to consider when deciding on the type of list to use:

• What types of users will be using the list?
• What types of data will the list contain?
• How will the list be used?
• How many fields will the list contain?
• What types of fields should the list contain?

Once you have answered as many of the above questions as possible you can decide on what type of list to create and what type of fields the list will contain.

To create a list programmatically, use the Add method of the Lists collection. The following example creates a new list object.

Function NewList(ByVal strName As String, ByVal cnstListType As FpListType, _
                 ByVal strDesc As String) As Boolean
'Adds a new list to the current web.

    Dim objApp As FrontPage.Application
    Dim objLists As Lists
            
    On Error GoTo newList_Err
            
    Set objApp = FrontPage.Application
    Set objLists = objApp.ActiveWeb.Lists
    'Add new list.
    objLists.Add Name:=strName, _
                 ListType:=cnstListType, _
                 Description:=strDesc

    NewList = True
    
NewList_end:
    
    Exit Function

NewList_Err:
    NewList = False
    Resume NewList_end

End Function

In the above example, a function is used that returns a Boolean to determine if the operation was successful. This is important because if the operation fails, you have no way to tell if the list was created. Also, error checking is used to ensure that the program will not fail.

The function accepts a String value representing the name of the new list, an fpListType constant that represents the type of list and a String that represents a description of the new list.

Use the following subroutine to call the function.

Sub NewListDriver()

  Dim blnSuccess As Boolean
  Dim strText As String
  
  strText = "A new list to incorporate reorganization details."
  Success = NewList(strName:="New Corporate List", _
      cnstListType:=fpListTypeBasicList, strDesc:=StrText)
  
  If blnSuccess Then
      MsgBox "The new list was added to the web."
  Else
      MsgBox "The list was not added to the web."
  End If

End Sub

If successful, a message will be displayed and the new list will appear in the Folder List pane of the current web. Once you have created the list you can add columns and begin to customize it to meet the requirements of your users. Fields are added to a list using the Add method of the ListFields collection.

The following example adds a new field to an existing list.

Function NewListField(ByVal strListName As String, ByVal strFieldName As String, _
                      ByVal cnstFieldType As FpFieldType, _
                      ByVal blnRequired As String) As Boolean
'Adds a new field to a list.

    Dim objListFields As ListFields
    Dim objList As List
           
    On Error GoTo NewListField_Err
                
    'Add new field to the list.
    Set objList = Application.ActiveWeb.Lists(Trim(strListName))
    Set objListFields = objList.Fields
    objListFields.Add Name:=strFieldName, _
                 FieldType:=cnstFieldType, _
                 Required:=blnRequired
    'Apply the changes to the web.
    objList.ApplyChanges
    NewListField = True
    
NewListField_end:
    Exit Function

NewListField_Err:
    NewListField = False
    Resume newListField_end

End Function

Like the previous example, a function that returns a Boolean is used to determine if the field was added successfully to the list. Error trapping is also used to ensure that the subroutine will always return a result.

The function accepts a String value that represents the name of the List object, a String value that represents the title of the new field, an enumerated constant of type fpListFieldType that represents the type of field and a Boolean value that represents whether or not the field is required.

Use the following subroutine to call the function.

Sub NewListFieldDriver()

  Dim blnSuccess As Boolean
  Dim strname As String
  
  strname = "New List"
  blnSuccess = NewListField(strListName:=Strname, strFieldName:="Name", _
                         cnstFieldType:=fpFieldSingleLine, _
                         blnRequired:=True)
  
  If Success Then
      MsgBox "The new field was added to the list."
  Else
      MsgBox "The field was not added to the list."
  End If

End Sub

In the above example, a new field is added of type fpFieldSingleLine that is used to display the name of a user. Similarly, you could also add a field of type fpFieldNumber to store the office number of a user and a field of type fpFieldDateTime to store the user's original start date. While the above examples use a list, other list types such as the DocumentLibrary and the Survey objects are created and modified in the same fashion. Each list type is based on the BasicList object and each list type contains the same collection of fields.

Once you have modified the List, use the ApplyChanges method of the List object to apply the changes to the list.

Managing Lists

Because both lists and the fields they contain are collections, they can easily be traversed. Also, because the structure of the lists is hierarchical, programs can easily sort through each level of data. This allows users to monitor and create reports based on the structure of the lists or perform batch modifications on the list hierarchy itself.

The following example performs a batch modification on all fields of type fpFieldCurrency in every list in the current web. This is accomplished first by traversing through all of the Fields in every list, and then by searching all of the lists in the active web. The function searches the ListFields collection of all lists in the active web for fields with the name "Cost" and the field type fpFieldCurrency. If any fields are found that match this criteria, then their currency type is changed to Canadian dollars and their names are displayed in a window.

The function also returns a Boolean that indicates whether or not the operation was successful.

Function ModifyFields() As Boolean
'Modifies fields in all Lists.

    Dim objApp As FrontPage.Application
    Dim objField As Object
    Dim strType As String
    Dim objList As List

    Set objApp = FrontPage.Application
    'Check to see that a list exists in the current web
    If Not ActiveWeb.Lists = 0 Then
        'Traverse each List in the active web
        For Each objList In objApp.ActiveWeb.Lists
            'Traverse each field in each list
            For Each objField In objList.Fields
                'If Field name is Cost and is of type Currency then
                If (objField.Name = "Cost") And (objField.Type = fpFieldCurrency) Then
                    'If the field is not of type CurrencyFieldCanada then change it.
                    If Not objField.Currency = fpCurrencyFieldCanada Then
                        objField.Currency = fpCurrencyFieldCanada
                        'Add names of modified fields to a string.
                        If strType = "" Then
                            'Create new string.
                            strType = objList.Name & " - " & vbTab & objField.Name & vbCr
                        Else
                            'Add next field name to string.
                            strType = strType & objList.Name & _
                              " - " & vbTab & objField.Name & vbCr
                        End If
                    End If
                 End If
            Next objField
        Next objList
        If strType = "" Then
            ModifyFields = False
        Else
            'Display the fields that were modified.
            MsgBox "The following Fields were modified: " & vbCr & strType
            ModifyFields = True
        End If
    Else
        'Otherwise set to False.
        ModifyFields = False
    End If
   
End Function

Use the following subroutine to call the above function. The subroutine uses the Boolean result of the function to display a message to the user.

Sub ModifyFieldsDriver()
'Calls the ModifyFields function.
    Dim blnSuccess As Boolean
    
    blnSuccess = ModifyFields
    
    If blnSucess = False Then
        MsgBox "The current web contains no lists or no fields were modified."
    End If
    
End Sub

Conclusion

The collaboration objects allow you to better share a wide variety of data types between users on multiple webs. The List, Survey, and Document library object list type are simple to create and can easily be modified and customized to meet the specific needs of your users. Lists can also be managed with a great deal of simplicity. Because of the structure of lists, a list can be traversed, modified and searched without the need of a complex script.