WebCalendar Developer Guide
Table of Contents
Introduction
WebCalendar is written in PHP. A minimum of PHP 4.0.1 is
required to run WebCalendar due to the use of classes and sessions.
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 accomplished using CVS.
- 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 from git:
https://github.com/craigk5n/webcalendar
To obtain the code from your command line using the git command:
git clone https://github.com/craigk5n/webcalendar.git
Naming Conventions
The following conventions have been adopted by WebCalendar (although they
have not been 100% enforced, so you will see exceptions):
- Class Names
- Classes should be named using descriptive, full words. Abbreviations
should be avoided except in cases of standard acronyms such as HTML, HTTP,
etc. Names should be in UpperCamelCaps. Examples:
- RepeatingEvent
- WebCalendarSettings
Classes should be defined in files contained in includes/classes/.
Filenames should be of the form ClassName.class. There should only be one
class defined per file.
If incorporating a class from another project (i.e. phpMailer ), it is
acceptable to use the original naming conventions and filenames. This will
allow for easy upgrading and help avoid any GNU license issues.
- Method/Function Names
- Methods and functions should be named with short verb phrases.
Methods/functions which return a boolean should begin with a verb which
implies a yes/no answer (e.g. 'is' or 'has'). Names should be in
lowerCamelCaps. Examples:
- getPostValue ()
- saveEvent ()
- isAllDay ()
- Variable Names
- Variable names should be descriptive noun phrases. Counter variables
should be single letters (commonly 'i', 'j', or 'k'). Names should be in
lowerCamelCaps. Examples:
- $passwordHash
- $monthName
- $i
- Constant Names
- Constants (declared with define ()) should be named with descriptive noun phrases. Names should be in uppercase with WORDS_SEPARATED_BY_UNDERSCORES. Examples:
- Database Table Names
- Database table names should be prefixed with 'webcal_'. Names should be
in lowercase with words_separated_by_underscores. Examples:
- webcal_user_pref
- webcal_entry
- Preference Value Names
- These are variables stored in webcal_config and webcal_user_pref tables.
Names should be in uppercase with words_separated_by_underscores. Examples:
- ALLOW_HTML_DESCRIPTION
- DISABLE_ACCESS_FIELD
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)
will not be used. Replace all occurrences with ASCII 0x20. This may affect
indenting, so please double check before committing to git 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.
- 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.
- XHTML
- All XHTML should conform to XHTML 1.0 Transitional. Use double quotes around HTML attributes.
- If/Else
- Use the ternary operator (?:) whenever possible.
Curly brackets, {}, need only be used around multi-statement blocks.
Any of the following is acceptable based on logic complexity:
bar = ( foo == 1 ? true : false );
or
if ( $foo == 1 )
$pro = true;
else
$con = true;
or
if ( $bar > 0 ) {
$drink++;
$glass = 'full';
} else {
$fun--;
if ( $fun < 1)
echo 'Party is over!';
}
- Function Calls/Declarations
- Use one space both inside and outside of parenthesis ()
Declaration: function getGetValue ( $name ) {
Call: bar = getGetValue ( $name );
- Single quotes vs double quotes
- With the exception of XHTML attributes, use single quotes where possible.
echo 'This is an example of single quoting. ';
echo 'But, sometimes it\'s not possible without escaping. ';
echo "Also it's not possible with $embedded variables. ";
echo 'Control characters such as linefeed "\n" and tab "\t" don\'t work either. ';
echo 'However, it\'s preferable to concatenate' . $variables . 'like this, anyway. '
echo '"Nested quotes", she said, "are also acceptable where needed.
Just try to use single quotes as the outer set."'
- Use of the dot connector. Also called concatenation.
- The above example is faster if written this way:
echo 'This is an example of single quoting. '
. 'But, sometimes it\'s not possible without escaping. '
. "Also it's not possible with $embedded variables. "
. 'Control characters such as "\n" (linefeed) and "\t" (tab) don\'t work either. '
. 'However, it\'s preferable to concatenate' . $variables . 'like this, anyway. '
. '"Nested quotes", she said, "are also acceptable where needed.
Just try to use single quotes as the outer set."'
Submitting Changes
Please use github's pull request feature to contribute
changes to WebCalendar.
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. When translating text within javascript, always set the decode
flag to true. This will allow proper decoding of htmlentities.
- 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 characters 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
- Updating Language Files
- When text is added or updated, requiring new translations, the
translations/English-US.txt file
should be updated as a minimum. This file will be used as the basis for updating
the other language files and needs to be up to date. From within the tools directory,
the following command will search through the WebCalendar source files and
update the language file specified.
Language files should always be committed to CVS in Unix format to save space.
perl update_translation.pl English-US.txt
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 dbi4php.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 just 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: