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.
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.
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:
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 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();
};
// 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:
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.
// 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;
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
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;
}
| 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;
}
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
Here are some common problems:
|
Now that you have implemented Reviewer::View, the remaining functions are relatively simple.
You can proceed to the following parts of the tutorial:
