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 System Administrator's Guide</title>
8 <style type="text/css">
10 background-color: #FFFFFF;
11 font-family: Arial, Helvetica, sans-serif;
15 text-decoration: none;
29 font-family: courier, monospace;
31 border: 1px solid #0000FF;
32 background-color: #EEEEFF;
39 background-color: #606080;
48 background-color: #000000;
52 background-color: #000000;
65 background-color: #FFFF00;
66 border: 1px solid #000000;
75 background-color: blue;
77 border: 1px solid #000000;
86 background-color: #191970;
97 <h1>WebCalendar System Administrator's Guide</h1>
98 <p><strong>WebCalendar Version:</strong> 1.0.0</p>
100 <h2>Table of Contents</h2>
102 <li><a href="#intro">Introduction</a></li>
103 <li><a href="#requirements">System Requirements</a></li>
104 <li><a href="#fileunpacking">File Unpacking</a></li>
105 <li><a href="#dbsetup">Database Setup</a></li>
106 <li><a href="#appsetup">Application Setup</a></li>
107 <li><a href="#reminders">Setting Up Email Reminders</a></li>
108 <li><a href="#systemsettings">System Settings</a></li>
109 <li><a href="#siteextras">Custom Event Fields</a></li>
110 <li><a href="#faq">FAQ</a></li>
111 <li><a href="#trouble">Troubleshooting</a></li>
112 <li><a href="#help">Getting Help</a></li>
113 <li><a href="#license">Licensing</a></li>
114 <li><a href="#glossary">Glossary</a></li>
115 <li><a href="#appendixA">Appendix A: Database Setup with
117 <li><a href="#appendixB">Appendix B: Setting Up Reminders on
119 <li><a href="#appendixC">Appendix C: Displaying Upcoming
120 Events on Your Site</a></li>
121 <li><a href="#appendixD">Appendix D: How To Configure For LDAP</a></li>
126 <h2>Introduction</h2>
128 <p>WebCalender is an open source PHP-based multi-user calendar.</p>
130 <p><strong>Features:</strong></p>
132 <li>Multi-user support</li>
133 <li>Group support</li>
134 <li>View day-at-glance</li>
135 <li>View month-at-glance</li>
136 <li>View week-at-glance</li>
137 <li>View year-at-glance</li>
138 <li>View another user's calendar</li>
139 <li>View multiple users' calendars at the same time</li>
140 <li>View one or more users' calendar via layers on top of your own
142 <li>Public calendar (that requires no login) where anonymous users
143 submit events that are approved by an administrator</li>
144 <li>Add/Edit/Delete users</li>
145 <li>Add/Edit/Delete events</li>
146 <li>Repeating events</li>
147 <li>Custom event fields</li>
148 <li>Search interface for calendar entries</li>
149 <li>User-configurable preferences for colors, 12/24 time format,
150 Week start on Sun or Mon, default work hours</li>
152 <li>Checks for scheduling conflicts</li>
153 <li>Support for multiple timezones</li>
154 <li>Users can accept or reject events added by another user to
156 <li>Email reminders</li>
157 <li>Email notifications for new events</li>
158 <li>Support for 30 different languages:
164 <li>简体中文(GB2312)</li>
167 <li>Deutsch (German)</li>
169 <li>Español (Spanish)</li>
171 <li>Français (French)</li>
173 <li>Hollands (Dutch)</li>
174 <li>Holo (Taiwanese)</li>
177 <li>Italiano (Italian)</li>
180 <li>Norsk (Norwegian)</li>
183 <li>Portuguese/Brazil</li>
185 <li>Русско (Russian)</li>
186 <li>Suomalainen (Finnish)</li>
187 <li>Svensk (Swedish)</li>
192 <li>Exporting to and importing from:
199 <li>Authentication using:
202 <li>HTTP authentication</li>
207 <li>Activity log that tracks:
209 <li>event creation</li>
210 <li>event updates</li>
211 <li>event acceptance</li>
212 <li>event rejection</li>
213 <li>email notifications</li>
214 <li>email reminders</li>
218 <div class="top"><a href="#" target="_top">↑ top</a></div>
221 <a name="requirements"></a>
222 <h2>System Requirements</h2>
224 <li>PHP 4 (PHP 5 not yet tested) with <tt>magic_quotes_gpc</tt>
226 <li>Database (see <a href="#database">below</a>)</li>
227 <li>CSS-enabled browser</li>
228 <li>JavaScript-enabled browser</li>
229 <li>If not using HTTP-based authentication, then browser cookies
232 <p><strong>Recommended:</strong></p>
234 <li>pilot-link (if exporting to Palm): <a
235 href="http://sourceforge.net/project/?group_id=2158">http://sourceforge.net/project/?group_id=2158</a> <a
236 href="http://sourceforge.net/project/?group_id=2158"
237 title="Open in new window" target="_new"><img src="newwin.gif"
238 alt="new" class="newwin" /></a></li>
240 <p><a name="database">You must have one of the following
241 databases installed</a>:</p>
247 <li>MS SQL Server</li>
248 <li>ODBC (PHP ODBC includes support for Adabas D, IBM DB2, Solid
249 and Sybase SQL Anywhere as well as ODBC)</li>
251 <p>For the database you choose, you must have its drivers built into
252 PHP. For example, to use MySQL, PHP must be compiled with MySQL support
253 (which is the default setting when installing PHP). See the PHP pages (<a
254 href="http://www.php.net">www.php.net</a> <a
255 href="http://www.php.net" title="Open in new window" target="_new"><img
256 src="newwin.gif" alt="new" class="newwin" /></a>) for more information on
258 <p>No optional PHP packages (other than MySQL) are required for this
259 application. However, PHP shoud be compiled with <tt>--enable-track-vars</tt>
261 <p>Make sure that <tt>magic_quotes_gpc</tt> in <tt>php.ini</tt> is
262 turned on (otherwise, you will get an error message when you try to
263 access WebCalendar.)</p>
264 <p><span class="tip">TIP</span> If you are using Apache as your web
265 server and if you cannot or do not want to enable <tt>magic_quotes_gpc</tt>
266 for your entire site, you can enable it just for WebCalendar. Create a <tt>.htaccess</tt>
267 file in the toplevel WebCalendar directory that contains a single line:</p>
268 <pre>php_value magic_quotes_gpc 1</pre>
269 <p>(For this to work with Apache, you must have the Apache <tt>AllowOverride
270 All</tt> directive enabled for the directory where WebCalendar is installed.
271 Additionally, PHP must be running as an Apache module, not a CGI.)</p>
273 <p>You can run PHP either as a CGI or an Apache module. You'll get
274 better performance with PHP setup as a module. Not only will you not
275 have to deal with the CGI performance hit, but you'll be able to use
276 PHP's database connection pooling. Additionally, this application can
277 use a form/cookie-based authentication or traditional HTTP
278 authentication. For traditional HTTP authentication, PHP must be built
279 as an Apache module.</p>
280 <p>If you are planning on using email reminders, you will need to
281 build PHP as a CGI in order to run the <tt>send_reminders.php</tt>
282 script. I would strongly recommend building a module-based PHP for your
283 web server and then a second PHP build to create the CGI version.</p>
284 <p><span class="tip">TIP</span> Some Linux distributions come with
285 both a module-based PHP with Apache and a standalone PHP binary. Check
286 for <tt>/usr/bin/php</tt> to see if you already have the PHP standalone
287 executable. If it's there, you can use the following command to see what
288 version of PHP you have:</p>
289 <pre>/usr/bin/php -v</pre>
290 <div class="top"><a href="#" target="_top">↑ top</a></div>
293 <a name="fileunpacking"></a>
294 <h2>File Unpacking</h2>
295 <p>Unpack the calendar software in its own directory somewhere where
296 your web server will find it. (See your web server docs for info.)</p>
297 <p>By default, WebCalendar should create its own directory when you
298 unpack it. The new directory name will typically contain the version
299 name (such as <tt>WebCalendar-0.9.41</tt>). You can rename this
300 directory after unpacking the files if you prefer a directory name like
301 <tt>calendar</tt> or <tt>webcalendar</tt>. Keep in mind that unless you
302 remap the directory (via your web server's configuration settings), it
303 will be part of the URL for the calendar.</p>
304 <div class="top"><a href="#" target="_top">↑ top</a></div>
307 <a name="dbsetup"></a>
308 <h2>Database Setup</h2>
309 <p>There are three steps in setting up the database:</p>
311 <li>Creating the database</li>
312 <li>Creating the user</li>
313 <li>Creating the required tables</li>
315 <p>Follow the steps outlined below for the database you are using.
316 When complete, a single user account will be created with the <strong>login
317 "admin" and password "admin"</strong>, which you are encouraged to use to create
318 your own account.</p>
319 <p><span class="note">Note:</span> In the examples below, text in <strong>bold</strong>
320 represents text that you must type in.</p>
321 <p><span class="note">Security:</span> The default values for
322 database, login, and password (<strong>intranet</strong>, <strong>webcalendar</strong>,
323 and <strong>webcal01</strong>) are for demonstration purposes only and
324 should never be used in a production environment.</p>
325 <h3 class="colorheader">MySQL</h3>
326 <p>The following will create a database named "intranet".</p>
327 <pre><strong>mysqladmin create intranet</strong></pre>
328 <p>Next, create the database user account that will be used to
329 access the database.</p>
330 <pre><strong>mysql --user=root mysql</strong>
331 mysql> <strong>GRANT ALL PRIVILEGES ON *.* TO webcalendar@localhost
332 IDENTIFIED BY 'webcal01' WITH GRANT OPTION;</strong>
333 mysql> <strong>FLUSH PRIVILEGES;</strong>
334 mysql> <strong>QUIT</strong></pre>
335 <p>If you will be accessing MySQL from a different machine than the
336 one running the web server, repeat the command above and replace
337 'localhost' with the hostname of the other machine.</p>
338 <p>Create the calendar tables using the supplied <tt>tables-mysql.sql</tt>
340 <pre><strong>mysql intranet < tables-mysql.sql</strong></pre>
341 <p>In the above example, "intranet" is the name of your database.</p>
343 <p><span class="note">Note:</span> If you are using <a
344 href="http://www.phpmyadmin.net">phpMyAdmin</a> to manage your MySQL
345 database, follow the instructions in <a href="#appendixA">Appendix A</a>.
348 <h3 class="colorheader">Oracle</h3>
349 <p>The following will create a tablespace named "webcalendar". From
350 the command line, startup sqlplus and issue the following command:</p>
351 <pre><strong>sqlplus</strong>
352 SQL> <strong>CREATE TABLESPACE webcalendar
353 DATAFILE 'webcalendar.dat' SIZE 10M
354 AUTOEXTEND ON NEXT 10M MAXSIZE 40M;</strong></pre>
355 <p>Next, create the database user account that will be used to
356 access the database.</p>
357 <pre><strong>sqlplus</strong>
358 SQL> <strong>CREATE USER webcalendar IDENTIFIED BY webcal01
359 DEFAULT TABLESPACE webcalendar;</strong>
360 SQL> <strong>GRANT dba TO webcalendar;</strong>
361 SQL> <strong>quit</strong></pre>
362 <p>Create the calendar tables using the supplied <tt>tables-oracle.sql</tt>
364 <pre><strong>sqlplus webcalendar/webcal01</strong>
365 SQL> <strong>@tables-oracle;</strong>
366 SQL> <strong>quit</strong></pre>
368 <h3 class="colorheader">PostgreSQL</h3>
369 <p>The following will create a database named "webcalendar". From
370 the command line, startup psql and issue the following command:</p>
371 <pre><strong>create database webcalendar;
373 \i tables-postgres.sql
376 <h3 class="colorheader">Interbase</h3>
377 <p>The following will create a database named "WEBCAL.gdb". From the
378 command line, startup usql and issue the following command:</p>
379 <pre><strong>CREATE DATABASE 'WEBCAL.gdb';</strong></pre>
381 <p>Create the calendar tables using the supplied <tt>tables-ibase.sql</tt>
384 connect /path/WEBCAL.gdb;
385 input path/table-ibase.sql;</strong></pre>
387 <h3 class="colorheader">ODBC</h3>
388 <p>Setup will depend on which database you are using. When it comes
389 time to create the tables, the <tt>tables-postgres.sql</tt> file should
390 work for most databases.</p>
391 <h3 class="colorheader">MSSQL</h3>
392 <p>Create a database, <strong>intranet,</strong> and add a user, <strong>webcalendar</strong>,
393 to access this database. The user should be granted public,
394 db_datareader, and db_datawriter privileges. Open SQL Query Analyzer
395 then open the file <tt>tables-postgres.sql</tt>. Make sure you have
396 identified <strong>intranet</strong> as the target database and Execute
397 the contents of the sql file.</p>
398 <div class="top"><a href="#" target="_top">↑ top</a></div>
401 <a name="appsetup"></a>
402 <h2>Application Setup</h2>
403 <p>Next, you will need to run the web-based database setup script
404 (simply direct your browser to your new WebCalendar location). You will
405 need to modify the permissions of the <tt>includes</tt> directory. On
406 Linux/UNIX, you should change this directory to be read/write for all
407 users (<tt>chmod 777 includes</tt>). On Windows, change this directory
408 to have full access for all users using Windows Explorer. Changing the
409 write permissions will allow the web-based database configuration tool
410 to create the <tt>settings.php</tt> file.</p>
412 <p><span class="tip">TIP</span> After you have created the <tt>settings.php</tt>
413 file (with the "Save Settings" button), you can change the permissions
414 back to a more restrictive setting.</p>
416 <p>After you test and save your database settings, you will be
417 prompted to enter an installation password. <b>Write this password
418 down somewhere.</b> There is no way to reset this password. If you forget
419 this password and need to change your database settings, you will need
420 to manually edit the <tt>settings.php</tt> file with a text editor.</p>
422 <p>If you choose not to use the web-based database configuration
423 tool, you can manually edit the <tt>settings.php</tt> file. There is an
424 example file <tt>settings.php.orig</tt> that you can use as a starting
425 point. Simply rename this file to <tt>settings.php</tt>. You will need
426 to set the values as follows in <tt>settings.php</tt>:</p>
427 <p>To configure your database access. Set the values for:</p>
428 <table class="distinguish">
431 <td>One of "mysql", "oracle", "postgresql", "odbc",
432 "mssql", or "ibase"</td>
436 <td>The hostname that database is running on. (Use localhost if
437 it's the same machine as the web server.) (This variable is not used
442 <td>The database login</td>
446 <td>The database password for the above login</td>
450 <td>The name of the database that the calendar tables reside in.
451 ("intranet" in the <a href="#dbsetup">examples above</a>.) For ODBC,
452 this should be the DSN.</td>
455 <td>db_persistent</td>
456 <td>Enable use of persistent (pooled) database connections. This
457 should typically be enabled.</td>
461 <p>You can configure the calendar to run in single-user<a
462 href="#g_singleuser">*</a> mode or multi-user<a href="#g_multiuser">*</a>
463 mode. If this is your first time using the calendar, it's easier to try
464 single-user. You can always switch to multi-user later. Leave <tt>single_user</tt>
465 set to "N" (the default) for multi-user or set it to "Y" and set the
466 value of <tt>single_user_login</tt> to a login name of your liking to
467 set the system to single-user mode. (And be sure to set the value of <tt>single_user_login</tt>
468 to the login that you would choose if you decide to switch to multi-user
470 <p><span class="note">Note:</span> If you do decide to switch from
471 single-user mode to multi-user mode, make sure you add in a user to the
472 system for the login you set the <tt>single_user_login</tt> variable to.
473 You will need to do this via the database (mysql, sqlplus, etc.) Look in
474 the <tt>tables-mysql.sql</tt> (or <tt>tables-oracle.sql</tt>, etc.) to
475 see the example of adding in the "admin" user.</p>
476 <p>If you are setting up a multi-user calendar, you will need to
477 choose how your users are authenticated. You must change the settings of
478 <tt>use_http_auth</tt> and <tt>user_inc</tt> to setup which
479 authentication method to use.</p>
480 <p>You currently have four choices:</p>
482 <li>Web-based authentication (login/passwords verified in the
483 WebCalendar database):<br />
484 <tt>use_http_auth = false</tt><br />
485 <tt>user_inc = user.php</tt></li>
486 <li>HTTP-based authentication (login/passwords verified by the web
488 <tt>use_http_auth = true</tt><br />
489 <tt>user_inc = user.php</tt><br />
490 ... and don't forget to setup your web server to handle user
491 authentication.<br />
492 <span class="note">Note:</span> In order to use HTTP-based
493 authentication, PHP must be setup as a module for your server rather
495 <li>NIS-based authentication (login/passwords verified by NIS):<br />
496 <tt>use_http_auth = false</tt><br />
497 <tt>user_inc = user-nis.php</tt><br />
498 Additional configuration settings will need to be set in <tt>includes/user-nis.php</tt>.
500 <li>LDAP-based authentication (login/passwords verified by LDAP
502 <tt>use_http_auth = false</tt><br />
503 <tt>user_inc = user-ldap.php</tt><br />
504 Additional configuration settings will need to be set in <tt>includes/user-ldap.php</tt>.
507 <p>Keep in mind that if you want to use reminders, you will need to
508 setup the <tt>send_reminders.php</tt> script (see below) and keep your
509 admin setting for "Email enabled" set to "Yes" on the admin settings
511 <p>At this point, your WebCalendar installation should be up and
512 running. To access WebCalendar open up your favorite web browser and
513 type in the URL. The URL will depend on where you installed WebCalendar.</p>
514 <p>When you unpacked/unzipped the WebCalendar distribution, it
515 typically creates a directory that includes the version number. For
516 example, if the zip file was named <tt>WebCalendar-0.9.99.zip</tt> (or <tt>WebCalendar-0.9.99.tar.gz</tt>),
517 then there should be a <tt>WebCalendar-0.9.99</tt> directory. For
518 convenience, you can rename this directory so that the URL does not
519 include the version number. On Windows, you can do this from the Windows
520 Explorer. On Linux/UNIX, you can use the <tt>mv</tt> command to rename
521 the directory. Supposing you renamed the <tt>WebCalendar-0.9.99</tt>
522 directory to just be <tt>calendar</tt>, and you unpacked/unzipped the
523 files into your toplevel web server directory, the URL would be:</p>
524 <pre>http://yourserverhere/calendar/index.php</pre>
525 <p>If you have not previously configured your database settings, you
526 will be automatically redirected to a web page for configuring your
527 database settings. After you have configured the database, use the URL
528 again to access WebCalendar.</p>
529 <p>If you have configured your web server to use <tt>index.php</tt>
530 as the default index page for a directory, you can omit that from the
531 URL. On a single-user system, your browser should be redirected to
532 week.php initially. On a multi-user system, your browser should be
533 redirected to login.php so that you can login.</p>
534 <p><span class="tip">TIP</span> On a multi-user system, the only
535 user account created during installation has the username of "admin" and
536 a password of "admin". You should create a new admin account and delete
537 this one for security reasons.</p>
538 <div class="top"><a href="#" target="_top">↑ top</a></div>
542 <h2>Creating Users</h2>
543 <p>After logging in as an admin user (the initial username is
544 "admin" with password "admin"), you will see a common set of links at
545 the bottom of each page. Follow these steps to create a new user:</p>
547 <li>Login to WebCalendar as an admin user</li>
548 <li>Click on the "Admin" link at the bottom of any WebCalendar
550 <li>Click on the "Users" button</li>
551 <li>Click on the "Add New User" link</li>
552 <li>Fill out the form with details for the new user (email address
554 <li>Click on the "Save" button</li>
556 <p><span class="tip">TIP</span> On a single-user system, you do not
557 need to create any users.</p>
558 <p><span class="tip">TIP</span> For an event calendar, you do not
559 need to create a user for the "public user".</p>
560 <div class="top"><a href="#" target="_top">↑ top</a></div>
563 <a name="reminders"></a>
564 <h2>Setting Up Email Reminders</h2>
565 <p>PHP does not come with a utility for executing time-based jobs.
566 So, in order to check periodically for email reminders, a shell script
567 was written in PHP. You will need two things to get this working:</p>
569 <li>You should have a version of PHP built as a CGI (so that you
570 can run php from the command line). This does not mean you must build
571 all of PHP as a CGI. You can still build PHP as a module for your web
572 server and then build the CGI-based PHP later.<br />
573 <span class="note">Note:</span> Many Linux distributions and some
574 Windows LAMP packages come with the PHP built for CGI.</li>
575 <li>You must setup cron (on Linux/UNIX) or something like cron for
576 Windows to run the <tt>send_reminders.php</tt> script periodically.</li>
578 <p>Building PHP as a CGI is outside the scope of these instructions.
579 But, if you read the PHP instructions, you'll see that the default build
580 settings will build the CGI-based PHP. If you really can't do this
581 (perhaps you don't have permission to install anything new on the
582 system), skip down a couple of paragraphs to an alternate solution that
583 does not require PHP CGI.</p>
584 <p>For Linux/UNIX users, add the following line to the crontab entry
585 of a user. (This would be the same user that the web server process runs
587 <pre><tt>1 * * * * cd /some/directory/webcalendar/tools; ./send_reminders.php</tt></pre>
588 <p>Of course, replace the directory location to wherever the <tt>send_reminders.php</tt>
589 file can be found. If you moved this out of the tools directory (which
590 is recommended for security reasons), be sure to update <tt>send_reminders.php</tt>
591 since it needs to know where to find other WebCalendar files.</p>
592 <p>If you cannot setup PHP as a CGI or have no idea how, you can
593 leave <tt>send_reminders.php</tt> in its current location and access it
594 via a URL. IMHO, this is not the best choice, but it still works. Setup
595 a cron job to access the URL. For Linux/UNIX users, add the following
596 line to the crontab entry of a user.</p>
597 <pre><tt>1 * * * * wget http://yourserverhere/webcalendardirectoryhere/tools/send_reminders.php > /dev/null</tt></pre>
598 <p>You should test this from the command line first to make sure
599 your setup is correct. If you do not have <tt>wget</tt> installed on
600 your system, you can use any tool (lynx, perl script, etc.) that is
601 capable of making an HTTP request for this.</p>
602 <div class="top"><a href="#" target="_top">↑ top</a></div>
605 <a name="systemsettings"></a>
606 <h2>System Settings</h2>
607 <p>System Settings allows the administrator to control what features
608 are available to users as well as default values for certain features.</p>
609 <p>Many of these settings can be overridden by users in their
610 Preferences (such as color).</p>
613 <dt>Application Name</dt>
614 <dd>Specifies the document title (typically displayed in the
615 window title bar of most browsers)</dd>
617 <dd>Specifies the base URL of the calendar. This information is
618 needed to accurately include URLs in email messages (Notifications and
621 <dd>Specifies the default language setting for all users.</dd>
623 <dd>Specifies your preferred font. Multiple font names should be
624 comma-separated.</dd>
625 <dt>Preferred View</dt>
626 <dd>Specify if users should see the day, week, month, or year
627 after loggin in.</dd>
628 <dt>Display weekends in view</dt>
629 <dd>Specifies default setting for if Saturdays and Sundays should
630 appear in the calendar when viewing a month or week</dd>
632 <dd>Specifies the default format for displaying dates</dd>
634 <dd>Specifies the default time format as either 12-hour (3:45pm)
635 or 24-hour (15:14)</dd>
636 <dt>Time interval</dt>
637 <dd>Specify the default number of minutes each time block
638 represents in the day and week display</dd>
639 <dt>Auto-referesh calendars</dt>
640 <dd>If set to "yes," the day, week, and month pages will
641 automatically reload after a specified duration</dd>
642 <dt>Auto-refresh time</dt>
643 <dd>Specifies how long to wait before the auto-refresh should
644 force a page to be reloaded</dd>
645 <dt>Display unapproved</dt>
646 <dd>Specifies whether events that have been added to a calendar
647 but not yet approved should display on the calendar (in a different
649 <dt>Display week number</dt>
650 <dd>Specifies whether the week number should be displayed in month
652 <dt>Week starts on</dt>
653 <dd>Specifies if week start on Sunday or Monday</dd>
655 <dd>Specifies the default time range to display in day and week
657 <dt>Disable Priority field</dt>
658 <dd>If enabled, the Priority field will not be used</dd>
659 <dt>Disable Access field</dt>
660 <dd>If enabled, the Access field will not be used</dd>
661 <dt>Disable Participants field</dt>
662 <dd>If enabled, the Participants field will not be used, and users
663 will not be able to add events to any calendar other than their own.</dd>
664 <dt>Disable Repeating field</dt>
665 <dd>If enabled, users will not be able to create repeating events</dd>
666 <dt>Allow viewing other user's calendars</dt>
667 <dd>If enabled, users will be able to view the calendar of another
669 <dt>Allow public access</dt>
670 <dd>If enabled, anonymous users will be able to view the public
671 access calendar without logging in.</dd>
672 <dt>Public access can view other users</dt>
673 <dd>If enabled, anonymous users will be able to view the calendars
675 <dt>Public access can add events</dt>
676 <dd>If enabled, anonymous users will be able to submit new events.</dd>
677 <dt>Public access new events require approval</dt>
678 <dd>If enabled, events submitted to the public access calendar (by
679 anonymous users) will require approval by an admin user. If not
680 enabled, then new events will appear on the public access calendar as
681 soon as they are submitted.</dd>
682 <dt>Include add event link in views</dt>
683 <dd>If enabled, Views will include a link to quickly add events to
684 the specified user's calendar.</dd>
685 <dt>Allow external users</dt>
686 <dd>If enabled, the create/edit event page will contain a text
687 area to include the names (and optional email address) of event
688 participants that are not calendar users.</dd>
689 <dt>External users can receive email notifications</dt>
690 <dd>If enabled, event participants entered into the External
691 Participants area will receive email notifications at the same time as
692 calendar users (if an email address was specified for the Exernal
694 <dt>External users can receive email reminders</dt>
695 <dd>If enabled, event participants entered into the External
696 Participants area will receive email reminders at the same time as
697 calendar users (if an email address was specified for the Exernal
699 <dt>Remember last login</dt>
700 <dd>If enabled, when a returning calendar user reaches the login
701 page, their login name will be pre-filled with the last login username
702 that they entered. (The password field will still be blank.)</dd>
703 <dt>Check for event conflicts</dt>
704 <dd>Specifies if the system should check for scheduling conflicts
705 when a user adds or updates an event.</dd>
706 <dt>Conflict checking months</dt>
707 <dd>If conflict checking is enabled, this specifies how many
708 months past the initial date the system will check for conflicts when a
709 user adds or updates a repeating event.</dd>
710 <dt>Allow users to override conflicts</dt>
711 <dd>If enabled, users will be warned when there is an event
712 conflict and be presented with the option of scheduling the event
714 <dt>Limit number of timed events per day</dt>
715 <dd>If enabled, users can can be limited to a specific number of
716 timed events per day</dd>
717 <dt>Maximum timed events per day</dt>
718 <dd>Specifies that maximum number of events that can be scheduled
719 in one day of any one user.</dd>
723 <dt>Groups enabled</dt>
724 <dd>Specifies if group features should be enabled</dd>
725 <dt>User sees only his group</dt>
726 <dd>If enabled, users will be unaware of any users that are not in
727 the same group as the user.</dd>
731 <dt>Cagtegoies enabled</dt>
732 <dd>Specifies if category features should be enabled</dd>
736 <dt>Email enabled</dt>
737 <dd>Specifies if email functionality should be enabled. If set to
738 "No," then no email messages will be sent at any time.</dd>
739 <dt>Default sender address</dt>
740 <dd>Specifies the email originator to use when the system sends
741 out email Notifications and Reminders</dd>
742 <dt>Event reminders</dt>
743 <dd>Specifies if email reminders for events that include a
744 reminder should be sent</dd>
745 <dt>Events added to my calendar</dt>
746 <dd>Specifies if the system should send email when an event is
748 <dt>Events updated on my calendar</dt>
749 <dd>Specifies if the system should send email when an event is
751 <dt>Events removed from my calendar</dt>
752 <dd>Specifies if the system should send email when an event is
754 <dt>Event rejected by participant</dt>
755 <dd>Specifies if the system should send email when a participant
756 to an event rejects the event</dd>
760 <dt>Allow user to customize colors</dt>
761 <dd>Specifies whether color settings should be available to users
762 in their Preferences</dd>
763 <dt>Document background</dt>
764 <dd>Specifies the background color of all pages</dd>
765 <dt>Document title</dt>
766 <dd>Specifies the color of page title on each page</dd>
767 <dt>Document text</dt>
768 <dd>Specifies the default text color on each page</dd>
769 <dt>Table grid color</dt>
770 <dd>Specifies color of the lines that make HTML table grids on
772 <dt>Table header background</dt>
773 <dd>Specifies the default background for the heading of any HTML
775 <dt>Table header text</dt>
776 <dd>Specifies the default text color for the heading of any HTML
778 <dt>Table cell background</dt>
779 <dd>Specifies the background color for table cells</dd>
780 <dt>Table cell background for current day</dt>
781 <dd>Specifies the background color for the table cell containing
782 the current date</dd>
783 <dt>Table cell background for weekend</dt>
784 <dd>Specifies the background color for table cells that represent
785 a Saturday or Sunday</dd>
786 <dt>Event popup background</dt>
787 <dd>Specifies the background color of event popup areas</dd>
788 <dt>Event popup text</dt>
789 <dd>Specifies the text color of event popup areas</dd>
791 <div class="top"><a href="#" target="_top">↑ top</a></div>
794 <a name="siteextras"></a>
795 <h2>Custom Event Fields</h2>
796 <p>You may want to customize the event-specific fields found in the
797 <tt>includes/site_extras.php</tt> field. If this is your first time
798 using the calendar, you can skip this step and come back later since
799 this step is <i>optional</i>.</p>
800 <p>You can use this feature to add extra fields to your calendar
801 events. For example, you can add a URL, a contact email address, or a
803 <p>By default, this file is configured with a single reminder field
804 that allows the user to specify how long before the event the reminder
806 <p><span class="tip">TIP</span> See <a href="#reminders">instructions</a>
807 on setting up reminders to enable sending of reminders.</p>
808 <p>When defining a new custom field, the following types listed
809 below are available. "Arg 1" and "Arg 2" have different meaning
810 depending on the type of field. In some cases, "Arg 1" and "Arg 2" are
813 <table style="width: 100%;">
821 <td><tt>EXTRA_TEXT</tt></td>
822 <td>Allows the user to enter a single line of text</td>
823 <td>Specifies the size of the text form element as it would
824 appear in the following ("NN" would be replaced with Arg 1):<br />
825 <tt><input size="NN" ...</tt></td>
829 <td><tt>EXTRA_MULTILINETEXT</tt></td>
830 <td>Allows the user to enter multiple lines of text</td>
831 <td>Specifies how many characters wide the textform element
832 should be as it would appear in the following ("NN" would be replaced
834 <tt><textarea cols="NN" ...</tt></td>
835 <td>Specifies how many lines long the textform element should be
836 as it would appear in the following ("NN" would be replaced with Arg
838 <tt><textarea rows="NN" ...</tt></td>
841 <td><tt>EXTRA_URL</tt></td>
842 <td>Allows the user to enter a single line of text and will be
843 displayed as a link when viewed</td>
848 <td><tt>EXTRA_DATE</tt></td>
849 <td>Allows the user to select a date using the standard date
850 selection form elements</td>
855 <td><tt>EXTRA_EMAIL</tt></td>
856 <td>Allows the user to enter a single line of text and will be
857 displayed as a mailto URL link</td>
862 <td><tt>EXTRA_REMINDER</tt></td>
863 <td>Allows the user to specify if a reminder should be sent out
865 <td>Specifies how many minutes before the event that the reminder
867 <td>Specifies other reminder-specific options. The following
868 options are available:
870 <li><tt>$EXTRA_REMINDER_WITH_DATE</tt></li>
871 <li><tt>$EXTRA_REMINDER_WITH_OFFSET</tt></li>
872 <li><tt>$EXTRA_REMINDER_DEFAULT_YES</tt></li>
874 If more than one option is needed, they should be or-ed together with
875 the <tt>|</tt> character.</td>
878 <td><tt>EXTRA_REMINDER_DATE</tt></td>
879 <td>Allows the user to specify if a reminder should be sent out
880 for the event and and what time it should be sent</td>
881 <td>Specifies the default for how many minutes before the event
882 that the reminder should be sent. The user can override this when they
883 create/edit the event.</td>
884 <td>Specifies other reminder-specific options. The following
885 options are available:
887 <li><tt>$EXTRA_REMINDER_WITH_DATE</tt></li>
888 <li><tt>$EXTRA_REMINDER_WITH_OFFSET</tt></li>
889 <li><tt>$EXTRA_REMINDER_DEFAULT_YES</tt></li>
891 If more than one option is needed, they should be or-ed together with
892 the <tt>|</tt> character.</td>
895 <td><tt>EXTRA_SELECTION_LIST</tt></td>
896 <td>Presents the user with a selection list (single selection) to
898 <td>Specifies the list of available options using the PHP <tt>array</tt>
904 <div class="top"><a href="#" target="_top">↑ top</a></div>
908 <h2>Frequently Asked Questions</h2>
910 <!-- cek: leave these comments here... extractfaqs.pl looks for them -->
911 <!-- START FAQ: Installation/Setup -->
912 <dt>How do I setup PHP, MySQL and Apache on Windows?</dt>
913 <dd>The easiest way to do this is to try one of the prepackaged
914 bundles that will install all of these for you:
916 <li><a href="http://www.foxserv.net/">FoxServ</a> <a
917 href="http://www.foxserv.net" title="Open in new window"
918 target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></li>
919 <li><a href="http://www.sokkit.net/">Sokkit</a> <a
920 href="http://www.sokkit.net" title="Open in new window" target="_new"><img
921 src="newwin.gif" alt="new" class="newwin" /></a> (formlery PHPTriad)</li>
924 <dt>How do I setup PHP, MySQL and Apache on UNIX/Linux?</dt>
925 <dd>There are many online instructions on how to do this. Here are
929 href="http://www.onlamp.com/pub/a/php/2000/11/17/php_admin.html">ONLamp.com:
930 Basic Installtion of PHP on a Unix System</a> <a
931 href="http://www.onlamp.com/pub/a/php/2000/11/17/php_admin.html"
932 title="Open in new window" target="_new"><img src="newwin.gif"
933 alt="new" class="newwin" /></a></li>
935 href="http://www.devshed.com/Server_Side/PHP/SoothinglySeamless/">Developer
936 Shed: The Soothingly Seamless Setup of Apache, SSL, MySQL and PHP</a> <a
937 href="http://www.devshed.com/Server_Side/PHP/SoothinglySeamless/"
938 title="Open in new window" target="_new"><img src="newwin.gif"
939 alt="new" class="newwin" /></a></li>
940 <li><a href="http://www.linuxhelp.net/guides/lamp/">Linux
941 Help: LAMP Guide</a> <a href="http://www.linuxhelp.net/guides/lamp/"
942 title="Open in new window" target="_new"><img src="newwin.gif"
943 alt="new" class="newwin" /></a></li>
944 <li><a href="http://www.php.net/manual/en/installation.php">PHP.net</a> <a
945 href="http://www.php.net/manual/en/installation.php"
946 title="Open in new window" target="_new"><img src="newwin.gif"
947 alt="new" class="newwin" /></a></li>
950 <dt>I've finished the install. What is the login to WebCalendar?</dt>
951 <dd>After the initial creation of the database tables, there will
952 be a single user account created with the username "admin" and the
953 password set to "admin" as well. <br />
954 <span class="note">Note:</span> This account is intended to get your
955 started. You should create a new admin account and delete this one.</dd>
956 <dt><a name="samplepublic">I want to use WebCalendar as an
957 events calendar for my organization. How do I set it up to do this?</a></dt>
958 <dd>You will want to setup WebCalendar to use public access.
960 <li>Setup your <tt>settings.php</tt> file as a multi-user system
961 (see <a href="#appsetup">instructions</a>).</li>
962 <li>In System Settings, set "Allow public access" to "Yes."</li>
963 <li>If you want people to be able to submit new events through
964 public access, set "Public access can add events" to "Yes."</li>
965 <li>If you set "Public access can add events" to "Yes", set the
966 setting for "Public access new events require approval" to your
967 liking. If you set this to "Yes," an admin user will need to approve
968 any new events before they will appear on the public access calendar.</li>
969 <li>Login using one of the accounts you have setup. Add a new
970 event, and select "Public User" as one of the participants.</li>
971 <li>If you have enabled "Require event approvals" in your System
972 Settings, then you will need to approve the new event. Choose the
973 "Unapproved Events" at the bottom of any page (you must be an admin
974 user to access this). You will be presented with a list of unapproved
975 events (for both the current user and for the Public User account).
976 Approve the new event for the Public User.</li>
977 <li>Go to the Login page. You will see a "Access public calendar"
978 link that will bring you to the calendar for public access.</li>
979 <li>By default, the index.php page should send users to the
980 public calendar.</li>
984 <dt>How can I add holidays to the calendar?</dt>
985 <dd>There is no built-in support for holidays because it is not
986 necessary. You can add holidays into WebCalendar by importing one of
987 the many iCal holiday files that are freely available. A good resource
988 for free iCal files is <a href="http://www.icalshare.com">iCalShare
989 <img src="newwin.gif" alt="new" class="newwin" /></a>. For example, the
990 U.S. holiday ics file can be downloaded from:
992 href="http://icalshare.com/article.php?story=20020912105939521">http://icalshare.com/article.php?story=20020912105939521
993 <img src="newwin.gif" alt="new" class="newwin" /></a></blockquote>
994 If you don't want each individual user to have to import the holiday
995 calendar, you can use nonuser calendars. First, make sure nonuser
996 calendars are enabled in your system settings. Then, from
997 Admin->Users, you can access nonuser calendars. Create a new nonuser
998 calendar (such as "usholidays"). Then, notify your users that they can
999 add this nonuser calendar as a layer to their own calendar in order to
1000 see the holidays.</dd>
1002 <dt>Why are deleted events still present in the database?</dt>
1003 <dd>When you delete an event from your calendar, it is not deleted
1004 from the database. Instead, it is marked as deleted. This allows the
1005 system administrator access to information even after it is deleted.</dd>
1006 <dt>Can I setup more than one public calendar?</dt>
1007 <dd>You cannot directly setup two public calendars. However, there
1008 are two options for emulating this type of functionality:
1010 <li>You can <a href="WebCalendar-UserManual.html#categories">create
1011 global categories</a> and point users to the calendar with only a certain
1012 category displayed.</li>
1013 <li>You can setup multiple NonUser calendars and enable public
1014 access viewing of other users' calendars. You can then link directly
1015 to the calendar of one of the NonUser calendars, or you can <a
1016 href="WebCalendar-UserManual.html#views">setup a view</a> that
1017 contains the calendar of one or more of the NonUser calendars.</li>
1020 <dt>How do I change the title "Public Access" at the top of the
1022 <dd>In the file <tt>translations/English-US.txt</tt>, change the
1023 line that says "Public Access" to what you want it to say on the right
1026 Example: <pre>Public Access: Foobar Event Calendar</pre></dd>
1027 <dt>Can I embed WebCalendar as a component on another web page?</dt>
1028 <dd>WebCalendar is meant to be run as a standalone web
1029 application. You can customize the appearance of WebCalendar to match
1030 your existing site. To do this, In System Settings, set both "Custom
1031 header" and "Custom trailer" to "Yes" and press the "Edit" button to
1032 enter the header and trailer content. <br />
1033 If you are looking to just include a list of upcoming events in one of
1034 your web pages, you can use the <tt>upcoming.php</tt> page in
1035 WebCalendar to do this. Edit the top of this file to configure options.
1036 (These settings will likely move into System Settings in subsequent
1037 release.) You can then use an <tt>iframe</tt> elsewhere on your web
1038 site as in the example below: <pre><iframe height="250" width="300" scrolling="yes" src="upcoming.php"></iframe></pre>
1039 Include this HTML anywhere on any of your pages. By default, the events
1040 from the public calendar will be loaded (so you must have "Public
1041 Access" enabled in System Settings). You can override this with another
1042 user's calendar. (See <tt>upcoming.php</tt> for instructions on this.)
1044 <dt>How do I add a new translation?</dt>
1045 <dd>It's a fairly simple process. If you've ever translated a
1046 C-based app that used GNU's gettext tool, then you'll have no problem.
1047 The I18N support was based on GNU's <a
1048 href="http://www.gnu.org/software/gettext/gettext.html">gettext</a> <a
1049 href="http://www.gnu.org/software/gettext/gettext.html"
1050 title="Open in new window" target="_new"><img src="newwin.gif"
1051 alt="new" class="newwin" /></a>. Here's what you need to do.
1053 <li>look in the "translations" directory</li>
1054 <li>copy the <tt>English-US.txt</tt> file into what you'd like to
1055 call your language data file. (e.g. <tt>cp English-US.txt
1056 French.txt</tt>)</li>
1057 <li>Now translate all the text to the _right_ of the ":" into the
1058 new language. Do <i>not</i> alter the text to the left of the ":".</li>
1059 <li>When you're done making changes, move into the "tools"
1060 directory. Run the <tt>check_translation.pl</tt> script on your new
1061 data file to make sure you have all the needed translations. (e.g. <tt>perl
1062 check_translation.pl French</tt>)</li>
1063 <li>Add the new language to both the $languages array and the
1064 $browser_languages arrays defined in <tt>includes/config.php</tt>.</li>
1065 <li>Test it out...</li>
1066 <li>Post a copy of your translation (along with your changes to <tt>includes/config.php</tt>)
1068 href="http://sourceforge.net/tracker/?group_id=3870&atid=303870">SourceForge
1070 href="http://sourceforge.net/tracker/?group_id=3870&atid=303870"
1071 title="Open in new window" target="_new"><img src="newwin.gif"
1072 alt="new" class="newwin" /></a> for WebCalendar.</li>
1075 <dt>How do I update an existing translation?</dt>
1076 <dd>Just open up the translation file in the <tt>translations</tt>
1077 directory with your favorite text editor (like vi, vim, emacs, pico,
1078 Notepad, etc.). In particular look for places where missing
1079 translations are indicated. All missing translations should be marked
1080 with a "<< MISSING >>" note. and typically the
1081 English version of the translation will also be included on the
1082 following line (as in the example below): <pre># << MISSING >>
1085 For some text, an abberviation may be used rather than the English
1086 text. In those cases, the full text will be noted as in the following
1087 example: <pre># << MISSING >>
1088 # custom-script-help:
1089 # English text: Allows entry of custom Javascript or stylesheet text that
1090 # will be inserted into the HTML "head" section of every page.
1092 When you're done making changes, move into the <tt>tools</tt>
1093 directory. Run the <tt>check_translation.pl</tt> script on your new
1094 data file to make sure you have all the needed translations: <pre><tt>perl check_translation.pl French</tt></pre>
1095 Post a copy of your translation to the <a
1096 href="http://sourceforge.net/tracker/?group_id=3870&atid=303870">SourceForge
1098 href="http://sourceforge.net/tracker/?group_id=3870&atid=303870"
1099 title="Open in new window" target="_new"><img src="newwin.gif"
1100 alt="new" class="newwin" /></a> for WebCalendar.</dd>
1104 <div class="top"><a href="#" target="_top">↑ top</a></div>
1107 <a name="trouble"></a>
1108 <h2>Troubleshooting</h2>
1110 <!-- cek: leave these comments here... extractfaqs.pl looks for them -->
1111 <!-- START FAQ: Troubleshooting -->
1112 <dt>I get error messages about undefined variables when I try to
1114 <dd>On newer versions of PHP, the default setting of PHP is to
1115 display messages when an undefined variable is referenced. To prevent
1116 these messages from being displayed, change the setting of <tt>error_reporting</tt>
1117 in your <tt>php.ini</tt> file to be: <pre>error_reporting = E_ALL & ~E_NOTICE</pre>
1118 Alternately, you can disable any error messages from being displayed in
1119 the browser and have them logged to a file. (See the comments included
1120 in the <tt>php.ini</tt> file for instructions on how to do this.)</dd>
1121 <dt>I get errors when trying to add an event that contains a
1122 single quotation.</dt>
1123 <dd>WebCalendar is designed to work with PHP's <tt>magic_quotes_gpc</tt>
1124 feature (configured in <tt>php.ini</tt>). If you do not have this
1125 enabled (<tt>On</tt> in <tt>php.ini</tt>), you may get errors when
1126 adding events. In WebCalendar version 0.9.43 or later, you will always
1127 get an error message telling you to update <tt>php.ini</tt> if <tt>magic_quotes_gpc</tt>
1128 is set to <tt>Off</tt>. <br />
1130 <span class="tip">TIP</span> If you are using Apache as your web server
1131 and if you cannot or do not want to enable <tt>magic_quotes_gpc</tt>
1132 for your entire site, you can enable it just for WebCalendar. Create a
1133 <tt>.htaccess</tt> file in the toplevel WebCalendar directory that
1134 contains a single line: <pre>php_value magic_quotes_gpc 1</pre>
1135 <p>(For this to work with Apache, you must have the Apache <tt>AllowOverride
1136 All</tt> directive enabled for the directory where WebCalendar is installed.
1137 Additionally, PHP must be running as an Apache module, not a CGI.)</p>
1139 <span class="note">Note for Oracle and PostgreSQL:</span> You must also
1140 change the value of <tt>magic_quotes_sybase</tt> to <tt>On</tt> within
1141 the <tt>php.ini</tt> settings.</dd>
1142 <dt>I get an error message from PHP saying "Call to undefined
1144 <dd>This tells you that your version of PHP is missing something
1145 that WebCalendar needs. If the function mentioned is a database login
1146 function (<em>ociplogin</em>, <em>mysql_pconnect</em>, <em>ibase_connect</em>,
1147 <em>pg_pconnect</em>), then you probably do not have the needed
1148 database support for your database compiled into PHP. If the function
1149 is not a database connect call, then check the <a
1150 href="http://www.php.net/manual/en/">PHP manual</a> <a
1151 href="http://www.php.net/manual/en/" title="Open in new window"
1152 target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>
1153 to see if the function requires a specific version of PHP. You may have
1154 an out-dated version of PHP that requires upgrading.</dd>
1155 <dt>When I try and view certain pages, nothing happens for 30
1156 seconds, then I get a time-out error.</dt>
1157 <dd>On slower or very busy servers, it can take some time for the
1158 server to get all the events. Most PHP installations have a built-in
1159 timeout out of 30 seconds and will interrupt any request that takes
1160 longer than that. This is most likely to happen on the year-long custom
1161 report or on the month view when layers are being used. If you have
1162 access, you can increase the time-out value for PHP in the <tt>php.ini</tt>
1163 file by changing the setting of the <tt>max_execution_time</tt>
1165 <dt>I get an error message that says "Can't connect to local MySQL
1166 server through socket '/tmp/mysql.sock'."</dt>
1167 <dd>This is a PHP/MySQL configuration issue. The value of <tt>mysql.default_socket</tt>
1168 in your <tt>php.ini</tt> file must match the value of <tt>socket</tt>
1169 in your <tt>my.cnf</tt> file. Edit the <tt>php.ini</tt> file to fix
1171 <dt>I am not receiving any email messages from WebCalendar.</dt>
1172 <dd>WebCalendar sends two types of email messages: Notifications<a
1173 href="#g_notification">*</a> and Reminders<a href="#g_reminder">*</a>.
1174 Check the following if you are not receiving any email:
1176 <li>You have defined a valid SMTP server in your PHP
1177 configuration file <tt>php.ini</tt>. (The setting is "SMTP" in the
1178 "mail_function" section.)</li>
1179 <li>In WebCalendar's System Settings, you have set the "Email
1180 Enabled" setting to "Yes".</li>
1181 <li>In WebCalendar's System Settings, make sure you have the
1182 "Default sender address" to something. <br />
1183 <span class="note">Note:</span> Some mail system will reject mail that
1184 has a "From" address that is a different domain from the originating
1185 SMTP server. So, if your SMTP server is smtp.mydomain.com and your
1186 "Default sender address" is calendar@someotherdomain.com, some mail
1187 systems may bounce the mail back.</li>
1188 <li>For a Notification, make sure you have the type of
1189 Notification set to "Yes" in the user's Preferences.</li>
1192 <li>Make sure you have "Event reminders" set to "Yes" in the
1193 user's Preferences.</li>
1194 <li>Make sure you have <a href="#reminders">setup a cron job</a>
1195 to periodically run the <tt>send_reminders.php</tt> script.</li>
1200 <dt>Some of the pages are displaying text in English rather than
1201 <insert your language here></dt>
1202 <dd>The translations have been submitted at various points of
1203 WebCalendar development. Some have not been updated to include newer
1205 <dt>The text that I entered in the <a href="#siteextras">Custom
1206 Event Fields</a> is not being translated to different languages.</dt>
1207 <dd>You will need to add an entry in each of the translation files
1208 for any text you add into the Custom Event Fields.</dd>
1209 <dt>How do I get the most recent version of WebCalendar?</dt>
1210 <dd>You can download the latest public release from SourceForge's
1211 <a href="http://sourceforge.net/project/showfiles.php?group_id=3870">file
1212 list for WebCalendar</a> <a
1213 href="http://sourceforge.net/project/showfiles.php?group_id=3870"
1214 title="Open in new window" target="_new"><img src="newwin.gif"
1215 alt="new" class="newwin" /></a>. <br />
1216 You can download the latest development code from the CVS server using
1217 the <a href="http://sourceforge.net/cvs/?group_id=3870">instructions
1218 provided by SourceForge</a> <a
1219 href="http://sourceforge.net/cvs/?group_id=3870"
1220 title="Open in new window" target="_new"><img src="newwin.gif"
1221 alt="new" class="newwin" /></a>. (You will need a CVS client to do this.)</dd>
1222 <dt>How do I install a patch file listed on SourceForge's <a
1223 href="http://sourceforge.net/tracker?group_id=3870&atid=303870">list
1224 of WebCalendar patches</a> <a
1225 href="http://sourceforge.net/tracker?group_id=3870&atid=303870"
1226 title="Open in new window" target="_new"><img src="newwin.gif"
1227 alt="new" class="newwin" /></a>?</dt>
1228 <dd>Most patches are distributed as context diffs. That means they
1229 were produced using the UNIX <tt>diff</tt> command with the <tt>-C</tt>
1230 option. The patches are intended to be used with the <a
1231 href="http://www.fsf.org/software/patch/patch.html">GNU patch</a> <a
1232 href="http://www.fsf.org/software/patch/patch.html"
1233 title="Open in new window" target="_new"><img src="newwin.gif"
1234 alt="new" class="newwin" /></a> program. This program is standard on most
1235 Linux systems and can be obtained as part of the <a
1236 href="http://www.cygwin.com">Cygwin</a> <a
1237 href="http://www.cygwin.com" title="Open in new window" target="_new"><img
1238 src="newwin.gif" alt="new" class="newwin" /></a> package for Windows. Mac
1239 OS X will have the patch program installed if they install the
1240 developer tools CD.</dd>
1241 <dt>I forgot/lost my admin password. How can I reset it?</dt>
1242 <dd>The easiest way is to admin a new admin user and then use that
1243 new user to reset the password for your old admin account. Assuming you
1244 have deleted the original 'admin' login, you can use the following SQL
1245 to insert a new admin user into the database: <pre>INSERT INTO webcal_user ( cal_login, cal_passwd, cal_lastname,
1246 cal_firstname, cal_is_admin ) VALUES
1247 ( 'admin', '21232f297a57a5a743894a0e4a801fc3', 'Administrator',
1248 'Default', 'Y' );</pre> This will add a user with login 'admin' and password
1249 'admin' to the database. If you still have a user named 'admin', then
1250 replace 'admin' in the above SQL with a different username.</dd>
1251 <dt>I get a database error indicating table <tt>webcal_config</tt>
1252 does not exist.</dt>
1253 <dd>This is the first table that WebCalendar tries to access, so
1254 it typically means one of the following:
1256 <li>You have not created the database tables as described in the
1258 <li>You have the wrong database name specified in your <tt>includes/settings.php</tt>
1264 <div class="top"><a href="#" target="_top">↑ top</a></div>
1268 <h2>Getting Help</h2>
1269 <p>Try the Help/Troubleshooting forum for WebCalendar, hosted at
1270 SourceForge.net:</p>
1272 href="https://sourceforge.net/forum/forum.php?forum_id=11588">https://sourceforge.net/forum/forum.php?forum_id=11588</a> <a
1273 href="http://sourceforge.net/forum/forum.php?forum_id=11588"
1274 title="Open in new window" target="_new"><img src="newwin.gif"
1275 alt="new" class="newwin" /></a></pre>
1276 <p>If you encounter a bug, please check the <a
1277 href="http://sourceforge.net/tracker/?group_id=3870&atid=103870">list
1278 of open and pending bugs</a> <a
1279 href="http://sourceforge.net/tracker/?group_id=3870&atid=103870"
1280 title="Open in new window" target="_new"><img src="newwin.gif"
1281 alt="new" class="newwin" /></a>. If you do <strong>not</strong> see
1282 anything similar, submit a new bug.</p>
1283 <div class="top"><a href="#" target="_top">↑ top</a></div>
1286 <a name="license"></a>
1288 <p>WebCalendar is distributed under the open source <a
1289 href="http://www.gnu.org/licenses/gpl.html">GNU General Public
1290 License</a> <a href="http://www.gnu.org/licenses/gpl.html"
1291 title="Open in new window" target="_new"><img src="newwin.gif"
1292 alt="new" class="newwin" /></a>. If you have questions about this license,
1293 please read their <a href="http://www.gnu.org/licenses/gpl-faq.html">GPL
1294 FAQ</a> <a href="http://www.gnu.org/licenses/gpl-faq.html"
1295 title="Open in new window" target="_new"><img src="newwin.gif"
1296 alt="new" class="newwin" /></a>.</p>
1297 <div class="top"><a href="#" target="_top">↑ top</a></div>
1300 <a name="glossary"></a>
1303 <dt><a name="g_activitylog">Activity Log</a></dt>
1304 <dd>A summary of recent updates to calendar data</dd>
1305 <dt><a name="g_assistant">Assistant</a></dt>
1306 <dd>A calendar user that has been designated by another calendar
1307 user (the Boss) to help manage their calendar</dd>
1308 <dt><a name="g_boss">Boss</a></dt>
1309 <dd>A calendar user that has designated another calendar user (the
1310 Assistant) to help manage his calendar</dd>
1311 <dt><a name="g_externaluser">External User</a></dt>
1312 <dd>A calendar participant that does not have a calendar user
1314 <dt><a name="g_group">Group</a></dt>
1315 <dd>A mechanism of dividing up a large set of users into smaller
1317 <dt><a name="g_layer">Layer</a></dt>
1318 <dd>A function that allows a user to overlay another user's
1319 calendar on top of his own calendar so that the standard day, week and
1320 month pages show both his own and the layered user's events</dd>
1321 <dt><a name="g_ldap">LDAP</a></dt>
1322 <dd>LDAP (Lighweight Directory Access Protocol) is an Internet
1323 protocol used to maintain user directories</dd>
1324 <dt><a name="g_mulituser">Multi-User Mode</a></dt>
1325 <dd>When WebCalendar is configued in Multi-User Mode, there can be
1326 multiple user accounts, each with his own calendar. Unless Public
1327 Access is enalbed, all users will be required to login before they can
1328 access the system.</dd>
1329 <dt><a name="g_nis">NIS</a></dt>
1330 <dd>NIS (Network Information Service) is a UNIX-based user
1331 authentication system for managing user directories in a network</dd>
1332 <dt><a name="g_nonuser">NonUser Calendar</a></dt>
1333 <dd>A participant to a calendar event that is not a calendar user.
1334 This is typically used either as a resource (conference room, laptop
1335 computer) that needs to be shared or as a shared calendar that other
1336 users overlay onto their own calendar using layers (company-wide
1337 calendar, holiday calendar, etc.)</dd>
1338 <dt><a name="g_notification">Notification</a></dt>
1339 <dd>An email message that is sent when an event is added, removed
1340 or updated in the user's calendar by another user</dd>
1341 <dt><a name="g_preferredview">Preferred View</a></dt>
1342 <dd>The standard page (day, week, month or year) that will be
1343 presented to the user after logging in (set in user <a href="#pref">Preferences</a>)</dd>
1344 <dt><a name="g_preferredview">Public Access</a></dt>
1345 <dd>A <a href="#systemsettings">System Setting</a> that will allow
1346 anonymous users to access the calendar. See the <a href="#samplepublic">simple
1347 instructions</a> for setting this up in the <a href="#faq">FAQ section</a>.
1348 (Requires WebCalendar to be configued in Multi-User Mode).</dd>
1349 <dt><a name="g_reminder">Reminder</a></dt>
1350 <dd>An email message that is sent before an event to remind the
1352 <dt><a name="g_singleuser">Single-User Mode</a></dt>
1353 <dd>When WebCalendar is configued in Single-User Mode, there is no
1354 concept of users. You will be managing a single calendar and no login
1355 will be required. Anyone accessing this calendar will have full
1356 privileges to view, add, edit and delete all events.</dd>
1357 <dt><a name="g_timeinterval">Time Interval</a></dt>
1358 <dd>The amount of time each "block" will represent in either the
1359 day or week view (set in user <a href="#pref">Preferences</a>)</dd>
1360 <dt><a name="g_view">View</a></dt>
1361 <dd>A customized page that presents the events of selected users</dd>
1362 <dt><a name="g_workhours">Work Hours</a></dt>
1363 <dd>The default hours to show in the week and day view where
1364 events are displayed in blocks of time (set in user <a href="#pref">Preferences</a>)</dd>
1366 <div class="top"><a href="#" target="_top">↑ top</a></div>
1369 <a name="appendixA"></a>
1370 <h2>Appendix A: Using phpMyAdmin</h2>
1371 <p>If you have <a href="http://www.phpmyadmin.net">phpMyAdmin</a>
1372 installed and configured to manage your MySQL database, use the
1373 following steps to setup WebCalendar. (The following information is
1374 based on phpMyAdmin version 2.6.1.)</p>
1376 <li>On the initial phpMyAdmin page, under the "MySQL" heading, the
1377 first option should be "Create new database." Enter the name you have
1378 chosen for the database and press the "Create" button. (The default
1379 database name used by WebCalendar is "intranet".) After pressing the
1380 "Create" button, it should say: "Database <your database name
1381 here> has been created."</li>
1382 <li>Click on the home icon (the small house) in the left-side
1383 navigation. This will bring you back to your phpMyAdmin home page.</li>
1384 <li>(Optional) Create new MySQL user. If you already have a MySQL
1385 login that you would like to use, you can skip this step.</li>
1388 <li>Click on the "Privileges" link under the "MySQL" heading.</li>
1389 <li>Below any existing users listed, click on the link "Add a new
1391 <li>Fill in the details of your new database user. The default
1392 username for WebCalendar is "webcalendar" with a password of
1393 "webcal01". Leave the "Host" field set to "Any host".</li>
1394 <li>From the list of "Global privileges", be sure to select:
1395 SELECT, INSERT, UPDATE, DELETE, FILE, CREATE, ALTER, INDEX, DROP</li>
1396 <li>Click on the "Go" button.</li>
1397 <li>You should see a page that says "You have added a new user."</li>
1400 <li>Click on the "Databases" tab at the top of the page.</li>
1401 <li>From the list of databases on the page, click on the name of
1402 the database that you created.</li>
1403 <li>Click on the "SQL" tab at the top of the page.</li>
1404 <li>At the bottom of the page, there is an area to upload a SQL
1405 file. Click on the "Browse" button and select the <tt>tables-mysql.sql</tt>
1406 file in the WebCalendar toplevel directory. Then, press the "Go"
1408 <li>The top of the page should say "Your SQL-query has been
1409 executed successfully."</li>
1410 <li>You have now finished creating the WebCalendar database
1415 <div class="top"><a href="#" target="_top">↑ top</a></div>
1418 <a name="appendixB"></a>
1419 <h2>Appendix B: Setting Up Reminders on Windows</h2>
1421 <p>You have two options to choose from when setting up email
1422 reminders on a Windows platform. You can either install a cron package
1423 for Windows, or you can use the Windows Task Scheduler.</p>
1425 <h3>Installing a Cron Package</h3>
1426 <p>If you install a cron package for Windows, you will need to setup
1427 to setup a cron job. (UNIX cron is a tool for used to run tasks as
1428 specified times anywhere from every minute to once a year.)</p>
1429 <p>First, you should create a <tt>sendreminders.bat</tt> file that
1430 contains a single line:</p>
1431 <pre>C:\your\path\to\php.exe C:\your\path\to\webcalendar\tools\send_reminders.php</pre>
1432 <p>You can place this <tt>sendreminders.bat</tt> file anywhere on
1433 your file system.</p>
1434 <p>Next, you need to setup the cron job. The crontab entry should
1435 look like the following (replace with the correct path to your newly
1436 created <tt>sendreminders.bat</tt> file):</p>
1438 <pre>1 * * * * C:\your\path\to\sendreminders.bat</pre>
1440 <p>The "1 * * * *" will tell the cron schedule to run this task at 1
1441 after the hour all day long (12:01am, 1:01am, 2:01am, etc.) If you only
1442 want to run it once per day, you could use:</p>
1443 <pre>1 4 * * * C:\your\path\to\sendreminders.bat</pre>
1444 <p>This would tell the cron scheduler to run the task at 4:01am
1445 every day. For more information about the syntax of cron, check the
1446 documentation for the package you have installed or view the UNIX man
1447 page for crontab (like <a href="http://www.rt.com/man/crontab.5.html"
1448 target="_blank">this one</a>).</p>
1451 <p>There are many cron packages for Windows available. Below is a
1452 list of packages to choose from. (Note: use at your own risk. These
1453 links are provided for information only.)</p>
1456 <li><a href="http://cronw.sourceforge.net/" target="_blank">CRONw</a>
1459 href="http://www.gold-software.com/VisualCron-review11507.htm"
1460 target="_blank">VisualCron</a> (freeware)</li>
1461 <li><a href="http://www.nncron.ru" target="_blank">nnCron</a>
1462 (freeware and commercial versions)</li>
1463 <li><a href="http://surguy.net/articles/icron.xml" target="_blank">iCron</a>
1465 <li><a href="http://p.clark.home.mindspring.com/jcron/index.html"
1466 target="_blank">jCron</a> (freeware)</li>
1469 <h3>Using the Windows Task Schedule</h3>
1471 <p>Follow the steps listed below to setup a new task in the Windows
1472 Task Scheduler. (These instructions were created with Windows XP
1473 Professional. Other versions of Windows might be different.)</p>
1477 <li>Create a new batch file called <tt>sendreminders.bat</tt>. The
1478 contents of this file should be a single line: <pre>C:\your\path\to\php.exe C:\your\path\to\webcalendar\tools\send_reminders.php</pre>
1481 <li>On Windows XP, go to Control Panel</li>
1482 <li>Double-click on "Scheduled Tasks." This brings up a window
1483 that says "Scheduled Task Wizard"</li>
1485 <li>Click on "Browse..."</li>
1487 <li>Select the location of your newly created <tt>sendreminders.bat</tt>
1489 <li>Click on "Open"</li>
1491 <li>Change the name of the task. "WebCalendar Reminders" is a good
1494 <li>Select how often to perform this task. Select "Daily."</li>
1495 <li>Click on "Next"</li>
1497 <li>Select the start time, then click "Next". If you are planning
1498 on sending out reminders throughout the day, pick a time shortly after
1501 <li>Enter your user password as required. Click on "Next."</li>
1503 <li>Select the checkbox "Open advanced properites".</li>
1504 <li>Click on "Finish."</li>
1506 <li>Under the "Schedule" tab, click on "Advanced."</li>
1508 <li>Click on "Repeat Task" and fill in the details of how often
1509 the job should run. For example, you can set it to run "every 15
1510 minutes", then click on "until" and set that time to 11:30pm.</li>
1514 <div class="top"><a href="#" target="_top">↑ top</a></div>
1517 <a name="appendixC"></a>
1518 <h2>Appendix C: Displaying Upcoming Events on Your Site</h2>
1520 <p>If you would like to list upcoming events somewhere on a page on
1521 your site (someplace other than the WebCalendar pages), you can use the
1522 <tt>upcoming.php</tt> page to do this. This page is intended to be
1523 included in other pages using the <tt>iframe</tt> tag.</p>
1524 <p>You may need to modify some of the variables near the top of <tt>upcoming.php</tt>
1525 with a text editor:</p>
1526 <table border="0" style="margin-left: 20px; margin-right: 20px;">
1529 <td valign="top">$public_must_be_enabled</td>
1530 <td>Specifies if Public Access must be enabled in System Settings
1531 for this page to be viewed. <br />
1532 Default setting: false</td>
1536 <td valign="top">$display_link</td>
1537 <td>Specifies if events should have a link to the URL within
1538 WebCalendar to view the event. <br />
1539 Default setting: true</td>
1543 <td valign="top">$link_target</td>
1544 <td>Specifies the name of the window that be used for the link
1546 Default setting: _top</td>
1550 <td valign="top">$numDays</td>
1551 <td>Specifies how many days of events should be listed. <br />
1552 Can override this by passing "num" in within the URL with
1553 "upcoming.php?num=60" <br />
1554 Default setting: 30</td>
1558 <td valign="top">$maxEvents</td>
1559 <td>Specifies the maximum number of events to list. <br />
1560 Default setting: 10</td>
1564 <td valign="top">$username</td>
1565 <td>The login of the calendar to display upcoming events for. If
1566 you want to see upcoming events for user login "joe", then you would
1567 change this to "joe". <br />
1568 Default setting: __public__ (The public calendar)</td>
1572 <td valign="top">$allow_user_override</td>
1573 <td>Specifies whether the calendar user can be specified in the
1574 URL (in which case the $username setting will be ignored) using a URL
1575 like "upcoming.php?user=joe". <br />
1576 Default setting: true</td>
1580 <td valign="top">$load_layers</td>
1581 <td>Specifies if the calendar user's layers should also be
1582 included in the upcoming events. <br />
1583 Note: Layers must be enabled in the user's preferences. <br />
1584 Default setting: true</td>
1588 <td valign="top">$cat_id</td>
1589 <td>Specifies a category id to filter events on. <br />
1590 Note: Categories must be enabled in System Settings. <br />
1591 Default setting: (empty)</td>
1596 <p>Below is an example of how you would include <tt>upcoming.php</tt>
1597 in a simple HTML page.</p>
1599 <html><head><title>ACME Home Page</title></head>
1601 <h1>Welcome to the ACME Home Page</h1>
1602 <h2>News</h2><
1603 p>No news....</p>
1604 <h2>Upcoming Events</h2>
1605 <iframe src="upcoming.php" width="400" height="400" name="califrame" />
1611 <p><span class="tip">TIP</span> The <a
1612 href="http://www.w3schools.com/tags/tag_iframe.asp" target="_blank">W3
1613 Schools</a> site provides documentation about the different options that you
1614 can use with the <tt>iframe</tt> tag.</p>
1617 <div class="top"><a href="#" target="_top">↑ top</a></div>
1620 <a name="appendixD"></a>
1621 <h2>Appendix D: How To Configure For LDAP</h2>
1623 <p>Configuring WebCalendar to use an existing LDAP directory is
1624 fairly simple. It is know to work with OpenLDAP and Novell Edirectory
1625 and should work with other systems as well. <span class="note">Note:</span>
1626 If you use LDAP, the group functionailty of WebCalendar does not yet
1629 <p>To configure WebCalendar to use LDAP, do the following:</p>
1631 <li>Configure <tt>settings.php</tt></li>
1632 <li>Configure <tt>includes/user-ldap.php</tt></li>
1635 <p>The first step is to set WebCalendar to use LDAP authentication
1636 in <tt>settings.php</tt>. Instructions on to do this can be found in the
1637 <a href="#appsetup">Application Setup</a> section above. In summary, the
1638 following should be set:<br />
1639 <tt>use_http_auth = false</tt><br />
1640 <tt>user_inc = user-ldap.php</tt><br />
1643 <p>The next step is a little more work and involves editing the <tt>includes/user-ldap.php</tt>
1644 file with a text editor. You will have to set several configuration
1645 variables. If you don't know what to set the variables to, consult your
1646 LDAP system administrator. Documentation exists for all variables in the
1647 file. Finally, users have gotten LDAP working with OpenLDAP and Novell
1648 Edirectory by just changing the following:</p>
1650 <table border="0" style="margin-left: 20px; margin-right: 20px;">
1653 <td valign="top">$ldap_server</td>
1654 <td>FQDN or IP address of the LDAP server (or localhost). <br />
1655 ex. 'ldapserver.company.com'</td>
1659 <td valign="top">$ldap_base_dn</td>
1660 <td>Specifies the base DN used to search for users <br />
1661 ex. 'ou=people,dc=company,dc=com' or 'o=context,ou=subcontext'</td>
1665 <td valign="top">$ldap_admin_group_name</td>
1666 <td>Specifies a group (complete DN) with admin rights for
1668 You might have to create one in LDAP <br />
1669 ex. 'cn=it,ou=group,dc=company,dc=com'</td>
1674 <h3>Using SSL with LDAP</h3>
1675 <p>If the LDAP server will accept connections over SSL, simply add
1676 'ldaps://' to the beginning of <tt>$ldap_server</tt>. <br />
1677 Example: ldaps://ldapserver.company.com</p>
1679 <h3>Using TLS with LDAP</h3>
1680 <p>If the LDAP server is set up to use TLS, just set <tt>$ldap_start_tls
1684 <div class="top"><a href="#" target="_top">↑ top</a></div>
1686 <p><a href="http://validator.w3.org/check?uri=referer"><img
1687 src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!"
1688 class="valid" /></a></p>