Part 8. Defining the View Function for Reviewers

In this part, you will build on your existing knowledge of the VisualAge C++ IDE by repeating many of the editing, building, and navigation tasks you already learned in previous parts. You will add a new member function to the Reviewer class to support viewing documents that contain comments. You will also create two classes to support adding comments to documents. Finally, you will modify the Reviewer::View function definition so that it shows a version of an HTML file containing reviewers' comments.

This section should take you between 30 minutes and 2 hours to complete. If you are simply interested in using the review tool, you can cut and paste code into the indicated files and the section will take little time. If you want to understand CGI programming, and in particular the design of the review tool, the section will take longer.

Because you already have considerable experience adding code to functions, rebuilding your project, and recovering from build errors, this section contains less guidance than prior sections have done.

Remember, where necessary, to change any path or executable file names to the names required for your system.

Prerequisites If You Are Starting Here

You should have the following source files in a directory on your system. Click the link to see the file's contents. Any changes you may need to make for your environment are indicated in the files.

Redefine Functions

The next few sections of this tutorial provide code that you can add to your project. Under the heading for each class or member function to be added or changed in this section, you will find a brief description, followed by the required code. To replace a function definition in your source code with a new one from this part, follow these steps:

  1. In the online version of this section, select the replacement text for the function in your browser and copy it to the system clipboard.
  2. In a source view in the IDE, select the original function definition (not its in-class declaration) , and paste the clipboard contents so that they overwrite the prior definition. (If the original function is defined inline within its class, change the definition to a declaration, and add the new definition.)
  3. After several operations, rebuild your project to ensure that you copied and pasted correctly.

Move Common Code from Reader::View

Implementation Details

Currently, the Reader::View member function only adds the necessary CGI call information to all href links in a viewed document. This code is useful not only for allowing readers to view a file, but for allowing reviewers and authors to view or add comments to a file. Therefore it would be a good idea to move this code into a separate function.You will move the code from Reader::View into a new User class member function, LinkFix, and call that function from Reader::View.

In a Source view, add a public declaration for LinkFix to the User class declaration in user.hpp:

IString LinkFix();

Also, in user.cpp, change the function name of Reader::View to User::LinkFix. Do this by deleting the old function signature and typing in the new one. Then add the following new definition for Reader::View:

IString Reader::View() {
   return LinkFix();
}

CommentType and CommentSection Classes

Implementation Details

The first user function you will implement is User::View. However, before you begin, you need to implement some support classes for viewing, because a reviewer's view of a document is more complex than a reader's view. Unlike a reader, a reviewer can view comments, and can add new comments at specific points. The CommentSection class is used to hold sections of the document in which comments can be added, while the CommentType class is used to hold the comments. In this tutorial,you will add support for comments only at the start of each paragraph and list item. If you want, you can later add code of your own to handle other insertion points.

Once these classes are defined, you will declare an array of CommentSection elements in Reviewer::View. Element zero will contain all text up to the first paragraph or list item tag, and each subsequent element will contain text following the tag of the prior element, up to and including the next paragraph or list item tag. The CommentSection class will define a Print() operator that returns an IString consisting of the text up to the tag, the numbered hypertext link that allows comment entry, any comments that may exist for that entry, and the text up to the next tag.

Add the files comment.hpp and comment.cpp to the part of your configuration that contains other source files that you have defined. Then add the following code to the appropriate files:

Class declarations and inline members (comment.hpp):

class CommentType {
   IString UserId,     // ID of comment creator
           Date,       // Date comment was created
           Time,       // Time comment was created
           Text;       // Text of comment
   int LineNum,        // Line to which comment applies
       CommentNum;     // Comment number for this line
   Request* Req;       // Pointer to the current request
   IBoolean Completed;  // Whether the author has completed the comment
   public:
      // Set methods
      void SetUser(IString U) {UserId=U;}
      void SetDate(IString D) {Date=D;}
      void SetTime(IString U) {Time=U;}
      void SetText(IString U) {Text=U;}
      void SetReq(Request* R) {Req=R;}
      void SetLineNum(int L) {LineNum=L;}
      void SetCommentNum(int L) {CommentNum=L;}
      void SetCompleted(IBoolean T) {Completed=T;}
      // Constructors and print function
      CommentType() : LineNum(0), CommentNum(0), Req(0) {}
      CommentType(int Ln, int Ct, Request* R) :
         LineNum(Ln), CommentNum(Ct), Req(R) {}
      IString Print(IBoolean CompleteLink);
   };

