Project A: Build a Discussion Forum

Project A Build a Discussion Forum

Difficulty Level:	Moderate
Completion Time:	5 to 8 hours
Project Materials:	4 Forms, 1 Subform, 1 Library, 5 Action Buttons, 3 Shared Fields, 6 Views, 1 Access Control List Role, 1 Scheduled Agent
Languages Used:	Formula Language, LotusScript
Possible Usages:	Online help, questions & answers, items for sale

 

Application Architecture

Discussion forums, as the name implies, allow users to discuss and respond to forum topics. Traditionally, this type of architecture includes a multi-tiered methodology to organize information, beginning with a Main document, a Response document and Response to Response document.

This architecture might be used in an online "help" or "for sale" database in which a person posts a main discussion topic that becomes the focal point for subsequent discussion. This type of application might be compared to the classified section of a newspaper in which a person places, or posts, an item for sale and potential buyers ask questions regarding the item.

In this example, the initial posting is the main document, also known as the parent document. Any person who responds to the parent document generates a Response document, also called a child document. In addition to the parent and child document, Lotus Notes also provides the ability to create a Response to Response or grandchild document.

Figure 9.1 depicts the parent, child, and grandchild relationship and illustrates how a main discussion topic can have multiple related sub-documents.

Figure 9.1. Parent, child, grandchild relationship

Continuing the analogy of a classified section, this project allows each main document to be grouped or categorized through the use of a dropdown menu with related postings. For this example, "for sale" categories might include

• Appliances
• Boats
• Electronics
• Employment opportunities
• Miscellaneous
• Real estate
• Vehicles

There are essentially two ways that a category can be implementedit can be hard-coded or created dynamically. With hard-coding, values are stored with the programming code. Although this may require less time up front, it is more difficult and costly to make changes later. Creating a category dynamically may require more time up front but makes it easier to manage information later.

Note

Dynamic categories can be created such that either the administrator manages the valid list of categories or users are given the flexibility to create categories as needed. This project will illustrate how to create an application where an administrator controls the category names. This enforces a strict nomenclature for document classifications. The next project in this chapter will illustrate an alternative method for dynamic creation of categories.

Implementing dynamic categories requires three additional design elementsa form, a view, and program logic. The Category form will be used to create new category names. The view will be used to populate values in the dropdown menu. Items can simply be removed by deleting the appropriate category document from the view. Programming logic, as opposed to hard-coded values, is then added to the dropdown design element. This allows for easier management of information with no additional coding required in the future.

This application will include three different viewsBy Topic, By Author, and By Category. Each view will contain the same information, simply sorted and displayed differently. This provides the user with several different options when searching for information.

In addition to the discussion topic views, three administrative views will be createdCategories, Subscriptions, and Email Queue. These views manage the overall usage of the application. The Category view is used to manage the classification of documents and will populate the Category field on the parent document. The Subscription view lists all individuals that have registered with the discussion forum. This view will be used to send email notifications as new postings are created. The Email Queue is used by the server to send notifications. This view will list new postings that have not been emailed to registered users.

Finally, the architecture for this project includes two methods to send email notificationsclient based and server based. Using the client-based method, emails are automatically triggered each time a document is posted to the discussion forum. When these emails are sent, the person posting the article will be listed in the "From" field of the email. The second method shifts the notification process to the server. Using a scheduled agent, email notifications are sent from the server based on a specified interval (say every five minutes). With this method, the server name will be listed in the email "From" field. This method also shifts the processing from the client to the server. If you have a significant number of registered users, you'll probably want to implement the server-based methodology.

Note

This project includes both methods for sending email notices to registered usersclient based and server based. Both options have been included in the project to illustrate methods for generating and sending email notifications. From an implementation perspective, we recommend the server approach, but either can be implemented. If you elect to implement both, users will receive two email notifications as topics are posted to the database.

Note

The Lotus Notes client includes a discussion template that essentially does the same thing as this project. With that in mind, the intent of this project is to teach how to create an application that utilizes a "Response Document" hierarchy.

 

Create the Database

To start this project, launch the Lotus Domino Designer client. When the Designer client is running, select the File > Database > New menu options to create a new database. Specify Forum as the application title and Forum.nsf as the file name (see Figure 9.2). Be sure to select -Blank- as the template type.

Figure 9.2. New Database dialog

 

Set the Database Roles

After the database is created, start by establishing the roles associated with the database. Roles enable specific people to perform actions that others cannot. In this case, the "Admin" role will enable the application administrator to create new categories for the discussion forum. Anyone that does not have this role will have this authority.

To create the role, select the File > Database > Access Control menu options. By default, the Basics tab should be active. Switch to the Roles tab and select the Add button (located at the bottom of the dialog window).

This will display a new popup window called Add Role (see Figure 9.3). Type Admin and click the OK button to add the role.

Figure 9.3. Add Role dialog

Click OK a second time to close the Access Control List (ACL) window.

Create the Discussion Forum Script Library

