1 <?xml version="1.0" encoding="utf-8"?>
3 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4 "DTD/xhtml1-transitional.dtd">
5 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
7 <title>WebCalendar Developer Guide</title>
8 <style type="text/css">
10 background-color: #FFFFFF;
11 font-family: Arial, Helvetica, sans-serif;
14 text-decoration: none;
25 font-family: courier, monospace;
27 border: 1px solid #0000FF;
28 background-color: #EEEEFF;
34 background-color: #606080;
41 background-color: #000000;
44 background-color: #000000;
55 background-color: #FFFF00;
56 border: 1px solid #000000;
64 background-color: blue;
66 border: 1px solid #000000;
73 background-color: #191970;
83 <h1>WebCalendar Developer Guide</h1>
85 <h2>Table of Contents</h2>
87 <li><a href="#intro">Introduction</a></li>
88 <li><a href="#requirements">System Requirements</a></li>
89 <li><a href="#getcode">Getting The Code</a></li>
90 <li><a href="#conventions">Conventions</a></li>
91 <li><a href="#standards">Coding Standards</a></li>
92 <li><a href="#patch">Creating a Patch</a></li>
93 <li><a href="#translations">Translations and Languages</a></li>
94 <li><a href="#faq">FAQ</a></li>
95 <li><a href="#resources">Resources</a></li>
100 <h2>Introduction</h2>
102 <p>WebCalendar is written in PHP. Although originally written
103 for PHP3, only PHP4 is officially supported. (It should also
104 work on PHP5, but testing has not been completed yet.)
107 <div class="top"><a href="#" target="_top">↑ top</a></div>
112 <p>The following tools will be helpful in WebCalendar development:
116 <li><a href="http://www.perl.org">perl</a>:
117 Perl is used to check translation files to see what translations
119 If you are using Windows, perl is included as part of the
120 <a href="http://www.cygwin.com">cygwin</a> package.
122 <li>make: The "make" command is used when generating WebCalendar
123 documentation in the <tt>docs</tt> directory.
124 The "make" command is standard on Linux if you install
125 certain development packages.
126 If you are using Windows, make is included as part of the
127 <a href="http://www.cygwin.com">cygwin</a> package.
129 <li><a href="http://www.gnu.org/software/patch/patch.html">patch</a>:
130 The "patch" command is used to apply patches posted
131 on the SourceForge patches area.
133 <li>diff: The "diff" command is used to create patches posted
134 on the SourceForge patches area.
136 <li><a href="https://www.cvshome.org/">CVS</a>:
137 Configuration management is managed using CVS.
139 <li>Access to Internet Explorer, Mozilla/Firefox,
140 and Apple Safari. We try to test on all three of these
141 platforms whenever we make any HTML or JavaScript changes.
142 If you do not have access to all these, please test your changes
143 on as many of these browsers as you have access to.
148 <p><span class="tip">TIP</span> If you are developing on a
149 Windows system, the <a href="http://www.cygwin.com">Cygwin package</a>
150 will provide command line tools that
151 include perl, make, patch, diff and cvs.
154 <div class="top"><a href="#" target="_top">↑ top</a></div>
157 <a name="getcode"></a>
158 <h2>Getting The Code</h2>
160 <p>You should always be using the latest code in CVS.
161 You can obtain the latest code using anonymous CVS.
163 need to be an authorized WebCalendar developer).
164 Use the following commands to checkout the latest code from
168 cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/webcalendar login
169 cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/webcalendar co webcalendar
171 <p>This will create a <tt>webcalendar</tt> directory.
172 You should run these commands from one of the directories that
173 your web server is configured to use.
174 For example, on some Linux systems, the Apache document root is
175 configured to be <tt>/var/www/html</tt>. So,
176 you would change directories to that directories before
177 checking the code out of CVS.
180 <p>You only need to perform this checkout once.
181 After the initial checkout, you can update your code with the following
182 command (run this command from inside the toplevel WebCalendar directory):
186 <p>If you have modified any of the WebCalendar files,
187 CVS will attempt to merge your changes with any changes to the
188 same file in the new code from CVS.
191 For example, if you modified the <tt>includes/functions.php</tt> file
192 on your system and a WebCalendar developer also modified this file
193 in CVS, then when you perform the CVS update, the changes will be
194 merged. If the merge fails, you will see a file with a <tt>.rej</tt>
195 extension and another with <tt>.orig</tt>.
198 <div class="top"><a href="#" target="_top">↑ top</a></div>
199 <a name="conventions"></a>
202 The following conventions have been adopted by WebCalendar (although
203 they have not been 100% enforced, so you will see exceptions):
206 <li>Function names: Use lowercase with an underscore '_' when naming
207 functions.<br/>Example: dbi_query
209 <li>Database table names: All db tables are prefixed with "webcal_" and
210 are lowercase using underscores.
211 <br/>Example: webcal_user_pref
213 <li>PHP function comments: <a href="phpdoc/" title="WebCalendar Function Documenation">Function documentation</a> is generated using
214 <a href="http://www.phpdoc.org/" title="phpDocumentor">phpDocumentor</a>.
215 Each function should be preceded by a DocBlock. See the phpDocumentor website for
216 <a href="http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock"
217 title="DocBlocks">information about DocBlocks and DocBlock syntax</a>, and see
218 <a href="http://cvs.sourceforge.net/viewcvs.py/webcalendar/webcalendar/includes/functions.php?view=markup"><tt>includes/functions.php</tt></a>
221 <li>ChangeLog: if you have access to commit your changes to CVS, please
222 put an entry at the top of the ChangeLog file that describes the
223 change. If the change fixes a specific SourceForge bug, then
224 include the bug id in the description.
228 <div class="top"><a href="#" target="_top">↑ top</a></div>
229 <a name="standards"></a>
230 <h2>Coding Standards</h2>
232 The following coding standards have been adopted by WebCalendar (although
233 they have not been 100% implemented).
236 <li>Indenting: Two spaces (ASCII 0x20) for each level. Wrapped lines should also be
237 indented 2 spaces if these spaces will not affect output.
239 <li>Tabs (ASCII 0x09): This character will not be used. Replace all
240 occurrences with ASCII 0x20. This may affect indenting, so please
241 double check before committing to CVS or posting.
243 <li>File Format: Unix format only (LF ASCII 0x0A), no Windows or Mac format files.
245 <li>PHP file comments: Each file should have a file header.
247 See <a href="http://cvs.sourceforge.net/viewcvs.py/webcalendar/webcalendar/report.php?view=markup"><tt>report.php</tt></a> as an example.
249 <li>Use double quotes around html attributes
251 <li>If/Else: Always us {} when not using inline format. Either of the following
252 is acceptable based on logic complexity.
260 bar = ( foo == 1 )? true : false ;
263 <li>Function Calls/Declarations: Use spaces inside and around parenthesis ()
265 Declaration: function getGetValue ( $name ) {
266 Call: bar = getGetValue ( $name );
271 <div class="top"><a href="#" target="_top">↑ top</a></div>
273 <h2>Creating a Patch File</h2>
278 <div class="top"><a href="#" target="_top">↑ top</a></div>
279 <a name="translations"></a>
280 <h2>Translations and Languages</h2>
283 When adding or modifying WebCalendar code, all displayed text should be translatable.
284 The following tips will ensure new text can be translated quickly and efficiently.</p>
286 <li>Translate: All displayable text should be sent to the <em>translate
287 ()</em> function, which returns the text translated in the user's language of choice.
288 A variation of this function is <em>etranslate ()</em>, which includes and echo command.
290 <li>Htmlentities: When used, this function tag should include the current charset when displaying database
291 results. This will be most important when dealing with languages such as Japanese that
292 tend to contain charactes that would otherwise be non-displayable. Although this is not the perfect
293 solution, it seems to suffice for our purposes. Possibly, a better technique would be to
294 use the charset of the original creator of the data, but this is beyond current capabilities. <br />
296 <pre><a href="http://us3.php.net/manual/en/function.htmlentities.php">
297 http://us3.php.net/manual/en/function.htmlentities.php</a>
300 <li>TODO: Add procedures for updating Language.txt files
304 <div class="top"><a href="#" target="_top">↑ top</a></div>
306 <h2>Frequently Asked Questions</h2>
308 <!-- START FAQ: Developing -->
309 <dt>Why aren't you using PHP sessions?</dt>
310 <dd>We are still considering using PHP4 sessions.
311 In fact, the <tt>install/index.php</tt> page <i>does</i>
313 The cookie-based solution that WebCalendar uses is simple,
314 and it will work with all versions of PHP.
316 <dt>Why aren't you using ADODB for database access?</dt>
317 <dd>Again, this would be overkill for what we need. ADODB is a fairly
319 so I'm partial to my leaner php-dbi.php solution.</dd>
320 <dt>Why aren't you using the PEAR database functions?</dt>
321 <dd>WebCalendar pre-dates the PEAR database functions.
322 There does not seem to be sufficient reason to switch
323 from our existing code at this point.</dd>
324 <dt>Why aren't you using a template engine like smarty?</dt>
325 <dd>WebCalendar pre-dates most of the template engines out there.
326 We are currently evaluating some of the templating options
327 and may consider moving to one of the template systems in
329 <dt>How do I install a patch?</dt>
330 <dd>Different patches are applied differently.
331 Some patches just contain an updated file.
332 In that case, you should be able to use replace the old file
333 with the new (assuming the new file and your install are based
334 on the same version of WebCalendar). <br/><br/>
335 Others are patch files, which usually have a <tt>.diff</tt>
336 or <tt>.patch</tt> file extension.
337 In order to use one of these files, you need the
338 <a href="http://www.gnu.org/software/patch/patch.html">GNU patch</a>
340 (This should be installed on all Linux systems and you can get a
341 version for Windows. I use the patch program that comes with
342 <a href="http://www.cygwin.com">cygwin</a> on windows.)
343 I would recommend testing the patch on your install first using the
344 <tt>--dry-run</tt> option.
346 For example, if the patch file is called <tt>calmods.diff</tt>,
348 <pre>patch --dry-run < calmods.diff</pre>
349 If the program says it cannot determine which file to patch,
351 <pre>patch --dry-run -p1 < calmods.diff </pre>
353 If it goes through all the changes successfully, do the same
354 command without the <tt>--dry-run</tt> option to install the patch.
355 If it says "hunk failed", then the patch cannot be applied without
356 hand-merging files. This essentially means that the patch was
357 based on a version of WebCalendar that is too different than
358 the version that you have installed, so it was unable to determine
359 how to apply some of the changes in the patch file.
365 <div class="top"><a href="#" target="_top">↑ top</a></div>
366 <a name="resources"></a>
369 The following resources may be helpful:
373 <li>The <a href="http://cvs.sourceforge.net/viewcvs.py/webcalendar/webcalendar/TODO?view=markup">TODO</a> file in CVS contains
374 ideas for future enhancements.
376 <li>The <a href="http://sourceforge.net/forum/forum.php?forum_id=11587">Open
377 Discussion</a> forum on SourceForge is a good place to ask
378 questions about WebCalendar development.
380 <li><a href="http://sourceforge.net/bugs/?group_id=3870">Bug Reports</a>
383 <li><a href="phpdoc/">WebCalendar Function Documentation</a>
385 <li><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/webcalendar/webcalendar/docs/WebCalendar-Database.html?rev=HEAD&content-type=text/html">WebCalendar-Database.html</a> describes the WebCalendar database schema
387 <li><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/webcalendar/webcalendar/docs/WebCalendar-Styling.html?rev=HEAD&content-type=text/html">WebCalendar-Styling.html</a> describes how WebCalendar uses CSS
391 <div class="top"><a href="#" target="_top">↑ top</a></div>
394 <b>Last Update:</b> 2005/03/08 02:52:33 cknudsen
396 <a href="http://validator.w3.org/check?uri=referer"><img
397 src="http://www.w3.org/Icons/valid-xhtml10"
398 alt="Valid XHTML 1.0!" class="valid" /></a>