class CommentSection {
   protected:
      IString Tag;             // Tag for this section (eg. <p>, <li>)
      IString Text;            // HTML Text following tag
      IBoolean ShowInsert;      // Whether to show the numbered link for adding comments
      IBoolean CompleteLink;    // Whether to show the "Complete" link (used for authors)
      CommentType* Comment;    // Each section can have up to 16 comments
      int Count;               // Count of comments
      Request* Req;            // Pointer to the request
      int Number;              // Number of this comment section (ie. array index)
   public:
      // Constructor
      CommentSection(): Tag(""),
                        Comment(new CommentType[16]),
                        Text(""),
                        Count(-1),
                        Number(0),
                        Req(0),
                        CompleteLink(false),
                        ShowInsert(false) {}
      // Set methods
      void SetTag(IString Tg) {Tag=Tg; }
      void SetComment(IString Text, IString User,
                      IString Date, IString Time,
                      IBoolean Completed);

      void SetText(IString Tx) { Text=Tx; }
      void SetReq(Request* Rq) {Req=Rq;}
      void SetNumber(int Num) {Number=Num;}
      void SetCompleteLink(IBoolean tf) {CompleteLink=tf;}
      void SetShowInsert() {ShowInsert=true;}
      IBoolean IncrementCount() {
         if (Count<16) {Count++; return true; }
         return false;
      }
      IString Print();
};

Non-Inline Function Definitions (comment.cpp):

// Print this comment. Each comment is contained in a one-cell
// table (so that a border is shown). If the comment is completed,
// show that it is completed. Otherwise, if CompleteLink is true
// (and this is set only in the Author override of View), show
// a link allowing the comment to be completed.

IString CommentType::Print(IBoolean CompleteLink) {
   // Print the start of the table
   IString Result=
      "<br><table border=1><tr><td>";
   // Print the User ID of the user who created the comment
   // Underscores in User ID should become spaces
   Result+="Created by: <font color=\"#005555\">"
         +UserId.change("_"," ")
         +"</font>" ;
   // Print the Date and time of comment creation
   Result+=" on: <font color=\"#005555\">"
         +Date
         +"</font> at <font color=\"#005555\">"
         +Time
         +"</font></td></tr>";
   // On a new row, print the comment text
   Result+="<tr><td>"
         +Text
         +"</td></tr>\n";
   // Indicate that comment is complete 
      if (Completed)
         Result+="<tr><td><font color=\"#FF0033\">Completed</font></td></tr>";
      // Otherwise, add link to complete it if requested by caller
      else if (CompleteLink)
         Result+="<tr><td><a href=\"review.exe?Op=Complete+key="
               +Req->GetKey()
               +"+file="+Req->GetFilename()
               +"+line="+IString(LineNum)
               +"+cmt="+IString(CommentNum)
               +"\">Mark as Completed</a></td></tr>";
   Result+="</table>\n";
   return Result;
}

// Set method for creating a comment within this comment section
// Only creates the comment if it is one of the first 16 comments
// as only 16 comments are allowed per paragraph or list item.
void CommentSection::SetComment(
       IString Text, IString User,
       IString Date, IString Time,
       IBoolean Completed) {
   if (Count>=0 && Count<16) {
       Comment[Count].SetText(Text);
       Comment[Count].SetUser(User);
       Comment[Count].SetDate(Date);
       Comment[Count].SetTime(Time);
       Comment[Count].SetReq(Req);
       Comment[Count].SetCompleted(Completed);
       Comment[Count].SetLineNum(Number);
       Comment[Count].SetCommentNum(Count+1);
   }
}
// CommentSection::Print() prints the tag for the section;
// if the section is not section 0 (everything up to the first
// paragraph or list item tag) it prints a hyperlinked number
// that allows comment insertion;
// if there are any comments for this section, it calls
// CommentType::Print() for each of them;
// finally, it prints its text, that is, the original HTML up
// to the next paragraph or list item tag.

IString CommentSection::Print() {
   IString SNumber=Number;
   IString Result=Tag;
   if (Number>0)
      Result+="<a href=\""+EXE+"?Op=ShowAdd+key="+Req->GetKey()
            +"+file="+Req->GetFilename()
            +"+line="+SNumber+"#Ct"+SNumber+"\">"+SNumber+"</a> ";
   for (int cxc=0;cxc<=Count;cxc++)
      Result+=Comment[cxc].Print(CompleteLink);
   Result+="<a name=\"Ct"+SNumber+"\">";
   Result+=Text;
   return Result;
}

Reviewer::CreateSections

Implementation Details

The CommentSection and CommentType classes do almost all of the work of handling the sections of each HTML file for you. The View function only needs to read the HTML file requested, break it up into sections, and print the sections.