The next step will be to create the LotusScript library because virtually all of the design elements will utilize shared subroutines. To create the library, select the Create > Design > Script Library > LotusScript Library menu options.

Tip

The following code is available in the developer's toolbox. Simply open the "Project Library" database in your Lotus Notes client and navigate to the "Script Library" section for the appropriate project. After you locate the project, copy and paste the code into the Designer client for the current project. Be sure the programmer's pane has focus before pasting the code. Alternatively, you can elect to manually type the code.

 

CheckFieldValues Function

The CheckFieldValues function checks two fields, Topic and Category, to make sure they contain a value on the form. This function is called from the Topic form. An error message is displayed and returns a False value if one of the fields is null. A TRue value must be returned before the user can save the document in the database.

Function CheckFieldValues ( DocRef As NotesDocument )
 CheckFieldValues = True
 MsgText = ""
 If DocRef.Topic(0) = "" Then
 MsgText = MsgText + "Specify a topic description." + Chr$(13)
 End If

 If DocRef.Category(0) = "" Then
 MsgText = MsgText + "Specify a discussion category" + Chr$(13)
 End If

 If MsgText <> "" Then
 Msgbox MsgText, 16, "Required Fields."
 CheckFieldValues = False
 End If

End Function

 

SendNotice Subroutine

The SendNotice subroutine is used to send client-based emails to registered users. The routine is called the first time a new posting is saved and closed. Using this option, emails are triggered by the user that submitted the posting.

Emails will be sent to all registered users that have subscribed to the forum and have requested emails on the posted category (e.g., Compact Cars). Later in the project we'll discuss how to implement or disable this email delivery option.

Sub SendNotice ( uidoc As NotesUIDocument )

 '-------------------------------
 ' Initialize primary objects
 '-------------------------------
 Dim ws As NotesUIWorkspace
 Dim s As NotesSession
 Dim db As NotesDatabase
 Dim doc As NotesDocument
 Dim viewA As NotesView
 Dim docA As NotesDocument

 Set ws = New NotesUIWorkspace
 Set s = New NotesSession
 Set db = s.CurrentDatabase
 Set doc = uidoc.Document
 Set viewA = db.GetView( "Subscriptions" )
 Set docA = viewA.GetFirstDocument
 '--------------------------------
 ' Build the email document
 '--------------------------------
 Dim docMemo As NotesDocument
 Set docMemo = New NotesDocument (db)
 docMemo.Form = "Memo"
 docMemo.Subject = doc.Topic
 Set rtitem = New NotesRichTextItem(docMemo, "Body")
 Call rtitem.AddNewLine( 2 )
 Call rtitem.AppendText ("Open Document --> " )
 Call rtitem.AppendDocLink( Doc, "Discussion Topic" )
 Call rtitem.AddNewLine( 1 )
 Call rtitem.AppendText ("Open Database --> " )
 Call rtitem.AppendDocLink( db, db.Title )

 '--------------------------------
 ' Loop through subscriptions. Send email to interested parties.
 '--------------------------------
 While Not ( docA Is Nothing )
 'Msgbox "Sending email to: " + docA.InternetMail(0)
 If docA.AllowEmails(0) = True Then
 If ( foundElement (docA.Category, doc.Category(0) )) Then
 Print "--- Sending email to: " + docA.InternetMail(0)
 docMemo.SendTo = docA.InternetMail(0)
 docMemo.Send False
 End If
 End If
 Set docA = viewA.GetNextDocument( docA )
 Wend

End Sub

 

SendNewPostings Subroutine

The SendNewPostings subroutine is the second email delivery option and is used for server-based email notifications. This subroutine is called from a scheduled agent. Using this option, emails will originate from the server, as opposed to the user that submitted the discussion topic. Later in the project we'll cover how to enable or disable this delivery option.

Sub SendNewPostings

 Dim s As NotesSession
 Dim db As NotesDatabase
 Dim viewA As NotesView
 Dim viewB As NotesView
 Dim docA As NotesDocument
 Dim docB As NotesDocument
 Dim docC As NotesDocument
 Set s = New NotesSession
 Set db = s.CurrentDatabase
 Set viewA = db.GetView( "EmailQue" )
 Set docA = viewA.GetFirstDocument
 Set viewB = db.GetView( "Subscriptions" )

 '--------------------------------
 ' Loop through email queue.
 '---------------------------------
 While Not ( docA Is Nothing )
 Print "Processing topic: " + docA.Topic(0)

 '------------------------------
 ' Build the email document
 '------------------------------
 Dim docMemo As NotesDocument
 Set docMemo = New NotesDocument (db)
 docMemo.Form = "Memo"
 docMemo.Subject = docA.Topic
 Set rtitem = New NotesRichTextItem(docMemo, "Body")
 Call rtitem.AddNewLine( 1 )
 Dim rtitemB As Variant
 Set rtitemB = docA.GetFirstItem( "Body" )
 Call rtitem.AppendRTItem( rtitemB )
 Call rtitem.AddNewLine( 2 )
 Call rtitem.AppendText ("Open Document --> " )
 Call rtitem.AppendDocLink(DocA, "Discussion Topic" )
 Call rtitem.AddNewLine( 1 )
 Call rtitem.AppendText ("Open Database --> " )
 Call rtitem.AppendDocLink( db, db.Title )

 '------------------------------
 ' Send email to interested parties
 '------------------------------
 Set docB = viewB.GetFirstDocument
 While Not ( docB Is Nothing )
 If docB.AllowEmails(0) = "-1" Then
 If ( foundElement (docB.Category, docA.Category(0) )) Then
 Print "- Sending email to: " + docB.InternetMail(0)
 docMemo.SendTo = docB.InternetMail(0)
 docMemo.Send False
 End If
 End If
 Set docB = viewB.GetNextDocument ( docB )
 Wend

 '------------------------------
 ' Get next document before updating current status.
 '------------------------------
 Set docC = viewA.GetNextDocument( docA )
 docA.Status = "COMPLETE"
 docA.Save True, True
 Set docA = docC
 Wend

