WebCalendar Developer Guide

Table of Contents

• Introduction
• System Requirements
• Getting The Code
• Conventions
• Coding Standards
• Creating a Patch
• Translations and Languages
• FAQ
• Resources

Introduction

WebCalendar is written in PHP. Although originally written for PHP3, only PHP4 is officially supported. (It should also work on PHP5, but testing has not been completed yet.)

Tools

The following tools will be helpful in WebCalendar development:

• perl: Perl is used to check translation files to see what translations are missing. If you are using Windows, perl is included as part of the cygwin package.
• make: The "make" command is used when generating WebCalendar documentation in the docs directory. The "make" command is standard on Linux if you install certain development packages. If you are using Windows, make is included as part of the cygwin package.
• patch: The "patch" command is used to apply patches posted on the SourceForge patches area.
• diff: The "diff" command is used to create patches posted on the SourceForge patches area.
• CVS: Configuration management is managed using CVS.
• Access to Internet Explorer, Mozilla/Firefox, and Apple Safari. We try to test on all three of these platforms whenever we make any HTML or JavaScript changes. If you do not have access to all these, please test your changes on as many of these browsers as you have access to.

TIP If you are developing on a Windows system, the Cygwin package will provide command line tools that include perl, make, patch, diff and cvs.

Getting The Code

You should always be using the latest code in CVS. You can obtain the latest code using anonymous CVS. (You do not need to be an authorized WebCalendar developer). Use the following commands to checkout the latest code from CVS:

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/webcalendar login 
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/webcalendar co webcalendar

This will create a webcalendar directory. You should run these commands from one of the directories that your web server is configured to use. For example, on some Linux systems, the Apache document root is configured to be /var/www/html. So, you would change directories to that directories before checking the code out of CVS.

You only need to perform this checkout once. After the initial checkout, you can update your code with the following command (run this command from inside the toplevel WebCalendar directory):

cvs update -d

If you have modified any of the WebCalendar files, CVS will attempt to merge your changes with any changes to the same file in the new code from CVS.

For example, if you modified the includes/functions.php file on your system and a WebCalendar developer also modified this file in CVS, then when you perform the CVS update, the changes will be merged. If the merge fails, you will see a file with a .rej extension and another with .orig.

Conventions

The following conventions have been adopted by WebCalendar (although they have not been 100% enforced, so you will see exceptions):

• Function names: Use lowercase with an underscore '_' when naming functions.
  Example: dbi_query
• Database table names: All db tables are prefixed with "webcal_" and are lowercase using underscores.
  Example: webcal_user_pref
• PHP function comments: Function documentation is generated using phpDocumentor. Each function should be preceded by a DocBlock. See the phpDocumentor website for information about DocBlocks and DocBlock syntax, and see includes/functions.php for examples.
• ChangeLog: if you have access to commit your changes to CVS, please put an entry at the top of the ChangeLog file that describes the change. If the change fixes a specific SourceForge bug, then include the bug id in the description.

Coding Standards

The following coding standards have been adopted by WebCalendar (although they have not been 100% implemented).

• Indenting: Two spaces (ASCII 0x20) for each level. Wrapped lines should also be indented 2 spaces if these spaces will not affect output.
• Tabs (ASCII 0x09): This character will not be used. Replace all occurrences with ASCII 0x20. This may affect indenting, so please double check before committing to CVS or posting.
• File Format: Unix format only (LF ASCII 0x0A), no Windows or Mac format files.
• PHP file comments: Each file should have a file header.
  See report.php as an example.
• Use double quotes around html attributes
• If/Else: Always us {} when not using inline format. Either of the following is acceptable based on logic complexity.

  				
  if ( foo == 1 ) {
    bar = true;
  } else {
    bar = false;
  }
  or  
  bar = ( foo == 1 )? true : false ;
  			

• Function Calls/Declarations: Use spaces inside and around parenthesis ()

  Declaration: function getGetValue ( $name ) {
  Call: bar = getGetValue ( $name );
  

Creating a Patch File

TODO

Translations and Languages

When adding or modifying WebCalendar code, all displayed text should be translatable. The following tips will ensure new text can be translated quickly and efficiently.

• Translate: All displayable text should be sent to the translate () function, which returns the text translated in the user's language of choice. A variation of this function is etranslate (), which includes and echo command.
• Htmlentities: When used, this function tag should include the current charset when displaying database results. This will be most important when dealing with languages such as Japanese that tend to contain charactes that would otherwise be non-displayable. Although this is not the perfect solution, it seems to suffice for our purposes. Possibly, a better technique would be to use the charset of the original creator of the data, but this is beyond current capabilities.
  For reference see:

  
  http://us3.php.net/manual/en/function.htmlentities.php
  	

• TODO: Add procedures for updating Language.txt files

Frequently Asked Questions

Why aren't you using PHP sessions?

We are still considering using PHP4 sessions. In fact, the install/index.php page does use PHP sessions. The cookie-based solution that WebCalendar uses is simple, and it will work with all versions of PHP.

Why aren't you using ADODB for database access?

Again, this would be overkill for what we need. ADODB is a fairly large project, so I'm partial to my leaner php-dbi.php solution.

Why aren't you using the PEAR database functions?

WebCalendar pre-dates the PEAR database functions. There does not seem to be sufficient reason to switch from our existing code at this point.

Why aren't you using a template engine like smarty?

WebCalendar pre-dates most of the template engines out there. We are currently evaluating some of the templating options and may consider moving to one of the template systems in the future.

How do I install a patch?

Different patches are applied differently. Some patches just contain an updated file. In that case, you should be able to use replace the old file with the new (assuming the new file and your install are based on the same version of WebCalendar).

Others are patch files, which usually have a .diff or .patch file extension. In order to use one of these files, you need the GNU patch program. (This should be installed on all Linux systems and you can get a version for Windows. I use the patch program that comes with cygwin on windows.) I would recommend testing the patch on your install first using the --dry-run option.

For example, if the patch file is called calmods.diff, then you would use:

patch --dry-run < calmods.diff

If the program says it cannot determine which file to patch, try adding -p1:

patch --dry-run -p1 < calmods.diff 

If it goes through all the changes successfully, do the same command without the --dry-run option to install the patch. If it says "hunk failed", then the patch cannot be applied without hand-merging files. This essentially means that the patch was based on a version of WebCalendar that is too different than the version that you have installed, so it was unable to determine how to apply some of the changes in the patch file.

Resources

The following resources may be helpful:

• The TODO file in CVS contains ideas for future enhancements.
• The Open Discussion forum on SourceForge is a good place to ask questions about WebCalendar development.
• Bug Reports on SourceForge.
• WebCalendar Function Documentation
• WebCalendar-Database.html describes the WebCalendar database schema
• WebCalendar-Styling.html describes how WebCalendar uses CSS

Last Update: $Id: WebCalendar-DeveloperGuide.html,v 1.6 2005/03/08 02:52:33 cknudsen Exp $