Comments are stored in a file with the same name as the HTML file but in a separate directory, defined by the macro CommentRoot.

Each comment in a comment file starts with the line "<cmt>", followed by five words:

Word Meaning Example
1 Line comment applies to "4"
2 Completed or not "u" or "c"
3 User ID of creator "RGREEN" or "SBEHM"
4 Date of creation "12/04/1997"
5 Time of creation "12:23"

Subsequent lines are text of the comment. The comment ends with the line "</cmt>".

Place a declaration for this macro in your macros.hpp source file. Change the path shown below to the path where you want to store comment files on your system.

#define CommentRoot IString("g:\\vatutor\\comments")

Remember, you can edit macros from the Macros page of the Project.

The code you used here for creating sections will be used later by the Author version of View and by other member functions of the Reviewer and Author classes. To allow common access to this code, you should define a separate member function of Reviewer, which breaks up the HTML file into these sections. Place the function declaration in user.hpp and the implementation in user.cpp. As well, in user.hpp add a declaration for an array of comment sections, and a counter, CurCs, to keep track of the count of these sections, as shown below.

Declaration (user.hpp)

// Place these declarations inside the Reviewer class declaration,
// with protected access:
protected:
   void CreateSections(IString& Content, IBoolean CompleteLink=false);
   // Declare an array of comment sections
   CommentSection* Section;
   int CurCs;

Definition (user.cpp)

void Reviewer::CreateSections(IString& Result, IBoolean CompleteLink) {
    // Result contains the HTML file with href links already fixed
    // The CompleteLink argument tells CreateSections whether to show
    // a link authorizing completion of the comment (Author::View sets
    // CompleteLink, while Reviewer::View does not)
    // Create a lowercase copy for tag searching
    IString result=IString::lowerCase(Result);
    // Create a target array of 256 CommentSection objects.
    // Track total used so array can be expanded later if more than
    // 256 sections are found in document.
    // CurCs is declared in class.
    CurCs=0;
    int MaxCs=256;
    // Section is a pointer to an array of CommentSection elements;
    // initialize it now.
    Section=new CommentSection[MaxCs];
    // Search for next paragraph or list item
    // MinNonZero() will be defined in func.cpp
    int Next=MinNonZero(
        NextTag(result,"<p"),
        NextTag(result,"<li"));
    // If no such tag is found, set next to the end of the file,
    // so that the first section becomes the entire file.
    // Return when done, as no more sections need be created.
    if (Next==0) {
       Section[CurCs].SetTag(Result);
       Section[CurCs].SetReq(Req);
       CurCs++;
       return;
    } else {
    // Otherwise, set tag and comment number, and continue
       Section[CurCs].SetTag(Result.subString(1,Next-1));
       Section[CurCs].SetReq(Req);
       Section[CurCs].SetNumber(CurCs);
       CurCs++;
    }
    // Keep adding more sections
    while (Next>0) {
       // Find the end of the tag and set Tag to it
       int eTag=result.indexOf(">",Next);
       IString Tag=Result.subString(Next,eTag-Next+1);
       // Look for next paragraph or list item
       int NextNext=MinNonZero(
          NextTag(result,"<p",Next+1),
          NextTag(result,"<li",Next+1));
       IString Text="";
       // Set section to rest of text if no next tag found,
       // otherwise set text to rest of this section
       if (NextNext==0)
          Text=Result.subString(eTag+1);
       else
          Text=Result.subString(eTag+1,NextNext-eTag-1);
       // Expand the Section array if it is too small
       if (CurCs>=MaxCs) {
          MaxCs+=1;
          MaxCs*=1.25;
          CommentSection* NewCs=new CommentSection[MaxCs];
          for (int cs=0;cs<=CurCs;cs++)
             NewCs[cs]=Section[cs];
          delete[] Section;
          Section=NewCs;
          }
       // Create the CommentSection
       Section[CurCs].SetNumber(CurCs);
       Section[CurCs].SetTag(Tag);
       Section[CurCs].SetReq(Req);
       Section[CurCs].SetText(Text);
       Section[CurCs].SetCompleteLink(CompleteLink);
       CurCs++;
       Next=NextNext;
    } // End of While
    // Open the comment file and read in any comments
    // Comments are delimited by <cmt> and </cmt>
    ifstream CommentFile(Req->GetCommentFn());
    while (CommentFile) {
       IString CommentLine=IString::lineFrom(CommentFile);
       IBoolean Completed=false;
       if (CommentLine.isLike("<cmt>*")) {
          int CmtNum=CommentLine.word(2).asInt();
          if (CommentLine.word(3)=="c") Completed=true;
          IString User=CommentLine.word(4);
          IString Date=CommentLine.word(5);
          IString Time=CommentLine.word(6);
          IString Text=IString::lineFrom(CommentFile);
          IString NextLine=IString::lineFrom(CommentFile);
          while (CommentFile && NextLine!="</cmt>") {
             Text+=NextLine+"\n";
             NextLine=IString::lineFrom(CommentFile);
          }
          // Add a comment type to this comment section if the comment is valid
          if (Text!="" && CmtNum>0 && CmtNum<CurCs && Section[CmtNum].IncrementCount())
             Section[CmtNum].SetComment(Text,User,Date,Time,Completed);
       } // end outer if
    } // end while
 } // end function

