Make your own free website on Tripod.com

phpWebSite developer documentation

Content

...more is about to come! As phpWebSite currebtly approaches stable status, a lot of the information herein may be obsoleted. Take the information contained herein with a grain of salt...


top of page

Coding style?

Below are some personal comments on the code I found when I joined phpWebSite development. But before you read that, let me introduce you to the preferred coding style.


top of page

Commenting the Code - PHPDoc

If you change code and/or write new code you should add appropriate comments. This applies to whole files (so called modules when we talk about procedural code like in phpWS, or classes when talking OO), function/method definitions, included files and important variables.

Always remember: Commenting is important! It helps you to understand other's code faster, makes it easier to understand your own code and is a Good Thing [tm] when it comes to software engineering.

If you used Java, you probably came across javadoc, which generates browseable HTML documentation by extracting specially crafted comments from the sourcecode. There is a similar tool for PHP called (who would have guessed that) PHPDoc. It has been written by Ulf Wendel and may be found in PHP CVS (currently checked in in the PEAR directory) or at http://www.phpdoc.de/. The following is a quick guide to writing the most important types of comments we would like you to use when hacking on phpWebSite..

Aside from module comments (which should come before any code in the file), comments are recognized only if found before a certain keyword. These are:

The available variable types, as far as I know, are:

Module/Class comments

These should appear at the beginning of every file or right before the class definition, and help to explain the purpose of the file. Further they give the file a name (module) and put the file in a certain group (a module group) if the file does not contain a class definition. If a class is defined in the file, all needed data is derived from the class's name and inheritance. Leave out the module and modulegroup statement in this case! All phpWebSite modules/classes should belong to the package phpWebSite. This might be helpful in the future, if code is distributed with phpWebSite that is not part of the core package (e.g. certain modules). Such a comment looks like this:

/**
 * Short explanation (1 line!)
 *
 * Some more text which explains in more detail
 * what the file does and who might be interested
 * in understanding that.
 *
 * @version [dollar sign]Id[dollar sign]
 * @author Name <email address>
 * @module modulename
 * @modulegroup group
 * @package phpWebSite
 */

Function comments

These explain in detail what a function does, what parameters it expects and what is returned by the function. Function comments apply to classes as well, here they magically turn into method comments. Such a comment appears directly above a function definition looks like this:

/**
 * Short explanation (1 line!)
 *
 * Some more text which explains in more detail what
 * the function does and who might be interested
 * in understanding that.
 *
 * @author Name <email address>, Name2 <other email address>
 * @param type description
 * @return type description
 */

Class variable and Include file comments

These are simple: They just quickly explain what a class varibale is used for, or what an included file does, or why we need it. These comments may be longer, if you have to explain more (e.g. the $dbp variable in the config file). They should appear just above the corresponding variable or include/require statement. They have to be one line and look like this. Every included file has to be commented only once in one file, even if used several times.

/**
 * Some explanation of the variable or file just below this comment.
 */

Some tips and tricks