End Sub

 

FoundElement Function

The FoundElement function is used to search for a specified element in a list array. The function returns true if the element is found and False if the element is not found. In this case, the function checks to see if the registered user is interested in the posted discussion topic category.

Function foundElement (varFromList As Variant, varTarget As Variant) As Variant

 '--------------------------------
 ' Check for the existence of an element in an array.
 '--------------------------------
 foundElement = False
 Forall varElement In varFromList
 If varElement = "All" Then
 foundElement = True
 Exit Forall
 Elseif varElement = varTarget Then
 foundElement = True
 Exit Forall
 End If
 End Forall

End Function

 

SaveForm Function

The SaveForm function is called from the QuerySave event each time the main document or Response document is saved. This routine will call the CheckFieldValues function to verify that the fields are not empty. If all fields are valid, the message "Are you ready to post this topic?" will be displayed prior to saving the topic to the discussion forum.

If the user selects "Yes", then the Status field is set to "SUBMIT", and the form is closed. Setting the status to "SUBMIT" indicates that the form has been submitted and will trigger email notifications in the QueryClose event.

Function SaveForm As Integer

 Dim ws As New NotesUIWorkspace
 Dim uidoc As NotesUIDocument
 Dim doc As NotesDocument
 Dim answer As Integer
 Dim Continue As Integer
 Set uidoc = ws.CurrentDocument
 Set doc = uidoc.Document

 Continue = CheckFieldValues ( doc )
 If Continue Then
 If doc.IsNewNote Then
 answer% = Msgbox("Are you ready to post this topic?", _
 292, "Continue?")
 If answer% = 6 Then
 doc.Status = "SUBMIT"
 uidoc.Close
 Else
 continue = False
 End If
 End If
 End If
 SaveForm = Continue

End Function

 

CloseForm Subfunction

The CloseForm subroutine is called from the QueryClose event each time the main or Response document is closed. When called, this routine will check the value in the Status field. If this is the first time the document is being closed, the status will be set to "SUBMIT" and will trigger client-based email notifications.

After the email notifications are sent, the status is set to "POSTED" to signify that the topic has been sent to all interested subscribers via the client-based method. If the server-based method is implemented, the scheduled agent will trigger emails based on a status of "POSTED".

Note

As implemented here, client-based notifications will be enabled. To disable client-based notifications, comment out the statement "Call SendNotice ( uidoc )" in the following code. To implement server-based notifications, a scheduled agent (discussed later in the project) will need to be created to send out the notifications.

Sub CloseForm
 Dim w As New NotesUIWorkspace
 Dim uidoc As NotesUIDocument
 Dim doc As NotesDocument
 Set uidoc = w.CurrentDocument
 Set doc = uidoc.Document
 If doc.Status(0) = "SUBMIT" Then

 ' Comment out the "SendNotice" statement to
 ' implement the server-based email notifications
 Call SendNotice ( uidoc )

 doc.Status = "POSTED"
 doc.Save True, True
 End If
End Sub

Save and close the LotusScript library. When prompted, name the library DiscussionForum.

Create the Shared Action Buttons

This project includes five action buttonsNew Topic, Reply, New Category, Subscribe, and Submit. These buttons will be used throughout the application on multiple forms and views.

New Topic Button

This button is used to post new discussion topics, or parent documents, in the forum. Select the Create > Design > Shared Action menu options and name the button New Topic in the properties dialog. Add the following in the Programmer's pane. Save and close the design element.

@Command([Compose]; "Topic")

 

Reply Button

The Reply button will allow users to post either a Response or Response to Response document. Depending on the document that is currently selected, the button will create either a child or grandchild document. This is accomplished by checking the form name of the selected document.

If the current document in the view is a Response, then we know to create a Response to Response document. Otherwise, we know the current document is a parent, and therefore we create a child document. In other words, users will be able to use a single button for both types of Response documents. This button will only display if the document has already been posted.

Select the Create > Design > Shared Action menu options and name the button Reply in the properties dialog. Next, switch to tab 2. Check the Hide action if formula is true option and add the following to the formula window of the properties dialog.

@IsNewDoc

Add the following in the Programmer's pane. Save and close the design element.

Form := @If (@IsResponseDoc; "ResToRes"; "Res" );
@PostedCommand([Compose]; Form)

 

New Category Button

This button allows the application administrator to dynamically create discussion topic categories. Only select users will have authority to see this button and create new categories. This ability is managed through the ACL. Only users with the "Admin" role in the ACL will be permitted to create a new category or access the related view.

To create the button, select the Create > Design > Shared Action menu options and name the button New Category. Next, switch to tab 2. Check the Hide action if formula is true option and add the following to the hide formula window within the properties dialog.

!@IsMember("[Admin]";@UserRoles)

Next, close the property window and add the following in the Programmer's pane. Afterward, save and close the design element.

@Command([Compose]; "Cat")

 

Subscribe Button

The Subscribe button allows users to manage email notifications for the discussion forum. This button will create a new subscription document in the database for the user. Select the Create > Design > Shared Action menu and name the button Subscribe.

@Command([Compose]; "Subscribe")

 

Submit Button

The Submit button is used to post new discussion topics and trigger the email notifications to registered users. This button also calls a subroutine that ensures that all required fields on the document have been completed before saving the document. The Submit button only appears for new documents. After the document has been submitted, the button is hidden.

Select the Create > Design > Shared Action menu and name the button Submit in the properties dialog. Next, switch to tab 2. Check the Hide action if formula is true option and add the following to the formula window of the properties dialog.

!@IsNewDoc

Close the property window and add the following in the Programmer's pane. Change the language type from Formula to LotusScript. Now, in the Programmer's pane, select the (Options) section and add the following statement.

Use "DiscussionForum"

Next add the following in the Click event section of the Programmer's pane. This subroutine calls the front-end save function and includes an On Error call. In some cases, Lotus Notes may throw an exception error when trying to synchronize the front-end and back-end documents when the document is just being created. However, because this error will not affect the overall processing and functionality of the application, we'll use the On Error branch to catch the error and continue. Afterward, save and close the design element.

Sub Click(Source As Button)

 On Error Goto oops
 Dim w As New NotesUIWorkspace
 Dim uidoc As NotesUIDocument
 Set uidoc = w.CurrentDocument
 uidoc.save
oops:
 Exit Sub

End Sub

Note

The email notifications are triggered after the document is saved using both the QuerySave and QueryClose events. Using this approach, notifications can be triggered by using the Submit button or through the Esc key to close the document.

 

Create the Forum Fields Subform

The Main Topic, Response, and Response to Response forms each have several fields in common. Instead of creating separate fields on each form, this project will utilize a subform. These objects can be maintained from a single location if changes are needed. After the subform is created, it will be added to each of the three formsMain Topic, Response, and Response to Response (created later in the project).

To create the subform, select the Create > Design > Subform menu options. After the subform has been created, add the following field descriptions down the left side of the form.

• Author:
• Created:
• Details:

Next, select the Create > Field menu options for each of the following fields. Be sure to set the data type in the field properties dialog and set the default value formula for each field in the Programmer's pane.

Field Name	Type	Default Value Formula	Remarks
Authors	Authors, Computed when Composed	@UserName
Created	Date/Time, Computed when Composed	@Now	On tab 2 select the Display Time setting. Make sure both the date and time options are selected.
Body	Rich Text, Editable		Add the Body field below the "Details" text label.

To complete the subform, two shared action buttons need to be addedReply and Submit. These buttons will be used on all three documents. Select the Create > Action > Insert Shared Action menu options, choose both buttons, and click Insert to add them to the subform. Click Done to close the Insert Shared Action dialog window. The subform should now look like Figure 9.4.

Figure 9.4. ForumFields subform

Save and close the design element. Title the subform ForumFields when prompted.

Create the New Topic Form

With the script library, subform, and shared actions in place, the next step is to create the main discussion topic form. This form will be used to post new discussion topics (or parent documents) to the forum. To create the form, click the New Form button or select the Create > Design > Form menu options.

After the form has been created, add a descriptive text title such as Discussion Topic at the top of the form and the following field descriptions down the left side of the form.

• Topic:
• Category:

Next, add the fields as specified in the following table. To create a field, select the Create > Field menu options. Be sure to set the data type, formula, and other attributes for each field on the form using the properties dialog box and/or Programmer's pane.

Field Name	Type	Default Value Formula	Remarks
Topic	Text, Editable	Topic
Category	Combobox, Editable	Category	In tab 2 of the properties dialog, select Use formula for choices and add the following in the formula window:   [View full width] REM {Set a default value if no categories setup}; REM {Otherwise, display the selected category}; DefaultCat := "General"; Class :=""; Cache := "NoCache"; Host := ""; View := "Category"; Column := 1; output := @Unique(@DbColumn(Class:Cache; Host; view; Column)); @If (output = ""; DefaultCat; output)

 