Reviewer::View

The View function contains very little code of its own; most of this code has been moved out to the CommentType and CommentSection funciton and to the Reviewer::CreateSections function. Change the definition of Reviewer::View to the following:

IString Reviewer::View() {
    // 1. Get the file contents
    IString Result=LinkFix();
    if (Result=="")
      return Error("Could Not Read File",
         "The file you requested, "+Req->GetFilename()
        +", could not be read, or was empty.");
    // 2. Initialize the CommentSection Array.
    CreateSections(Result, false);
    // 3. Print the CommentSections
    Result="";
    for (int cs=0;cs<CurCs;cs++) Result+=Section[cs].Print();
    return Result;
    }

NextTag and MinNonZero (funcs.cpp)

Implementation Details: The NextTag function searches for the next occurrence of a tag in a string. Because a tag can have attributes, NextTag looks for the first match that contains the opening brace and name of the tag followed by a closing brace, space, or new line. The MinNonZero function, which is overloaded for two and three arguments, returns the lowest nonzero value of a set of nonnegative values.

Add the following definition for these two functions to funcs.cpp:

int NextTag(IString String, IString Tag, int StartPos=1) {
   return MinNonZero(
      String.indexOf(Tag+">",StartPos),
      String.indexOf(Tag+" ",StartPos),
      String.indexOf(Tag+"\n",StartPos));
   }
int MinNonZero(int a, int b, int c=0) {
   if (c>0) return MinNonZero(a,MinNonZero(b,c));
   if (a==0) return b;
   if (b==0) return a;
   if (a>b) return b;
   return a;
   }

Request::GetCommentFn (request.cpp and request.hpp)

This function returns the name of the comment file, which is determined from the main HTML file name and the comment directory. Add the function's declaration as a public member of Request, in request.hpp; add its definition in request.cpp.

// In request.hpp, within public part of Request class declaration:
IString GetCommentFn();

// In request.cpp
IString Request::GetCommentFn() {
    IString CommentFn=Filename;
    CommentFn.change("/",slash);
    if (CommentFn.subString(1,1)!=slash)        // Add a leading slash
       CommentFn=slash+CommentFn;
    // Add path to start of file.  
    // CommentRoot is defined in macros.hpp
    CommentFn=CommentRoot+CommentFn;
    return CommentFn;
 }

Test the New Implementation of Reviewer::View

You have not yet implemented the ShowAdd or Add functions, so you cannot add comments to test whether the View function is working properly. You can, however, test View by copying the following text and placing it in a file in your comment root directory. Give that file the same name as an HTML file in your web root directory, for example, index.html:

<cmt> 1 c Peter_Schmidt 11/14/1997  10:06
Please add the phrase "notwithstanding the turbulence of clouds,"
</cmt>
<cmt> 3 u Roberta_Verdi 11/14/1997  11:17
I believe you need more information on aardvarks here.
</cmt>
<cmt> 1 u The_Author 11/14/1997  12:38
I have made the change Peter requested. Time for lunch!
</cmt>

Try viewing the HTML file using your CGI: http://localhost:49213/cgi-bin/review.exe?op=View+key=reviewer+file=index.html

The text should look something like the following:

1
Created by: Peter Schmidt on: 11/14/1997 at 10:06
Please add the phrase "notwithstanding the turbulence of clouds,"
Completed
Created by: The Author on: 11/14/1997 at 12:38
I have made the change Peter requested. Time for lunch!

Here are some common problems:

  • 2 Some links are offsite
  • 3
    Created by: Roberta Verdi on: 11/14/1997 at 11:17
    I believe you need more information on aardvarks here.

    Some links are to nonexistent frames

  • 4 Some links are to different frames
  • 5 Some links have uppercase attributes
  • 6 Some links are syntactically invalid

Now that you have implemented Reviewer::View, the remaining functions are relatively simple.

You can proceed to the following parts of the tutorial: