Example Templates for PERCEPS

These example templates and filters were created by Mark Peskin.

The example uses several template files to generate html. Here is the primary template, CLASS.html.tmpl, that defines the frames for each page:


<html><head><TITLE>class {classname}{templ}</TITLE>
</head>
<FRAMESET Rows="*,110" >

  <FRAME Name="Description" SRC="{classfile}_desc.html" MARGINWIDTH=15 MARGINHEIGHT=20 Scrolling="Auto">
  
  <FRAMESET  Cols="*,150">
    <FRAME Name="CGraph" SRC="{classfile}_appl.html" MARGINHEIGHT=0 MARGINWIDTH=0 Scrolling="No">
    <FRAME Name="CIndex" SRC="smindex.html#{name}" MARGINHEIGHT=5 MARGINWIDTH=5  Scrolling="Auto">
  </FRAMESET>

</FRAMESET>

As you can see, the above template defines three frames. "Description" is the main frame containing the desciption of the class. "CGraph" contains the ClassGraph java applet for each class. Finally, "CIndex" contains a listing of all the classes. Below is the template file CLASS_desc.html.tmpl that generates the pages for the "Description" frame. It is by far the most complex in this example, and uses most of the availiable template tags. Note the use of foreach loops and if-then-else statements:


<html><head><TITLE>Description of {classname}</TITLE><BASE TARGET="_parent" ></head>
<body BGCOLOR=#FFFFFF>
<FONT FACE="Helvetica">
<DL><DT>
<FONT SIZE=4>{ if templ} template { endif} {if struct} struct {endif}
{else} {if union} union {endif}{else} class {endelse} {endelse}
</FONT>
<FONT SIZE=5><B>{classlinked}{templ}</B></FONT>
{if parents}
  <FONT SIZE=4> : {parents} </FONT>
{endif}
<br><br>

<DD><FONT FACE="Times" SIZE=4>
{if brief}  <B>{brief}</B> {if detail} <p> {endif} {else}  <br><br> {endelse} {endif}
{if detail} {detail}  <br><br>{endif}
{if italic} <I> {italic} </I> <br><br> {endif} 

</DL></FONT>

<FONT SIZE=4>Members:</FONT><br><br>
<UL>
{if public}

<LI><FONT SIZE=3><B>Public:</B></FONT><br><br>
<DL>

{foreach public}

   {include memberlisting}

<br>
{next public}

</DL>
<br><br>
{endif public}
{if protected}

<LI><FONT SIZE=3><B>Protected:</B></FONT><br><br>

{foreach protected}

   {include memberlisting}

<br>
{next protected}
<br><br>
{endif protected}
{if private}

<LI><FONT SIZE=3><B>Private:</B></FONT><br><br>

{foreach private}

   {include memberlisting}

<br>
{next private}
<br><br>
{endif private}
{if friend}

<LI><FONT SIZE=3><B>Friends:</B></FONT><br><br>

{foreach friend}

   {include memberlisting}

<br>
{next friend}
<br><br>
{endif friend}
</UL>
{if author} Programmer: { author } {endif}
</FONT>
</body>
</html>

The next template, CLASS_appl.html.tmpl, which generates pages for the "CGraph" applet frame, is relatively simple. Note the use of arguments in the {applet} tag to control the applet's appearance and behavior:


<html><head><TITLE>ClassGraph for class {name}</TITLE><BASE TARGET="Main" ></head>
<BODY BGCOLOR=#0048B9>
<CENTER>
{applet target=_parent background=0048B9 textcolor=ff0000 maintextcolor=ffff41 linecolor=ffff41 textincolor=ffff41 textdowncolor=00ff6f}
</CENTER>
</HTML>

Finally the smindex.html.tmpl template (for the "Cindex" frame) contains a simple loop over all of the classes:


<html><head><TITLE>Example Class Index</TITLE><BASE TARGET="_parent" ></head>
<body BGCOLOR=#FFFFFF>

<FONT FACE="Helvetica" SIZE=2>

{foreach class}

<A NAME="{name}" HREF="{classfile}.html">{classname}</A><BR>

{next class}

</FONT>
</body>
</html>

In addition there is a index.html.tmpl to create a "main" index for the classes (this is the first page you see):


<html><head><TITLE>Example Class Index</TITLE></head>
<body BGCOLOR=#FFFFFF>
<CENTER>
<BR>
<A HREF="author_index.html">Click Here for Index by Author</A>
<P>
<TABLE BORDER=0 CELLPADDING=10>
<CAPTION><FONT SIZE=4><B>Example Class Index</B></FONT></CAPTION>

{foreach class}

<TR >
  
  <TD  ALIGN=RIGHT VALIGN=TOP><A HREF="{classfile}.html">
      <FONT FACE="Helvetica" SIZE=3><B>{classname}{templ}</B></FONT></A></TD>
  <TD VALIGN=TOP><FONT FACE="Times" SIZE=3><B>{brief}</B></TD>
  
</TR>

{next class}

<TR >
  
  <TD  ALIGN=RIGHT VALIGN=TOP><A HREF="other.html">
      <FONT FACE="Helvetica" SIZE=3><B>Other Documented Items</B></FONT></A></TD>
  <TD VALIGN=TOP><FONT FACE="Times" SIZE=3><B>Other non-class items
     documeted by PERCEPS</B></TD>
  