Set the Form Objects and Properties

Next, locate the "(Globals) Untitled" section in the Objects tab of the Programmer's pane. This section is located at the very top of the Objects pane. You many need to scroll up to locate this section. Click on (Options) and add the following statement in the Programmer's pane:

USE "DiscussionForum"

This statement ties the form and script library together. Without this statement, Lotus Notes will not be able to locate the subroutines and functions.

QuerySave Event

Insert the following in the QuerySave event of the Programmer's pane. This will call the LotusScript library function (described earlier in the project).

Sub Querysave(Source As Notesuidocument, Continue As Variant)

 Continue = SaveForm()

End Sub

 

QueryClose Event

Insert the following in the QueryClose event of the Programmer's pane. This will call the LotusScript library subroutine (described earlier in the project).

Sub Queryclose(Source As Notesuidocument, Continue As Variant)

 Call CloseForm

End Sub

To complete the form, insert the ForumFields subform. Place the text cursor just below the Category field and select the Create > Resource > Insert Subform menu options. When prompted, select the ForumFields subform and add it to the form.

Select the File > Save menu options. When prompted, title the form New Topic | Topic. The form should now look like Figure 9.5.

Figure 9.5. New Topic form

Close the form when complete.

Create the Response Form

The Topic form will be used as the basis for the Response form. From the Design pane, highlight the Topic design element form and select the Edit > Copy menu options. Now select the Edit > Paste menu options and open the form in the Designer client.

Next, select Design > Form Properties to display the Form properties dialog. Change the form name to Response | Res and the form type to Response. Now switch to tab 2 and select the Formulas inherit values from selected document option located at the top of the properties dialog (see Figure 9.6).

Figure 9.6. Form properties dialog

Next, you will need to change several of the design elements on the form. Click on the Categories field and select Design > Field Properties to display the field properties dialog. On tab 1, change the field type from Combobox to Text and make this a Computed field. Close the properties dialog.

Now replace the descriptive text title at the top of the form. Change the text label from Discussion Topic to Response. The form should now look like Figure 9.7.

Figure 9.7. Response form

Save and close the form.

Create the Response to Response Form

This form will be based on the Response form. From the Design pane, highlight the Response form and select the Edit > Copy menu options. Now select the Edit > Paste menu options and open the form in the Designer client.

Next, select Design > Form Properties to display the form properties dialog. Change the form name to Response To Response | ResToRes and set the form type to Response to response. Close the properties dialog.

Next, replace the descriptive text title at the top of the form. Change the text label to Response to Response. Save and close the form.

Create the Category Form

This category form will be used to create new discussion topic categories or classifications. The values stored in this form will be used to populate the Category combobox field on the parent or main document. To create the form, select the Create > Design > Form menu options.

Next, create a text label called Category and a new field immediately below the label Category field. To create a field, select the Create > Field menu options. Be sure to set the data type, formula, and other attributes for each field on the form using the properties dialog box and/or Programmer's pane.

Field Name	Type	Default Value Formula	Remarks
Category	Text, Editable

This form will only be accessible to users assigned the "Admin" role in the ACL. To help manage who can create new categories, you will need to remove the form from the application menu, update the access permissions for the form, and create a button on the view that selectively allows categories to be created (which is performed later in the project).

To remove the form from the menu, select the Design > Form Properties menu options. On tab 1, uncheck the Include in menu option.

To set the Who can create documents with this form property, switch to tab 7 (see Figure 9.8). Uncheck the All authors and above option and select [Admin] (which will most likely be at the bottom of the listbox).

Figure 9.8. Security tab of the Form properties dialog

Save the form. When prompted, title the form New Category | Cat and close the design element.

Create the Subscription Form

This form is used to register discussion forum users. Here, users can set email notification preferences based on discussion forum categories. Users can elect to receive email notices for all discussion forum topics or only a select few. This form also allows users to enable or disable notices altogether. To create the form, select the Create > Design > Form menu options.

Next, label the form Forum Subscription at the top of the form and add the following text labels down the left side.

• Name:
• Notes Email:
• Internet Email:
• Notifications:
• Categories of Interest:

Select the Create > Field menu options and create fields based on the following table. Be sure to set the data type, formula, and other attributes for each field on the form using the properties dialog box and/or Programmer's pane.

Field Name	Type	Default Value Formula	Remarks
Name	Text, Editable	@Name([CN];@UserName)
NotesMail	Text, Editable	@Name([Abbreviate]; @UserName)
InternetMail	Text, Editable	[View full width] @LeftBack(@NameLookup([NoUpdate]; @UserName; "Shortname"); ";")
AllowEmails	RadioButton, Editable		Select Enter choices one per line in tab 2. Insert the default choices in the choices field. Yes, send me notifications |-1 No, do not send me notifications |0
Category	Checkbox, Editable	Category	Select Use Formula for choices in tab 2. Add the following formula.   [View full width] REM {Set default category}; DefaultCat := "General"; REM {Retrieve select if specified}; Class :=""; Cache := "NoCache"; Host := ""; View := "Category"; Column := 1; output := @Unique(@DbColumn(Class : Cache; Host; view; Column)); @If (output = ""; DefaultCat; "All":output)

 