Those of you using emacs will notice that c-mode and php-mode know those comments and indent, wrap and colourize them correctly. It might be worth trying to use one of the available javadoc editing tools (I didn't try, but if you do, let me know). You should add a single space character at the end of lines in a multi line comment - otherwise the result might look, uhm, interesting. If something seems odd - DON´T PANIC (42, you remember?). PHPDoc is still a young piece of software, not every error has to be your fault. Finally: I will try to run PHPDoc weekly and put up the results at http://www.k-fish.de/krabutzig/phpwebsite/

Some asked whether comments like the following are possible:

/*******************************************************************
 * Some explanation of the variable or file just below this comment.
 ******************************************************************/

This was meant to make the code better to navigate - but alas it does not work. Err... it works, but the results look rather funny, because the leading line of *´s is included in the generated documentation. Similar things happen to the closing line of *´s. So all I can say is: stick with exactly the format shown above. I hope this will someday be resolved in PHPDoc, until then we have to wait.

Feel free to add more comments (preferably c-style, i.e. start them with //, not #) in your code to explain what you are doing. And if you write even more detailed documentation, feel free to link them to these docs and put them in CVS.

And please take a look at the section titled "Report" in the generated API documentation. This way you can spot errors and deficiencies in the documentation and fix them.


top of page

what happens when index.php is requested

/* index.php */

include open_session.php
include mainfile.php
include config.php
set $index=1
set $storynum to either $cookie[3] or $top
include header.php

   /* header.php */
   include config.php
   CacheControl()
   DOCTYPE xhtml DTD
   if banners {include banners.php}

   function head()
      include config.php
      global variables
      if unique titles {$titelag=menu_text}
      if user {
         include $theme/theme.php

            /* $theme/theme.php */
            /* end $theme/theme.php */

         include $theme/header.php

            /* $theme/header.php */
            <head>
            <title> $sitename - if {$titletag}
            <link> to css stylesheet
            <meta>
            </head>

            <body>
            <table> for website boundaries
            <table> inner 3 column table for page layout
            display logo and search form
            display $titlebar (slogan)

            <table> for menu
            include menu.php
            display $AdminBlock if $admintest true using themesidebox
            plug_check(1,0,NULL,NULL)

            display User Login Block if {} using themesidebox	

            mysql_query SELECT leftblocks
            create array of leftblocks from query
            display array of leftblocks using themesidebox
            /* end $theme/header.php */
      }
   head()
   include counter.php
   /* end header.php */

call plug_check(2,0,NULL,NULL)
mysql_query SELECT articles limit $storynum
mysql_query SELCECT main_page_content
show main content using thememainbox 
show articles using themeindex
include footer.php

   /* footer.php */
   function foot()
      include config.php
      global variables
      if user {
         include $theme/footer.php

            /* $theme/footer.php */
            include config.php

            display poll if $active true
            display user block if $cookie[8] true				
            plug_check(3,1,flag_begin,col_begin)

            mysql_query SELECT rightblocks
            create array of rightblocks from query
            display array of rightblocks using themesidebox

            mysql_query SELECT articles limit $storynum, $oldnum
            display past articles using themesidebox				

            </table>
            </table>
            /* end $theme/footer.php */
      }

      // use of the style avoid IE5.5 and 6 problems */
      <div class=smalltextatbottom style="text-align : center">

      result = mysql_query SELECT footlines from flags
      list(footlines) = mysql_fetch_row(result)

      footlines
      </div>
      </body>
      </html>
   foot()
  /* end footer.php */

get http referrer
/* end index.php */

Many thanks to Eric T. Wallace for updating this for version 0.8.0!


top of page

what happens when content.php is requested

  1. if $mainfile is not set, include mainfile.php
  2. include header.php (see above for what happens)
  3. if $admin is set, offer link to admin.php (edit page)
  4. include layout.php
    1. grab layout for $page_id from db
    2. switch() according to layout from db
    3. now comes (almost) the same function repeatedly (6 times) for the different layouts
      include config.php (!?!)
    4. get number of sections and title, output title
    5. recurse through sections, get contents, output
  5. include footer.php (see above for what happens)


top of page

what menu.php does

  1. call menu1(), menu2() or menu3() according to $menu value:

    $menu isfunction
    <100menu1()
    <10000menu2()
    <1000000menu3()

  2. now print the menu according to it´s level (details are an exercise for the reader :o)


top of page

Themes (header.php and footer.php revisited)

If you look at the themes provided, it is not instantly clear what these files do exactly, and where the functions used within are defined. This doesn´t get better if you discover that some of them are redeclared throughout the files! This will be addressed with a theme API. Keep this in mind when reading the following, it is mostly meant to aid in developing a better scheme.

A (standard) theme currently consists of four PHP files, a CSS file and one image file.

index.php
This is just used for sending the user back to the phpWebSite index page when he tries to browse the theme directory directly.
deflogo.gif
The standard logo that appears in the upper right corner of the page.
style.css
Here the styles used in the system are defined. For some documentation about that see below (not really, though...). If you just want to change colours, fonts and the like, this is the place to experiment.
header.php
This file basically is a HTML file, containing the page´s HTML up to the point where the main content area starts. It contains PHP code to insert the title tag, the $sitename, the $titlebar, the modules (if any), the login box, events and the left blocks.
footer.php
This file basically is a HTML file, containing the page´s HTML from the point on where the main content area end. It contains PHP code to insert the poll booth, the user block, added right blocks and the past articles. This is done only if $index==1, i.e. when we are on the index page.
theme.php
This file provides some basic functions used in the header and footer files. Aside from themeindex, themeboxtop and themearticle they basically all render a box, having a title and some content. themeboxtop just outputs the beginning of a block (look at the code to understand what I mean). themeindex and themearticle are for displaying an article overview (on the index page) or the actual article.

phpWebSite always prepends a XHTML header, as required by the standards. So you must start with the <head> tag and omit the <body> tag! And it always appends the text contained in $foot1, $foot2, $foot3 to the page and closes the page by appending the closing </body> and </html> tags, so you must omit them as well.


top of page

CSS definitions

this is about...
... to come! We are thinking about a new set of styles to be used for the future theme implementation. So I think it is quite useless to document the current state. Right? I knew you´d agree :-)


Karsten Dambekalns <k.dambekalns@fishfarm.de>