[Sommaire] [Imprimer]

   1  <?xml version="1.0" encoding="utf-8"?>
   2  <!DOCTYPE html
   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">
   6  <head>
   7  <title>WebCalendar Developer Guide</title>
   8  <style type="text/css">
   9  body {
  10    background-color: #FFFFFF;
  11    font-family: Arial, Helvetica, sans-serif;
  12  }
  13  a {
  14    text-decoration: none;
  15  }
  16  dt {
  17    font-weight: bold;
  18    margin-left: 25px;
  19    margin-top: 20px;
  20  }
  21  .valid {
  22    border-width: 0px;
  23  }
  24  pre {
  25    font-family: courier, monospace;
  26    font-size: 14px;
  27    border: 1px solid #0000FF;
  28    background-color: #EEEEFF;
  29    padding: 4px;
  30    margin-left: 25px;
  31    margin-right: 25px;
  32  }
  33  tr {
  34    background-color: #606080;
  35    color: #F0F0F0;
  36  }
  37  td {
  38    vertical-align: top;
  39  }
  40  th {
  41    background-color: #000000;
  42  }
  43  .colorheader {
  44    background-color: #000000;
  45    color: #FFFFFF;
  46    margin-left: 3px;
  47    margin-right: 3px;
  48    padding: 2px;
  49  }
  50  .newwin {
  51    border-width: 0px;
  52  }
  53  .tip {
  54    font-weight: bold;
  55    background-color: #FFFF00;
  56    border: 1px solid #000000;
  57    padding: 1px;
  58    padding-left: 5px;
  59    padding-right: 5px;
  60    margin-right: 10px;
  61  }
  62  .note {
  63    font-weight: bold;
  64    background-color: blue;
  65    color: #FFFFFF;
  66    border: 1px solid #000000;
  67    padding: 2px;
  68  }
  69  hr {
  70    margin-bottom: 7px;
  71  }
  72  h2 {
  73    background-color: #191970;
  74    color: #FFFFFF;
  75    padding: 5px;
  76  }
  77  .top {
  78    text-align: right;
  79  }
  80  </style>
  81  </head>
  82  <body>
  83  <h1>WebCalendar Developer Guide</h1>
  84  
  85  <h2>Table of Contents</h2>
  86  <ul>
  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>
  96  </ul>
  97  <hr />
  98  
  99  <a name="intro"></a>
 100  <h2>Introduction</h2>
 101  
 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.)
 105  </p>
 106  
 107  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 108  <hr />
 109  
 110  <a name="Tools"></a>
 111  <h2>Tools</h2>
 112  <p>The following tools will be helpful in WebCalendar development:
 113  </p>
 114  
 115  <ul>
 116    <li><a href="http://www.perl.org">perl</a>:
 117        Perl is used to check translation files to see what translations
 118        are missing.
 119        If you are using Windows, perl is included as part of the
 120        <a href="http://www.cygwin.com">cygwin</a> package.
 121        </li>
 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.
 128        </li>
 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.
 132        </li>
 133    <li>diff: The "diff" command is used to create patches posted
 134        on the SourceForge patches area.
 135        </li>
 136    <li><a href="https://www.cvshome.org/">CVS</a>:
 137        Configuration management is managed using CVS.
 138        </li>
 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.
 144        </li>
 145  
 146  </ul>
 147  
 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.
 152  </p>
 153  
 154  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 155  <hr />
 156  
 157  <a name="getcode"></a>
 158  <h2>Getting The Code</h2>
 159  
 160  <p>You should always be using the latest code in CVS.
 161  You can obtain the latest code using anonymous CVS.
 162  (You do not
 163  need to be an authorized WebCalendar developer).
 164  Use the following commands to checkout the latest code from
 165  CVS:
 166  </p>
 167  <pre>
 168  cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/webcalendar login 
 169  cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/webcalendar co webcalendar
 170  </pre>
 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.
 178  </p>
 179  
 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):
 183  </p>
 184  <pre>cvs update -d
 185  </pre>
 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.
 189  </p>
 190  <p>
 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>.
 196  </p>
 197  
 198  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 199  <a name="conventions"></a>
 200  <h2>Conventions</h2>
 201  <p>
 202  The following conventions have been adopted by WebCalendar (although
 203  they have not been 100% enforced, so you will see exceptions):
 204  </p>
 205  <ul>
 206  <li>Function names: Use lowercase with an underscore '_' when naming
 207    functions.<br/>Example: dbi_query
 208    </li>
 209  <li>Database table names: All db tables are prefixed with "webcal_" and
 210      are lowercase using underscores.
 211      <br/>Example: webcal_user_pref
 212      </li>
 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>
 219      for examples.
 220      </li>
 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.
 225     </li>
 226  </ul>
 227  
 228  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 229  <a name="standards"></a>
 230  <h2>Coding Standards</h2>
 231  <p>
 232  The following coding standards have been adopted by WebCalendar (although
 233  they have not been 100% implemented).
 234  </p>
 235  <ul>
 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.  
 238      </li>
 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.  
 242      </li>
 243  <li>File Format: Unix format only (LF ASCII 0x0A), no Windows or Mac format files.
 244      </li>
 245  <li>PHP file comments: Each file should have a file header.
 246      <br/>
 247      See <a href="http://cvs.sourceforge.net/viewcvs.py/webcalendar/webcalendar/report.php?view=markup"><tt>report.php</tt></a> as an example.
 248      </li>
 249  <li>Use double quotes around html attributes
 250      </li>
 251  <li>If/Else: Always us {} when not using inline format. Either of the following
 252      is acceptable based on logic complexity.
 253    <pre>                
 254  if ( foo == 1 ) {
 255    bar = true;
 256  } else {
 257    bar = false;
 258  }
 259  or  
 260  bar = ( foo == 1 )? true : false ;
 261              </pre>
 262      </li>
 263  <li>Function Calls/Declarations: Use spaces inside and around  parenthesis ()
 264    <pre>
 265  Declaration: function getGetValue ( $name ) {
 266  Call: bar = getGetValue ( $name );
 267  </pre>
 268      </li>
 269  </ul>
 270  
 271  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 272  <a name="patch"></a>
 273  <h2>Creating a Patch File</h2>
 274  
 275  <p>TODO</p>
 276  
 277  
 278  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 279  <a name="translations"></a>
 280  <h2>Translations and Languages</h2>
 281  
 282  <p>
 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>
 285  <ul>
 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.
 289      </li>
 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 />
 295                  For reference see:
 296      <pre><a href="http://us3.php.net/manual/en/function.htmlentities.php">
 297  http://us3.php.net/manual/en/function.htmlentities.php</a>
 298      </pre>
 299                  </li>    
 300  <li>TODO: Add procedures for updating Language.txt files
 301      </li>    
 302  </ul>
 303  
 304  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 305  <a name="faq"></a>
 306  <h2>Frequently Asked Questions</h2>
 307  <dl>
 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>
 312        use PHP sessions.
 313        The cookie-based solution that WebCalendar uses is simple,
 314        and it will work with all versions of PHP.
 315        </dd>
 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
 318        large project,
 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
 328        the future.</dd>
 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>
 339        program.
 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. 
 345        <br/><br/>
 346        For example, if the patch file is called <tt>calmods.diff</tt>,
 347        then you would use:
 348        <pre>patch --dry-run < calmods.diff</pre>
 349        If the program says it cannot determine which file to patch,
 350        try adding -p1: 
 351        <pre>patch --dry-run -p1 < calmods.diff </pre>
 352        <br/><br/>
 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. 
 360        </dd>
 361   
 362  <!-- END FAQ -->
 363  </dl>
 364  
 365  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 366  <a name="resources"></a>
 367  <h2>Resources</h2>
 368  <p>
 369  The following resources may be helpful:
 370  </p>
 371  
 372  <ul>
 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.
 375     </li>
 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.
 379    </li>
 380  <li><a href="http://sourceforge.net/bugs/?group_id=3870">Bug Reports</a>
 381    on SourceForge.
 382    </li>
 383  <li><a href="phpdoc/">WebCalendar Function Documentation
 384    </li>
 385  <li><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/webcalendar/webcalendar/docs/WebCalendar-Database.html?rev=HEAD&amp;content-type=text/html">WebCalendar-Database.html</a> describes the WebCalendar database schema
 386    </li>
 387  <li><a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/webcalendar/webcalendar/docs/WebCalendar-Styling.html?rev=HEAD&amp;content-type=text/html">WebCalendar-Styling.html</a> describes how WebCalendar uses CSS
 388    </li>
 389  </ul>
 390  
 391  <div class="top"><a href="#" target="_top">↑&nbsp;top</a></div>
 392  <hr />
 393  <p>
 394  <b>Last Update:</b> $Id: WebCalendar-DeveloperGuide.html,v 1.6 2005/03/08 02:52:33 cknudsen Exp $
 395  <br/>
 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>
 399  </p>
 400  </body>
 401  </html>