Define Who Can Update the Forum Subscription

Only the person that subscribes to the forum should have the ability to modify notification preferences. To define who can update the subscription, an Authors field needs to be added to the form. This will ensure that only the author of the document can change the document.

Insert a blank line at the top of the form above the Forum Subscription title. Next, select the Create > Field menu options and create the following field. Be sure to set the data type, formula, and other attributes for each field on the form using the properties dialog box and default value in the Programmer's pane.

Field Name	Type	Default Value Formula	Remarks
Author	Authors, Computed when composed	@UserName	On tab 6, select Hide paragraph when formula is true and add the formula: 1

Save the form. When prompted, name the form Subscribe | Subscribe. The form should now look similar to Figure 9.9.

Figure 9.9. Subscribe form

Close the form after all updates are complete.

Create the By Topic View

By default, a view called (untitled) was automatically created when the database was first created. To configure this view, navigate to Views in the Design pane and double-click on the view called "(untitled)".

When the view is displayed, the Designer client will immediately display the properties dialog for the view. Specify 1. By Topic in the name field and Topic in the alias field. The view has been named, so you can close the dialog window.

Column 1

This column will display the number of Response documents associated with the parent document. To configure this column, click on the predefined column header (#) and select the Design > Column Properties menu options. Set the column width to 2.

A.9.1

Next, change the Language Selector from Simple Function to Formula and add the following in the Programmer's pane.

@If(!@IsResponseDoc; @DocDescendants("0"; "%"; "%"); "")

 

Column 2

The second column will be used to sort the documents in the view. This will be a hidden column. Select the Create > Append new column menu options to add a new column.

In the properties dialog, set the column width to 1 on tab 1, set the sort type to Ascending in tab 2, and select the Hide column option in tab 6.

Next, select Creation Date as the simple function in the Programmer's pane.

Creation Date

 

Column 3

This column will display all child and grandchild documents. This will be a hidden column. Select the Create > Append new column menu options to add a new column.

In the properties dialog, set the column width to 1 and select the Show twistie when row is expandable and Show Responses Only options in tab 1. Make sure these options are selected. Without these options selected, the view will not work properly.

Then change the Language Selector from Simple Function to Fields and select the following in the Programmer's pane.

Topic

 

Column 4

This column will display all parent documents. Select the Create > Append new column menu options to add a new column.

In the properties dialog, set the column title to Topic, set the width to 45, and select Show twistie when row is expandable on tab 1. Set the font style to Bold and text color to Blue on tab 3.

Then change the Language Selector from Simple Function to Fields and select the following in the Programmer's pane.

Topic

 

View Selection Formula

The view selection formula determines what documents are selected and displayed in the view. To set the selection formula, click inside the view (as opposed to a column header) to give the view focus. Then locate the View Selection section in the Programmer's pane. Change the Language Selector from Simple Search to Formula and add the following in the Programmer's pane.

SELECT Form = "Topic" | Form = "Res" | Form = "ResToRes"

 

Action Buttons

To complete the view, two action buttons need to be addedNew Topic and Reply. These buttons will allow the user to click on a button to add a new parent, child, or grandchild topic to the discussion forum. Select Create > Insert Shared Action to add these buttons. When the popup dialog box displays, insert first the New Topic button followed by the Reply button. Click Done after the buttons have been added. Your view should look like Figure 9.10.

Figure 9.10. By Topic view

Save and close the view.

Create the By Category View

With one view already in place, you'll use this as the basis for the By Category view. This is achieved by making a copy of the By Topic view and then modifying it.

In the Design pane, highlight the 1. By Topic view design element and select the Edit > Copy menu options. Now select the Edit > Paste menu options. Double-click on the Copy of By Topic view to open it in design mode.

Select the Design > View Properties menu options. In the properties dialog, change the view title to 2. By Category and the view alias to By Category.

Note

Be sure to specify By Category for the alias. Another view in the database will be named Category. These alias names must be unique.

The next step will be to update the columns in the view. You will need to insert a new column as the first column in the view. This column will be used to sort and display documents based on the discussion topic category name.

To insert the column, select the Create > Insert New Column menu options. This action will insert a new column and shift all existing columns to the right.

In the properties dialog, set the column width to 1 and select the Show twistie when row is expandable option. On tab 2, set the sort order to Ascending and type to Categorized. Last, set the font text color to Blue and Bold on tab 3.

Then change the Language Selector from Simple Function to Fields and select the following in the Programmer's pane.

Category

Save and close the view.

Create the By Author View

The By Author view will display documents grouped by author. Using this view, users will be able to find documents based on the person that posted the discussion topic. To create the view, select the Create > Design > View menu options.

When prompted, set the view name to 3. By Author|By Author. Next, change the Copy style from view field to -Blank-. To set this value, click the Copy From button. Finally, change the selection conditions to By Formula and insert the following in the dialog box.

SELECT Form = "Topic" | Form = "Res" | Form = "ResToRes"

The dialog box should look like Figure 9.11.

Figure 9.11. Create View dialog

Click Save and Customize to create the view and open it in edit mode.

Column 1

This column will display the total number of documents posted by an author. In this view, both the parent and Response documents will be grouped together based on the author's name. To compute the total number of documents, you'll use a built-in function that counts documents by category.

To configure this column, click on the predefined column header (#) and select the Design > Column Properties menu options. Set the column width to 2 on tab 1. Then switch to tab 2 and change the Totals field from None to Total. Also select the Hide detail rows option (see Figure 9.12).

Figure 9.12. Sort tab of the Column properties dialog

Next, change the Language Selector from Simple Function to Formula and add the following in the Programmer's pane.

1

At this point, you've configured the column to count the documents associated with an author. However, for the count to be accurate, the view properties will also need to be modified. Otherwise, the count total will be incorrect.

Select the Design > View Properties menu options. Switch to tab 2 and uncheck the Show response documents in a hierarchy option (see Figure 9.13). This option must be disabled in order to correctly count the number of documents in the category.

Figure 9.13. Information tab of the View properties dialog

 

Column 2

This column will display the author's name. Select the Create > Append New Column menu options.

In the properties dialog, set the column width to 1 and select the Show twistie when row is expandable option. On tab 2, set the sort order to Ascending and Categorized. Next, switch to tab 3 and set the font text color to Blue and Bold.

Next, change the Language Selector from Simple Function to Formula and add the following in the Programmer's pane.

@Name([CN]; Authors)

 

Column 3

This column is used to sort documents in the view and will be hidden. Select the Create > Append New Column menu options.

In the properties dialog, set the column width to 1, set the sort type to Ascending in tab 2, and select the Hide column option in tab 6.

Next, select Creation Date as the simple function in the Programmer's pane.

Creation Date

 

Column 4

This column will display all parent documents. Select the Create > Append new column menu options to add a new column.

In the properties dialog, set the column title to Topic, set the width to 45 on tab 1, and close the properties dialog.

Then change the Language Selector from Simple Function to Fields and select the following in the Programmer's pane.

Topic

 

Action Buttons

To complete the view, two action buttons need to be addedNew Topic and Reply. These buttons will allow the user to click on a button to add a new parent, child, or grandchild topic to the discussion forum. Select Create > Insert Shared Action to add these buttons. When the popup dialog box displays, insert first the New Topic button followed by the Reply button. Click Done after the buttons have been added.

Save and close the view.

Create the Subscriptions Administration View

The Subscription view, along with the next three views, will be used to manage the discussion forum settings. This first view will allow users to register or subscribe to the discussion forum. Here, users can enable and disable notifications, select categories of interest, or remove themselves altogether.

The By Author view will display documents grouped by author. Using this view, users will be able to find documents based on the person that posted the discussion topic. To create the view, select the Create > Design > View menu options.

When prompted, set the view name to 4. Admina. Subscriptions|Subscriptions. Next, change the Copy style from view field to -Blank-. To set this value, click the Copy From button. Finally, change the selection conditions to By Formula and insert the following in the dialog box.

SELECT Form = "Subscribe"

Note

The backslash in the view name is used to create a cascaded view menu. This allows you to group related views together.

Click Save and Customize to create the view.

Column 1

This column will display all users that have subscribed to the forum. To configure this column, click on the predefined column header (#) and select the Design > Column Properties menu options. Set the column name to Name on tab 1. Switch to tab 2 and set the sort preference to Ascending.

Then change the Language Selector from Simple Function to Fields and select the following in the Programmer's pane.

Name

 

Column 2

This column will display the Lotus Notes email address setting for the user. Select the Create > Append new column menu options. In the properties dialog, set the column title to Email and width to 20.

Then change the Language Selector from Simple Function to Fields and select the following in the Programmer's pane.

NotesMail

 

Action Buttons

To complete the view, you will need to add the Subscribe action button to the view. To add the button, select Create > Insert Shared Action. When the popup dialog box displays, select and insert the Subscribe button.

Save and close the view.

Create the Categories Administration View

This view will display all discussion forum categories. The contents of this view will also be used to populate the Category combobox on the Topic forum. To create the view, select the Create > Design > View menu options.

When prompted, set the view name to 4. Admin. Categories|Category. Next, change the Copy style from view field to -Blank-. To set this value, click the Copy From button. Finally, change the selection conditions to By Formula and insert the following in the dialog box.

SELECT Form = "Cat"

Click Save and Customize to create the view.

Column 1

This column will display all categories for the forum. To configure this column, click on the predefined column header (#) and select the Design > Column Properties menu options. Set the column name to Category on tab 1 and column width to 20 on tab 1. Switch to tab 2 and set the sort preference to Ascending.

Then change the Language Selector from Simple Function to Fields and select the following in the Programmer's pane.

Category

 

Action Button

To complete the view, we'll add the New Category action button to the view. To add the button, select Create > Insert Shared Action. When the popup dialog box displays, select and insert this button.

Note

The New Category button will not display when running the database in Local mode. This button will only display when the application is running on the server and the user has been assigned the "Admin" role. We'll explain how to create a role later in the project.

However, by selecting the Enforce consistent ACL option on the Advanced tab of the ACL properties, the users with the "Admin" role will be able to see the button.

Save and close the view.

Create the Email Queue Administration View

This view will be used for server-based email notifications. This view will contain a list of all newly posted topics that have yet to be sent to the list of forum subscribers. Specifically, the view will contain all documents whose status flag is set to "POSTED".

A scheduled agent will then query this view on a regular interval (say every five minutes). If documents are found in the view, the agent will notify all forum subscribers, change the status flag to "COMPLETE", and remove the document from the view. To create the view, select the Create > Design > View menu options.

When prompted, set the view name to 4. Adminc. Email Queue|EmailQue. Next, change the Copy style from view field to -Blank-. To set this value, click the Copy From button. Finally, change the selection conditions to By Formula and insert the following in the dialog box.

SELECT Form = "Topic" | Form = "Res" | Form = "ResToRes"

Click Save and Customize to create the view.

After the view is created, select the Design > View Properties menu options. Switch to tab 2 and uncheck the Show response documents in hierarchy option. This step is very important. If you miss this step, all child and grandchild documents will be omitted from the email queue.

Column 1

This column will display the author of the discussion topic. In the properties dialog, set the column title to Author.

Make sure the Language Selector is set to Simple Function and select the following value in the Programmer's pane.

Author(s) (Simple Name)

 

Column 2

This column will display the creation date for the discussion forum topic. Select the Create > Append New Column menu options to add the column. In the properties dialog, set the column title to Created On and width to 14.

Make sure the Language Selector is set to Simple Function and select the following value.

Creation Date

 

Column 3

The last column for the view will display the title of the discussion topic. Select the Create > Append New Column menu options to add the column. In the properties dialog, set the column title to Topic and width to 40. In the Programmer's pane, change the display type to Field and select the following value.

Topic

Save and close the view.

Create an Email Scheduled Agent

This section describes how to create a scheduled agent used to manage server-based email notifications for new discussion topics. This agent can be implemented in lieu of the SendNotication subroutine call in the QueryClose event for parent, child, and grandchild forms. To create the agent, select the Create > Design > Agent menu options.

After the agent is created, the properties dialog will display. Set the agent name to SendNewPostings and select On schedule as the trigger type (see Figure 9.14).

Figure 9.14. Agent properties dialog

Next, click the Schedule to set the run frequency. This will display a secondary dialog window. Set the agent to run on five-minute intervals and also change the field Run on to -Any Server-.

Note

It's very important to use the correct setting in the Run on field. This value must be set to -Any Server- or to a specific server name for the scheduled agent to run (see Figure 9.15).

Figure 9.15. Schedule settings for an agent

Click OK to accept the schedule settings and close the agent properties dialog window.

Agent LotusScript Routine

The next step will be to create the LotusScript routines for the scheduled agent. Start by changing the Language Selector to LotusScript.

Next, insert the following LotusScript code in the (Options) section of the Programmer's pane.

Option Public
USE "DiscussionForum"

Add the following code in the Initialize section.

Sub Initialize

 Call SendNewPostings

End Sub

Save and close the agent.

Note

For this agent to run correctly on the server, you will need to "sign" the agent using either the server root certificate or an ID that has sufficient rights to run restricted agents on the server. If the agent is not signed or the last person to edit the agent has insufficient authority to run agents on the server, then the scheduled agent will not run. Contact your Domino server administrator to ensure that the agent is signed with an authorized ID. See Chapter 19, "Security," for additional information regarding application security.

 

Security

Now that the database design is complete, the last step is to configure the database security settings in the ACL. As mentioned at the start of this project, this application applies some granularity to the security using "roles" to manage who can create categories.

Select the File > Database > Access Control menu options. By default, the Basics tab should be active. Click on the -Default- user in the center of the screen. Change the access field (right side) to Author. Also select the Create Documents and Delete Documents checkboxes. These options will allow only the author of the appointment and anyone listed in the editors field to modify or delete the appointment.

Next, identify the person who will manage the application. Click the Add button (located at the bottom of the ACL dialog window) to add a user. After the user has been added, give the person Editor access and select the [Admin] role.

Congratulations, the project is now complete (see Figure 9.16)!

Figure 9.16. Completed project

Project B Build a Project Control Notebook