</TR>

</TABLE>
</BODY>
</HTML>

Finally, the file author_index.html.tmpl shows off some of the capabilities introduced in PERCEPS 2.0. It creates a listing of classes by the "author" global variable. It also lists the modification date of the classes header file (which has been passed to a plugin filter, time.flt, to extract the month and day). This is a particularly good illustration of how perceps can be useful in a groupware context:


<html><head><TITLE>Example Class Index</TITLE></head>
<body BGCOLOR=#FFFFFF>
<CENTER>
<TABLE BORDER=3 CELLPADDING=10>
<CAPTION><FONT SIZE=4><B>Class Index by Author</B></FONT></CAPTION>

<TR>
  <B>
  <TD ALIGN=CENTER>Class</TD>
  <TD ALIGN=CENTER>Modified</TD>
  <TD ALIGN=CENTER>Description</TD>
  </B>
</TR>

{foreach author all}
{foreach class}
{if first}
<TR>
  <TD COLSPAN=3 ALIGN=CENTER>
    <FONT FACE="Helvetica" SIZE=4><B>
    {if !author}Other Authors{endif}{else}{author}{endelse}
    </B></FONT>
  </TD>
</TR>
{endif}
{nobreak}

<TR >{br}
  
  <TD  ALIGN=CENTER VALIGN=TOP><A HREF="{classfile}.html">
      <FONT FACE="Helvetica" SIZE=3><B>{name}{templ}</B></FONT></A></TD>
  <TD ALIGN=CENTER VALIGN=TOP><FONT FACE="Times" SIZE=3><B>{modtime}</B></TD>
  <TD VALIGN=TOP><FONT FACE="Times" SIZE=3><B>{brief}</B></TD>
  
</TR>
{endnobreak}
{next class}

{next author}

</TABLE>
</BODY>
</HTML>

The template used to list non-class items in the file other.html is fairly straightforward:


<html><head><TITLE>Other Documented Items</TITLE></head>
<body BGCOLOR=#FFFFFF>
<BR><BR>
<CENTER><H3>Other Documented Items</H3></CENTER>

<BR><BR>

<B>FUNCTIONS</B><BR><BR>
<UL><DL>
{foreach func}

    <DT>{type}<B> {name}</B>({args}) {if const}const{endif}{if throws} <FONT COLOR="red"> throws {throwclass}({throwargs}) </FONT>{endif};
    <DD><FONT FACE="Times" SIZE=3>
      {if brief}  <B>{brief}</B> <br> {endif}
      {if detail} {detail} <br> {endif}
      </FONT>

<br>
{next}
</DL></UL>
<B>GLOBALS</B><BR><BR>
<UL><DL>
{foreach global}

    <DT>{type}<B> {name}</B>{if enum} {lb}{args}{rb} {endif}{else}{args}{endelse};
    <DD><FONT FACE="Times" SIZE=3>
      {if brief}  <B>{brief}</B> <br> {endif}
      {if detail} {detail} <br> {endif}
      </FONT>

<br>
{next}
</DL></UL>
<B>TYPEDEFS</B><BR><BR>
<UL><DL>
{foreach typedef}

    <DT>{type}<B> {name}</B>{if enum} {lb}{args}{rb} {endif};
    <DD><FONT FACE="Times" SIZE=3>
      {if brief}  <B>{brief}</B> <br> {endif}
      {if detail} {detail} <br> {endif}
      </FONT>

<br>
{next}
</DL></UL>
<B>MACROS</B><BR><BR>
<UL><DL>
{foreach macro}

    <DT><B>{name}</B> : {args}
    <DD><FONT FACE="Times" SIZE=3>
      {if brief}  <B>{brief}</B> <br> {endif}
      {if detail} {detail} <br> {endif}
      </FONT>

<br>
{next}
</DL></UL>
</body>
</html>

Finally, the first example uses two plugin filters. The first, time.flt, takes the default ctime time format and extracts the month and day:


sub filter {
  
  local($str)=@_;
  local ($day,$month,$date)=split(" ",$str);
  return "$month $date";
    
}

The second, param.flt, turns information in the "param" custom comment into an html table. It's a bit more involved:


sub filter {
  local($str)=@_;
  local($newstr,$pname,$pdesc);
  foreach (split("\n",$str)) {
    if(/^\s*\t(.*)/) {
      $pdesc.=" $1";
    }
    if(/^[^\t\S]*(\S+)\s*\-\s*(.*)/) {
      if($pname) {
       $newstr.="<TR><TD><B><FONT FACE=Helvetica SIZE=2>$pname</FONT></B></TD><TD><FONT FACE=Helvetica SIZE=2>$pdesc</FONT></TD></TR>\n";
      }
      $pname=$1;
      $pdesc=$2;
    }
  }
  $newstr.="<TR><TD><B><FONT FACE=Helvetica SIZE=2>$pname</FONT></B></TD><TD><FONT FACE=Helvetica SIZE=2>$pdesc</FONT></TD></TR>\n";
  $str="<BR><TABLE BORDER=2 CELLPADDING=4>\n<TR><TD><FONT SIZE=2>Parameter</FONT></TD><TD><FONT SIZE=2>Description</FONT></TD></TR>\n".$newstr;
  $str.="</TABLE>\n";
  return $str;
}