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;
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 System Administrator's Guide</h1>
84 <p><strong>WebCalendar Version:</strong> 1.0.0</p>
86 <h2>Table of Contents</h2>
88 <li><a href="#intro">Introduction</a></li>
89 <li><a href="#requirements">System Requirements</a></li>
90 <li><a href="#fileunpacking">File Unpacking</a></li>
91 <li><a href="#dbsetup">Database Setup</a></li>
92 <li><a href="#appsetup">Application Setup</a></li>
93 <li><a href="#reminders">Setting Up Email Reminders</a></li>
94 <li><a href="#systemsettings">System Settings</a></li>
95 <li><a href="#siteextras">Custom Event Fields</a></li>
96 <li><a href="#faq">FAQ</a></li>
97 <li><a href="#trouble">Troubleshooting</a></li>
98 <li><a href="#help">Getting Help</a></li>
99 <li><a href="#license">Licensing</a></li>
100 <li><a href="#glossary">Glossary</a></li>
101 <li><a href="#appendixA">Appendix A: Database Setup with phpMyAdmin</a></li>
102 <li><a href="#appendixB">Appendix B: Setting Up Reminders on Windows</a></li>
103 <li><a href="#appendixC">Appendix C: Displaying Upcoming Events on Your Site</a></li>
104 <li><a href="#appendixD">Appendix D: How To Configure For LDAP</a></li>
109 <h2>Introduction</h2>
111 <p>WebCalender is an open source PHP-based multi-user calendar.</p>
113 <p><strong>Features:</strong></p>
115 <li>Multi-user support</li>
116 <li>Group support</li>
117 <li>View day-at-glance</li>
118 <li>View month-at-glance</li>
119 <li>View week-at-glance</li>
120 <li>View year-at-glance</li>
121 <li>View another user's calendar</li>
122 <li>View multiple users' calendars at the same time</li>
123 <li>View one or more users' calendar via layers on top of your own calendar</li>
124 <li>Public calendar (that requires no login) where anonymous users
125 submit events that are approved by an administrator</li>
126 <li>Add/Edit/Delete users</li>
127 <li>Add/Edit/Delete events</li>
128 <li>Repeating events</li>
129 <li>Custom event fields</li>
130 <li>Search interface for calendar entries</li>
131 <li>User-configurable preferences for colors, 12/24 time format,
132 Week start on Sun or Mon, default work hours</li>
134 <li>Checks for scheduling conflicts</li>
135 <li>Support for multiple timezones</li>
136 <li>Users can accept or reject events added by another user to their calendar</li>
137 <li>Email reminders</li>
138 <li>Email notifications for new events</li>
139 <li>Support for 30 different languages:
145 <li>简体中文(GB2312)</li>
148 <li>Deutsch (German)</li>
150 <li>Español (Spanish)</li>
152 <li>Français (French)</li>
154 <li>Hollands (Dutch)</li>
155 <li>Holo (Taiwanese)</li>
158 <li>Italiano (Italian)</li>
161 <li>Norsk (Norwegian)</li>
164 <li>Portuguese/Brazil</li>
166 <li>Русско (Russian)</li>
167 <li>Suomalainen (Finnish)</li>
168 <li>Svensk (Swedish)</li>
173 <li>Exporting to and importing from:
180 <li>Authentication using:
183 <li>HTTP authentication</li>
188 <li>Activity log that tracks:
190 <li>event creation</li>
191 <li>event updates</li>
192 <li>event acceptance</li>
193 <li>event rejection</li>
194 <li>email notifications</li>
195 <li>email reminders</li>
199 <div class="top"><a href="#" target="_top">↑ top</a></div>
202 <a name="requirements"></a>
203 <h2>System Requirements</h2>
205 <li>PHP 4 (PHP 5 not yet tested) with <tt>magic_quotes_gpc</tt> enabled</li>
206 <li>Database (see <a href="#database">below</a>)</li>
207 <li>CSS-enabled browser</li>
208 <li>JavaScript-enabled browser</li>
209 <li>If not using HTTP-based authentication, then browser cookies are required</li>
211 <p><strong>Recommended:</strong></p>
213 <li>pilot-link (if exporting to Palm):
214 <a href="http://sourceforge.net/project/?group_id=2158">http://sourceforge.net/project/?group_id=2158</a> <a href="http://sourceforge.net/project/?group_id=2158" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></li>
216 <p><a name="database">You must have one of the following databases installed</a>:</p>
222 <li>MS SQL Server</li>
223 <li>ODBC (PHP ODBC includes support for Adabas D, IBM DB2, Solid and Sybase SQL Anywhere as well as ODBC)</li>
225 <p>For the database you choose, you must have its drivers built into
226 PHP. For example, to use MySQL, PHP must be compiled with MySQL
227 support (which is the default setting when installing PHP).
228 See the PHP pages (<a href="http://www.php.net">www.php.net</a> <a href="http://www.php.net" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>)
229 for more information on setting up PHP.</p>
230 <p>No optional PHP packages (other than MySQL) are required for this
231 application. However, PHP shoud be compiled with <tt>--enable-track-vars</tt>
233 <p>Make sure that <tt>magic_quotes_gpc</tt> in <tt>php.ini</tt>
234 is turned on (otherwise, you will get an error message when you try to access WebCalendar.)</p>
235 <p><span class="tip">TIP</span> If you are using Apache
236 as your web server and if you cannot or do not want to enable
237 <tt>magic_quotes_gpc</tt> for your entire site, you can enable
238 it just for WebCalendar.
239 Create a <tt>.htaccess</tt> file in the toplevel WebCalendar
240 directory that contains a single line:</p>
241 <pre>php_value magic_quotes_gpc 1</pre>
242 <p>(For this to work with Apache, you must have the Apache
243 <tt>AllowOverride All</tt> directive enabled for the directory
244 where WebCalendar is installed.
245 Additionally, PHP must be running as an Apache module, not
248 <p>You can run PHP either as a CGI or an Apache module. You'll get better
249 performance with PHP setup as a module. Not only will you not have to
250 deal with the CGI performance hit, but you'll be able to use PHP's
251 database connection pooling. Additionally, this application can use
252 a form/cookie-based authentication or traditional HTTP authentication.
253 For traditional HTTP authentication, PHP must be built as an Apache
255 <p>If you are planning on using email reminders, you will need to build
256 PHP as a CGI in order to run the <tt>send_reminders.php</tt> script. I would
257 strongly recommend building a module-based PHP for your web server
258 and then a second PHP build to create the CGI version.</p>
259 <p><span class="tip">TIP</span> Some Linux distributions come with both a module-based PHP
260 with Apache and a standalone PHP binary.
261 Check for <tt>/usr/bin/php</tt> to see if you already have the
262 PHP standalone executable. If it's there, you can use
263 the following command to see what version of PHP you have:</p>
264 <pre>/usr/bin/php -v</pre>
265 <div class="top"><a href="#" target="_top">↑ top</a></div>
268 <a name="fileunpacking"></a>
269 <h2>File Unpacking</h2>
270 <p>Unpack the calendar software in its own directory somewhere where
271 your web server will find it. (See your web server docs for info.)</p>
272 <p>By default, WebCalendar should create its own directory
273 when you unpack it. The new directory name will typically
274 contain the version name (such as <tt>WebCalendar-0.9.41</tt>).
275 You can rename this directory after unpacking the files if you
276 prefer a directory name like <tt>calendar</tt> or <tt>webcalendar</tt>.
277 Keep in mind that unless you remap the directory (via your web server's
278 configuration settings), it will be part of the URL for the calendar.</p>
279 <div class="top"><a href="#" target="_top">↑ top</a></div>
282 <a name="dbsetup"></a>
283 <h2>Database Setup</h2>
284 <p>There are three steps in setting up the database:</p>
286 <li>Creating the database</li>
287 <li>Creating the user</li>
288 <li>Creating the required tables</li>
290 <p>Follow the steps outlined below for the database you are using.
291 When complete, a single user account will be created
292 with the <strong>login "admin" and password "admin"</strong>, which you are encouraged
293 to use to create your own account.</p>
294 <p><span class="note">Note:</span> In the examples below, text in <strong>bold</strong>
295 represents text that you must type in.</p>
296 <p><span class="note">Security:</span> The default values for database, login, and
297 password (<strong>intranet</strong>, <strong>webcalendar</strong>, and <strong>webcal01</strong>) are for demonstration purposes only
298 and should never be used in a production environment.</p>
299 <h3 class="colorheader">MySQL</h3>
300 <p>The following will create a database named "intranet".</p>
301 <pre><strong>mysqladmin create intranet</strong></pre>
302 <p>Next, create the database user account that will be used to access the database.</p>
303 <pre><strong>mysql --user=root mysql</strong>
304 mysql> <strong>GRANT ALL PRIVILEGES ON *.* TO webcalendar@localhost
305 IDENTIFIED BY 'webcal01' WITH GRANT OPTION;</strong>
306 mysql> <strong>FLUSH PRIVILEGES;</strong>
307 mysql> <strong>QUIT</strong></pre>
308 <p>If you will be accessing MySQL from a different machine than
309 the one running the web server, repeat the command above
310 and replace 'localhost' with the hostname of the other machine.</p>
311 <p>Create the calendar tables using the supplied <tt>tables-mysql.sql</tt> file:</p>
312 <pre><strong>mysql intranet < tables-mysql.sql</strong></pre>
313 <p>In the above example, "intranet" is the name of your database.</p>
315 <p><span class="note">Note:</span> If you are using
316 <a href="http://www.phpmyadmin.net">phpMyAdmin</a> to
317 manage your MySQL database, follow the
318 instructions in <a href="#appendixA">Appendix A</a>.
321 <h3 class="colorheader">Oracle</h3>
322 <p>The following will create a tablespace named "webcalendar".
323 From the command line, startup sqlplus and
324 issue the following command:</p>
325 <pre><strong>sqlplus</strong>
326 SQL> <strong>CREATE TABLESPACE webcalendar
327 DATAFILE 'webcalendar.dat' SIZE 10M
328 AUTOEXTEND ON NEXT 10M MAXSIZE 40M;</strong></pre>
329 <p>Next, create the database user account that will be used to access the database.</p>
330 <pre><strong>sqlplus</strong>
331 SQL> <strong>CREATE USER webcalendar IDENTIFIED BY webcal01
332 DEFAULT TABLESPACE webcalendar;</strong>
333 SQL> <strong>GRANT dba TO webcalendar;</strong>
334 SQL> <strong>quit</strong></pre>
335 <p>Create the calendar tables using the supplied <tt>tables-oracle.sql</tt> file:</p>
336 <pre><strong>sqlplus webcalendar/webcal01</strong>
337 SQL> <strong>@tables-oracle;</strong>
338 SQL> <strong>quit</strong></pre>
340 <h3 class="colorheader">PostgreSQL</h3>
341 <p>The following will create a database named "webcalendar".
342 From the command line, startup psql and
343 issue the following command:</p>
344 <pre><strong>create database webcalendar;
346 \i tables-postgres.sql
349 <h3 class="colorheader">Interbase</h3>
350 <p>The following will create a database named "WEBCAL.gdb".
351 From the command line, startup usql and
352 issue the following command:</p>
353 <pre><strong>CREATE DATABASE 'WEBCAL.gdb';</strong></pre>
355 <p>Create the calendar tables using the supplied <tt>tables-ibase.sql</tt> file:</p>
357 connect /path/WEBCAL.gdb;
358 input path/table-ibase.sql;</strong></pre>
360 <h3 class="colorheader">ODBC</h3>
361 <p>Setup will depend on which database you are using.
362 When it comes time to create the tables,
363 the <tt>tables-postgres.sql</tt> file should work for most
365 <h3 class="colorheader">MSSQL</h3>
366 <p>Create a database, <strong>intranet,</strong> and add a user, <strong>webcalendar</strong>, to access this database. The user should be granted public, db_datareader,
367 and db_datawriter privileges. Open SQL Query Analyzer then open
368 the file <tt>tables-postgres.sql</tt>. Make sure you have identified <strong>intranet</strong> as the target database and Execute the contents of the sql file.</p>
369 <div class="top"><a href="#" target="_top">↑ top</a></div>
372 <a name="appsetup"></a>
373 <h2>Application Setup</h2>
374 <p>Next, you will need to run the web-based database setup script
375 (simply direct your browser to your new WebCalendar location).
376 You will need to modify the permissions of the <tt>includes</tt>
377 directory. On Linux/UNIX, you should change this directory
378 to be read/write for all users (<tt>chmod 777 includes</tt>).
379 On Windows, change this directory to have full access for all users
380 using Windows Explorer. Changing the write permissions will allow the web-based
381 database configuration tool to create the <tt>settings.php</tt> file.</p>
383 <p><span class="tip">TIP</span> After you have created the
384 <tt>settings.php</tt> file (with the "Save Settings" button),
385 you can change the permissions back to a more restrictive setting.</p>
387 <p>After you test and save your database settings, you
388 will be prompted to enter an installation password.
389 <b>Write this password down somewhere.</b> There is no way to reset
390 this password. If you forget this password and need to change your database settings,
391 you will need to manually edit the <tt>settings.php</tt> file with a text editor.</p>
393 <p>If you choose not to use the web-based database configuration
394 tool, you can manually edit the <tt>settings.php</tt> file.
395 There is an example file <tt>settings.php.orig</tt> that you
396 can use as a starting point. Simply rename this file to <tt>settings.php</tt>.
397 You will need to set the values as follows in <tt>settings.php</tt>:</p>
398 <p>To configure your database access. Set the values for:</p>
399 <table class="distinguish">
403 One of "mysql", "oracle", "postgresql", "odbc",
410 The hostname that database is running on.
411 (Use localhost if it's the same machine as
412 the web server.) (This variable is not used with ODBC)
420 The database password for the above login
424 The name of the database that the calendar
425 tables reside in. ("intranet" in the <a href="#dbsetup">examples above</a>.)
426 For ODBC, this should be the DSN.
429 db_persistent</td><td>
430 Enable use of persistent (pooled) database connections.
431 This should typically be enabled.
435 <p>You can configure the calendar to run in single-user<a href="#g_singleuser">*</a> mode or
436 multi-user<a href="#g_multiuser">*</a> mode. If this is your first time using the
437 calendar, it's easier to try single-user. You can always switch to multi-user
438 later. Leave <tt>single_user</tt> set to "N" (the default) for multi-user or set
439 it to "Y" and set the value of <tt>single_user_login</tt> to a login name of your liking
440 to set the system to single-user mode. (And be sure to set the value of
441 <tt>single_user_login</tt> to the login that you would choose if you decide to switch
442 to multi-user mode some day.)</p>
443 <p><span class="note">Note:</span> If you do decide to switch from single-user mode to multi-user mode,
444 make sure you add in a user to the system for the login you set the
445 <tt>single_user_login</tt> variable to. You will need to do this via the
446 database (mysql, sqlplus, etc.) Look in the <tt>tables-mysql.sql</tt>
447 (or <tt>tables-oracle.sql</tt>, etc.) to see the example of adding in the "admin" user.</p>
448 <p>If you are setting up a multi-user calendar, you will need to choose
449 how your users are authenticated. You must change the settings of
450 <tt>use_http_auth</tt> and <tt>user_inc</tt>
451 to setup which authentication method to use.</p>
452 <p>You currently have four choices:</p>
454 <li>Web-based authentication (login/passwords verified in the WebCalendar database):<br />
455 <tt>use_http_auth = false</tt><br />
456 <tt>user_inc = user.php</tt>
458 <li>HTTP-based authentication (login/passwords verified by the web server):<br />
459 <tt>use_http_auth = true</tt><br />
460 <tt>user_inc = user.php</tt><br />
461 ... and don't forget to setup your web server to handle user
462 authentication.<br />
463 <span class="note">Note:</span> In order to use HTTP-based authentication,
464 PHP must be setup as a module for your server rather than a CGI.
466 <li>NIS-based authentication (login/passwords verified by NIS):<br />
467 <tt>use_http_auth = false</tt><br />
468 <tt>user_inc = user-nis.php</tt><br />
469 Additional configuration settings will need to be set
470 in <tt>includes/user-nis.php</tt>.
472 <li>LDAP-based authentication (login/passwords verified by LDAP server):<br />
473 <tt>use_http_auth = false</tt><br />
474 <tt>user_inc = user-ldap.php</tt><br />
475 Additional configuration settings will need to be set
476 in <tt>includes/user-ldap.php</tt>.
479 <p>Keep in mind that if you want to use reminders, you will need to
480 setup the <tt>send_reminders.php</tt> script (see below) and keep your admin
481 setting for "Email enabled" set to "Yes" on the admin settings page.</p>
482 <p>At this point, your WebCalendar installation should be up and running.
483 To access WebCalendar open up your favorite web browser and
484 type in the URL. The URL will depend on where you installed
486 <p>When you unpacked/unzipped the WebCalendar distribution, it typically
487 creates a directory that includes the version number.
488 For example, if the zip file was named <tt>WebCalendar-0.9.99.zip</tt>
489 (or <tt>WebCalendar-0.9.99.tar.gz</tt>), then there
490 should be a <tt>WebCalendar-0.9.99</tt> directory. For convenience, you
491 can rename this directory so that the URL does not include the version
492 number. On Windows, you can do this from the Windows Explorer.
493 On Linux/UNIX, you can use the <tt>mv</tt> command to rename the directory.
494 Supposing you renamed the <tt>WebCalendar-0.9.99</tt> directory to just
495 be <tt>calendar</tt>, and you unpacked/unzipped the files into your toplevel
496 web server directory, the URL would be:</p>
497 <pre>http://yourserverhere/calendar/index.php</pre>
498 <p>If you have not previously configured your database settings,
499 you will be automatically redirected to a web page for
500 configuring your database settings. After you have configured the database,
501 use the URL again to access WebCalendar.</p>
502 <p>If you have configured your web server to use <tt>index.php</tt> as the
503 default index page for a directory, you can omit that from the URL.
504 On a single-user system, your browser should be redirected to week.php
505 initially. On a multi-user system, your browser should be redirected to login.php
506 so that you can login.</p>
507 <p><span class="tip">TIP</span> On a multi-user system, the only user account created
508 during installation has the username of "admin" and a password of "admin". You should create
509 a new admin account and delete this one for security reasons.</p>
510 <div class="top"><a href="#" target="_top">↑ top</a></div>
514 <h2>Creating Users</h2>
515 <p>After logging in as an admin user (the initial username is "admin" with
516 password "admin"), you will see a common set of links at the bottom
517 of each page. Follow these steps to create a new user:</p>
519 <li>Login to WebCalendar as an admin user</li>
520 <li>Click on the "Admin" link at the bottom of any WebCalendar page</li>
521 <li>Click on the "Users" button</li>
522 <li>Click on the "Add New User" link</li>
523 <li>Fill out the form with details for the new user (email address is optional)</li>
524 <li>Click on the "Save" button</li>
526 <p><span class="tip">TIP</span> On a single-user system, you do not need to create any users.</p>
527 <p><span class="tip">TIP</span> For an event calendar, you do not need to create a user for the "public user".</p>
528 <div class="top"><a href="#" target="_top">↑ top</a></div>
531 <a name="reminders"></a>
532 <h2>Setting Up Email Reminders</h2>
533 <p>PHP does not come with a utility for executing time-based jobs.
534 So, in order to check periodically for email reminders, a shell
535 script was written in PHP. You will need two things to get this working:</p>
537 <li>You should have a version of PHP built as a CGI (so that you can run
538 php from the command line). This does not mean you must build all
539 of PHP as a CGI. You can still build PHP as a module for your web
540 server and then build the CGI-based PHP later.<br />
541 <span class="note">Note:</span> Many Linux distributions and some Windows LAMP packages
542 come with the PHP built for CGI.</li>
543 <li>You must setup cron (on Linux/UNIX) or something like cron for Windows
544 to run the <tt>send_reminders.php</tt> script periodically.</li>
546 <p>Building PHP as a CGI is outside the scope of these instructions. But,
547 if you read the PHP instructions, you'll see that the default build
548 settings will build the CGI-based PHP. If you really can't do this
549 (perhaps you don't have permission to install anything new on the
550 system), skip down a couple of paragraphs to an alternate solution
551 that does not require PHP CGI.</p>
552 <p>For Linux/UNIX users, add the following line to the crontab entry of
553 a user. (This would be the same user that the web server
554 process runs as.)</p>
555 <pre><tt>1 * * * * cd /some/directory/webcalendar/tools; ./send_reminders.php</tt></pre>
556 <p>Of course, replace the directory location to wherever the
557 <tt>send_reminders.php</tt> file can be found. If you moved this out of the
558 tools directory (which is recommended for security reasons),
559 be sure to update <tt>send_reminders.php</tt> since it needs
560 to know where to find other WebCalendar files.</p>
561 <p>If you cannot setup PHP as a CGI or have no idea how, you can leave
562 <tt>send_reminders.php</tt> in its current location and access it via a URL.
563 IMHO, this is not the best choice, but it still works. Setup a cron
564 job to access the URL. For Linux/UNIX users, add the following line to
565 the crontab entry of a user.</p>
566 <pre><tt>1 * * * * wget http://yourserverhere/webcalendardirectoryhere/tools/send_reminders.php > /dev/null</tt></pre>
567 <p>You should test this from the command line first to make sure your setup is
568 correct. If you do not have <tt>wget</tt> installed on your system, you can use
569 any tool (lynx, perl script, etc.) that is capable of making an HTTP request for this.</p>
570 <div class="top"><a href="#" target="_top">↑ top</a></div>
573 <a name="systemsettings"></a>
574 <h2>System Settings</h2>
575 <p>System Settings allows the administrator to control what features are available to users
576 as well as default values for certain features.</p>
577 <p>Many of these settings can be overridden by users in their Preferences (such as color).</p>
580 <dt>Application Name</dt>
581 <dd>Specifies the document title (typically displayed in the window title bar
582 of most browsers)</dd>
584 <dd>Specifies the base URL of the calendar. This information is needed to
585 accurately include URLs in email messages (Notifications and Reminders).</dd>
587 <dd>Specifies the default language setting for all users.</dd>
589 <dd>Specifies your preferred font. Multiple font names should be comma-separated.</dd>
590 <dt>Preferred View</dt>
591 <dd>Specify if users should see the day, week, month, or year after loggin in.</dd>
592 <dt>Display weekends in view</dt>
593 <dd>Specifies default setting for if Saturdays and Sundays should appear in the
594 calendar when viewing a month or week</dd>
596 <dd>Specifies the default format for displaying dates</dd>
598 <dd>Specifies the default time format as either 12-hour (3:45pm) or 24-hour (15:14)</dd>
599 <dt>Time interval</dt>
600 <dd>Specify the default number of minutes each time block represents in the day and
602 <dt>Auto-referesh calendars</dt>
603 <dd>If set to "yes," the day, week, and month pages will automatically
604 reload after a specified duration</dd>
605 <dt>Auto-refresh time</dt>
606 <dd>Specifies how long to wait before the auto-refresh should force a page
608 <dt>Display unapproved</dt>
609 <dd>Specifies whether events that have been added to a calendar but not yet
610 approved should display on the calendar (in a different color)</dd>
611 <dt>Display week number</dt>
612 <dd>Specifies whether the week number should be displayed in month and week views</dd>
613 <dt>Week starts on</dt>
614 <dd>Specifies if week start on Sunday or Monday</dd>
616 <dd>Specifies the default time range to display in day and week views</dd>
617 <dt>Disable Priority field</dt>
618 <dd>If enabled, the Priority field will not be used</dd>
619 <dt>Disable Access field</dt>
620 <dd>If enabled, the Access field will not be used</dd>
621 <dt>Disable Participants field</dt>
622 <dd>If enabled, the Participants field will not be used, and users will not be
623 able to add events to any calendar other than their own.</dd>
624 <dt>Disable Repeating field</dt>
625 <dd>If enabled, users will not be able to create repeating events</dd>
626 <dt>Allow viewing other user's calendars</dt>
627 <dd>If enabled, users will be able to view the calendar of another user</dd>
628 <dt>Allow public access</dt>
629 <dd>If enabled, anonymous users will be able to view the public access
630 calendar without logging in.</dd>
631 <dt>Public access can view other users</dt>
632 <dd>If enabled, anonymous users will be able to view the calendars of other users</dd>
633 <dt>Public access can add events</dt>
634 <dd>If enabled, anonymous users will be able to submit new events.</dd>
635 <dt>Public access new events require approval</dt>
636 <dd>If enabled, events submitted to the public access calendar (by anonymous
637 users) will require approval by an admin user. If not enabled, then new events
638 will appear on the public access calendar as soon as they are submitted.</dd>
639 <dt>Include add event link in views</dt>
640 <dd>If enabled, Views will include a link to quickly add events to the
641 specified user's calendar.</dd>
642 <dt>Allow external users</dt>
643 <dd>If enabled, the create/edit event page will contain a text area to include
644 the names (and optional email address) of event participants that are not calendar users.</dd>
645 <dt>External users can receive email notifications</dt>
646 <dd>If enabled, event participants entered into the External Participants
647 area will receive email notifications at the same time as calendar users (if an email
648 address was specified for the Exernal Participant).</dd>
649 <dt>External users can receive email reminders</dt>
650 <dd>If enabled, event participants entered into the External Participants
651 area will receive email reminders at the same time as calendar users (if an email
652 address was specified for the Exernal Participant).</dd>
653 <dt>Remember last login</dt>
654 <dd>If enabled, when a returning calendar user reaches the login page, their login name will be pre-filled with the last login username that they entered. (The password field will still be blank.)</dd>
655 <dt>Check for event conflicts</dt>
656 <dd>Specifies if the system should check for scheduling conflicts when a user adds or updates an event.</dd>
657 <dt>Conflict checking months</dt>
658 <dd>If conflict checking is enabled, this specifies how many months past the initial date the system will check for conflicts when a user adds or updates a repeating event.</dd>
659 <dt>Allow users to override conflicts</dt>
660 <dd>If enabled, users will be warned when there is an event conflict and be presented with the option of scheduling the event anyhow.</dd>
661 <dt>Limit number of timed events per day</dt>
662 <dd>If enabled, users can can be limited to a specific number of timed events per day</dd>
663 <dt>Maximum timed events per day</dt>
664 <dd>Specifies that maximum number of events that can be scheduled in one day of any one user.</dd>
668 <dt>Groups enabled</dt>
669 <dd>Specifies if group features should be enabled</dd>
670 <dt>User sees only his group</dt>
671 <dd>If enabled, users will be unaware of any users that are not in the same group as the user.</dd>
675 <dt>Cagtegoies enabled</dt>
676 <dd>Specifies if category features should be enabled</dd>
680 <dt>Email enabled</dt>
681 <dd>Specifies if email functionality should be enabled. If set to "No," then no email messages will be sent at any time.</dd>
682 <dt>Default sender address</dt>
683 <dd>Specifies the email originator to use when the system sends out email Notifications and Reminders</dd>
684 <dt>Event reminders</dt>
685 <dd>Specifies if email reminders for events that include a reminder should be sent</dd>
686 <dt>Events added to my calendar</dt>
687 <dd>Specifies if the system should send email when an event is added</dd>
688 <dt>Events updated on my calendar</dt>
689 <dd>Specifies if the system should send email when an event is updated</dd>
690 <dt>Events removed from my calendar</dt>
691 <dd>Specifies if the system should send email when an event is deleted</dd>
692 <dt>Event rejected by participant</dt>
693 <dd>Specifies if the system should send email when a participant to an event rejects the event</dd>
697 <dt>Allow user to customize colors</dt>
698 <dd>Specifies whether color settings should be available to users in their Preferences</dd>
699 <dt>Document background</dt>
700 <dd>Specifies the background color of all pages</dd>
701 <dt>Document title</dt>
702 <dd>Specifies the color of page title on each page</dd>
703 <dt>Document text</dt>
704 <dd>Specifies the default text color on each page</dd>
705 <dt>Table grid color</dt>
706 <dd>Specifies color of the lines that make HTML table grids on each page</dd>
707 <dt>Table header background</dt>
708 <dd>Specifies the default background for the heading of any HTML table</dd>
709 <dt>Table header text</dt>
710 <dd>Specifies the default text color for the heading of any HTML table</dd>
711 <dt>Table cell background</dt>
712 <dd>Specifies the background color for table cells</dd>
713 <dt>Table cell background for current day</dt>
714 <dd>Specifies the background color for the table cell containing the current date</dd>
715 <dt>Table cell background for weekend</dt>
716 <dd>Specifies the background color for table cells that represent a Saturday or Sunday</dd>
717 <dt>Event popup background</dt>
718 <dd>Specifies the background color of event popup areas</dd>
719 <dt>Event popup text</dt>
720 <dd>Specifies the text color of event popup areas</dd>
722 <div class="top"><a href="#" target="_top">↑ top</a></div>
725 <a name="siteextras"></a>
726 <h2>Custom Event Fields</h2>
727 <p>You may want to customize the event-specific fields found in
728 the <tt>includes/site_extras.php</tt> field.
729 If this is your first time using the calendar, you can skip
730 this step and come back later since this step
731 is <i>optional</i>.</p>
732 <p>You can use this feature to add extra
733 fields to your calendar events. For example, you can add a URL,
734 a contact email address, or a location.</p>
735 <p>By default, this file is configured with
736 a single reminder field that allows the user to specify how long
737 before the event the reminder should be sent.</p>
738 <p><span class="tip">TIP</span> See <a href="#reminders">instructions</a> on setting
739 up reminders to enable sending of reminders.</p>
740 <p>When defining a new custom field, the following types listed below
741 are available. "Arg 1" and "Arg 2" have different meaning depending on the type
742 of field. In some cases, "Arg 1" and "Arg 2" are not used.</p>
744 <table style="width: 100%;">
752 <tt>EXTRA_TEXT</tt></td><td>
753 Allows the user to enter a single line of text</td><td>
754 Specifies the size of the text form element as it would appear in the
755 following ("NN" would be replaced with Arg 1):<br />
756 <tt><input size="NN" ...</tt></td><td>
760 <tt>EXTRA_MULTILINETEXT</tt></td><td>
761 Allows the user to enter multiple lines of text</td><td>
762 Specifies how many characters wide the textform element should be as it
763 would appear in the following ("NN" would be replaced with Arg 1):<br />
764 <tt><textarea cols="NN" ...</tt></td><td>
765 Specifies how many lines long the textform element should be as it would
766 appear in the following ("NN" would be replaced with Arg 1):<br />
767 <tt><textarea rows="NN" ...</tt>
770 <tt>EXTRA_URL</tt></td><td>
771 Allows the user to enter a single line of text and will be displayed as a
772 link when viewed</td><td>
777 <tt>EXTRA_DATE</tt></td><td>
778 Allows the user to select a date using the standard date selection form
784 <tt>EXTRA_EMAIL</tt></td><td>
785 Allows the user to enter a single line of text and will be displayed as
786 a mailto URL link</td><td>
791 <tt>EXTRA_REMINDER</tt></td><td>
792 Allows the user to specify if a reminder should be sent out for
794 Specifies how many minutes before the event that the reminder
795 should be sent. </td><td>
796 Specifies other reminder-specific options. The following options are available:
798 <li><tt>$EXTRA_REMINDER_WITH_DATE</tt></li>
799 <li><tt>$EXTRA_REMINDER_WITH_OFFSET</tt></li>
800 <li><tt>$EXTRA_REMINDER_DEFAULT_YES</tt></li>
802 If more than one option is needed, they should be or-ed together with
803 the <tt>|</tt> character.
806 <tt>EXTRA_REMINDER_DATE</tt></td><td>
807 Allows the user to specify if a reminder should be sent out for the event
808 and and what time it should be sent</td><td>
809 Specifies the default for how many minutes before the event that the
810 reminder should be sent. The user can override this when they create/edit
812 Specifies other reminder-specific options. The following options are available:
814 <li><tt>$EXTRA_REMINDER_WITH_DATE</tt></li>
815 <li><tt>$EXTRA_REMINDER_WITH_OFFSET</tt></li>
816 <li><tt>$EXTRA_REMINDER_DEFAULT_YES</tt></li>
818 If more than one option is needed, they should be or-ed together with
819 the <tt>|</tt> character.
822 <tt>EXTRA_SELECTION_LIST</tt></td><td>
823 Presents the user with a selection list (single selection) to choose from</td><td>
824 Specifies the list of available options using the PHP <tt>array</tt>
830 <div class="top"><a href="#" target="_top">↑ top</a></div>
834 <h2>Frequently Asked Questions</h2>
836 <!-- cek: leave these comments here... extractfaqs.pl looks for them -->
837 <!-- START FAQ: Installation/Setup -->
838 <dt>How do I setup PHP, MySQL and Apache on Windows?</dt>
839 <dd>The easiest way to do this is to try one of the prepackaged bundles that will install all of these for you:
841 <li><a href="http://www.foxserv.net/">FoxServ</a> <a href="http://www.foxserv.net" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></li>
842 <li><a href="http://www.sokkit.net/">Sokkit</a> <a href="http://www.sokkit.net" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a> (formlery PHPTriad)</li>
845 <dt>How do I setup PHP, MySQL and Apache on UNIX/Linux?</dt>
846 <dd>There are many online instructions on how to do this. Here are a few:
848 <li><a href="http://www.onlamp.com/pub/a/php/2000/11/17/php_admin.html">ONLamp.com: Basic Installtion of PHP on a Unix System</a> <a href="http://www.onlamp.com/pub/a/php/2000/11/17/php_admin.html" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></li>
849 <li><a href="http://www.devshed.com/Server_Side/PHP/SoothinglySeamless/">Developer Shed: The Soothingly Seamless Setup of Apache, SSL, MySQL and PHP</a> <a href="http://www.devshed.com/Server_Side/PHP/SoothinglySeamless/" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></li>
850 <li><a href="http://www.linuxhelp.net/guides/lamp/">Linux Help: LAMP Guide</a> <a href="http://www.linuxhelp.net/guides/lamp/" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></li>
851 <li><a href="http://www.php.net/manual/en/installation.php">PHP.net</a> <a href="http://www.php.net/manual/en/installation.php" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></li>
854 <dt>I've finished the install. What is the login to WebCalendar?</dt>
855 <dd>After the initial creation of the database tables, there will
856 be a single user account created with the username "admin" and
857 the password set to "admin" as well.
858 <br /><span class="note">Note:</span> This account is intended to get your started.
859 You should create a new admin account and delete this one.</dd>
860 <dt><a name="samplepublic">I want to use WebCalendar as an events calendar for
861 my organization. How do I set it up to do this?</a></dt>
862 <dd>You will want to setup WebCalendar to use public access.
864 <li>Setup your <tt>settings.php</tt> file as a multi-user
865 system (see <a href="#appsetup">instructions</a>).</li>
866 <li>In System Settings, set "Allow public access" to "Yes."</li>
867 <li>If you want people to be able to submit new events
868 through public access, set "Public access can add events"
870 <li>If you set "Public access can add events" to "Yes",
871 set the setting for "Public access new events
872 require approval" to your liking. If you set this to "Yes,"
873 an admin user will need to approve any new events before
874 they will appear on the public access calendar.</li>
875 <li>Login using one of the accounts you have setup.
876 Add a new event, and select "Public User" as one of the
878 <li>If you have enabled "Require event approvals" in your
879 System Settings, then you will need to approve the new
880 event. Choose the "Unapproved Events" at the bottom
881 of any page (you must be an admin user to access this).
882 You will be presented with a list of unapproved events
883 (for both the current user and for the Public User account).
884 Approve the new event for the Public User.</li>
885 <li>Go to the Login page. You will see a "Access public calendar"
886 link that will bring you to the calendar for public access.</li>
887 <li>By default, the index.php page should send users to
888 the public calendar.</li>
892 <dt>How can I add holidays to the calendar?</dt>
893 <dd>There is no built-in support for holidays because it is
894 not necessary. You can add holidays into WebCalendar by importing
895 one of the many iCal holiday files that are freely available.
896 A good resource for free iCal files is
897 <a href="http://www.icalshare.com">iCalShare
898 <img src="newwin.gif" alt="new" class="newwin" /></a>.
899 For example, the U.S. holiday ics file can be downloaded from:
901 <a href="http://icalshare.com/article.php?story=20020912105939521">http://icalshare.com/article.php?story=20020912105939521
902 <img src="newwin.gif" alt="new" class="newwin" /></a>
904 If you don't want each individual user to have to import
905 the holiday calendar, you can use nonuser calendars.
906 First, make sure nonuser calendars are enabled in your
907 system settings. Then, from Admin->Users, you can
908 access nonuser calendars. Create a new nonuser calendar
909 (such as "usholidays"). Then, notify your users that they
910 can add this nonuser calendar as a layer to their own
911 calendar in order to see the holidays.
914 <dt>Why are deleted events still present in the database?</dt>
915 <dd>When you delete an event from your calendar, it is not
916 deleted from the database. Instead, it is marked as deleted.
917 This allows the system administrator access to information
918 even after it is deleted.</dd>
919 <dt>Can I setup more than one public calendar?</dt>
920 <dd>You cannot directly setup two public calendars. However,
921 there are two options for emulating this type of functionality:
923 <li>You can <a href="WebCalendar-UserManual.html#categories">create global categories</a> and point users to the calendar with only a certain category displayed.</li>
924 <li>You can setup multiple NonUser calendars and enable
925 public access viewing of other users' calendars.
926 You can then link directly to the calendar of one of
927 the NonUser calendars, or you can
928 <a href="WebCalendar-UserManual.html#views">setup a view</a>
929 that contains the calendar of one or more of the NonUser calendars.</li>
932 <dt>How do I change the title "Public Access" at the top of
934 <dd>In the file <tt>translations/English-US.txt</tt>,
935 change the line that says "Public Access" to what you want
936 it to say on the right side.<br/><br/>Example:
937 <pre>Public Access: Foobar Event Calendar</pre>
939 <dt>Can I embed WebCalendar as a component on another web page?</dt>
940 <dd>WebCalendar is meant to be run as a standalone web application.
941 You can customize the appearance of WebCalendar to match your existing
943 To do this, In System Settings, set both "Custom header" and
944 "Custom trailer" to "Yes" and press the "Edit" button to enter the
945 header and trailer content.
947 If you are looking to just include a list of upcoming events in one
948 of your web pages, you can use the <tt>upcoming.php</tt> page in
949 WebCalendar to do this. Edit the top of this file to configure options.
950 (These settings will likely move into System Settings in subsequent release.)
951 You can then use an <tt>iframe</tt> elsewhere on your web site as
952 in the example below:
953 <pre><iframe height="250" width="300" scrolling="yes" src="upcoming.php"></iframe></pre>
954 Include this HTML anywhere on any of your pages.
955 By default, the events from the public calendar will be loaded (so
956 you must have "Public Access" enabled in System Settings).
957 You can override this with another user's calendar.
958 (See <tt>upcoming.php</tt> for instructions on this.)
960 <dt>How do I add a new translation?</dt>
962 It's a fairly simple process. If you've ever translated a C-based app
963 that used GNU's gettext tool, then you'll have no problem. The I18N
964 support was based on GNU's <a href="http://www.gnu.org/software/gettext/gettext.html">gettext</a> <a href="http://www.gnu.org/software/gettext/gettext.html" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>. Here's what you need to do.
966 <li>look in the "translations" directory</li>
967 <li>copy the <tt>English-US.txt</tt> file into what you'd like to call your
968 language data file. (e.g. <tt>cp English-US.txt French.txt</tt>)</li>
969 <li>Now translate all the text to the _right_ of the ":" into the
970 new language. Do <i>not</i> alter the text to the left of the ":".</li>
971 <li>When you're done making changes, move into the "tools" directory.
972 Run the <tt>check_translation.pl</tt> script on your new data file to make
973 sure you have all the needed translations.
974 (e.g. <tt>perl check_translation.pl French</tt>)</li>
975 <li>Add the new language to both the $languages array and the
976 $browser_languages arrays defined in <tt>includes/config.php</tt>.</li>
977 <li>Test it out... </li>
978 <li>Post a copy of your translation (along with your changes to <tt>includes/config.php</tt>) to the <a href="http://sourceforge.net/tracker/?group_id=3870&atid=303870">SourceForge Patches</a> <a href="http://sourceforge.net/tracker/?group_id=3870&atid=303870" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a> for WebCalendar.</li>
981 <dt>How do I update an existing translation?</dt>
982 <dd>Just open up the translation file in the <tt>translations</tt> directory
983 with your favorite text editor (like vi, vim, emacs, pico, Notepad, etc.).
984 In particular look for places where missing translations are indicated.
985 All missing translations should be marked with a
986 "<< MISSING >>" note.
987 and typically the English version of the translation will also be included on the following line (as in the example below):
988 <pre># << MISSING >>
991 For some text, an abberviation may be used rather than the English text.
992 In those cases, the full text will be noted as in the following example:
993 <pre># << MISSING >>
994 # custom-script-help:
995 # English text: Allows entry of custom Javascript or stylesheet text that
996 # will be inserted into the HTML "head" section of every page.
998 When you're done making changes, move into the <tt>tools</tt> directory.
999 Run the <tt>check_translation.pl</tt> script on your new data file to make
1000 sure you have all the needed translations:
1001 <pre><tt>perl check_translation.pl French</tt></pre>
1002 Post a copy of your translation to the
1003 <a href="http://sourceforge.net/tracker/?group_id=3870&atid=303870">SourceForge Patches</a> <a href="http://sourceforge.net/tracker/?group_id=3870&atid=303870" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a> for WebCalendar.</dd>
1007 <div class="top"><a href="#" target="_top">↑ top</a></div>
1010 <a name="trouble"></a>
1011 <h2>Troubleshooting</h2>
1013 <!-- cek: leave these comments here... extractfaqs.pl looks for them -->
1014 <!-- START FAQ: Troubleshooting -->
1015 <dt>I get error messages about undefined variables when I try to view any page.</dt>
1016 <dd>On newer versions of PHP, the default setting of PHP is to display
1017 messages when an undefined variable is referenced. To prevent
1018 these messages from being displayed, change the setting of <tt>error_reporting</tt>
1019 in your <tt>php.ini</tt> file to be:
1020 <pre>error_reporting = E_ALL & ~E_NOTICE</pre>
1021 Alternately, you can disable any error messages from being displayed
1022 in the browser and have them logged to a file. (See the comments
1023 included in the <tt>php.ini</tt> file for instructions on how to do this.)</dd>
1024 <dt>I get errors when trying to add an event that contains a single quotation.</dt>
1025 <dd>WebCalendar is designed to work with PHP's
1026 <tt>magic_quotes_gpc</tt> feature (configured in <tt>php.ini</tt>).
1027 If you do not have this enabled (<tt>On</tt> in <tt>php.ini</tt>),
1028 you may get errors when adding events.
1029 In WebCalendar version 0.9.43 or later, you will always get an error
1030 message telling you to update <tt>php.ini</tt> if <tt>magic_quotes_gpc</tt>
1031 is set to <tt>Off</tt>.
1033 <span class="tip">TIP</span> If you are using Apache
1034 as your web server and if you cannot or do not want to enable
1035 <tt>magic_quotes_gpc</tt> for your entire site, you can enable
1036 it just for WebCalendar.
1037 Create a <tt>.htaccess</tt> file in the toplevel WebCalendar
1038 directory that contains a single line:
1039 <pre>php_value magic_quotes_gpc 1</pre>
1040 <p>(For this to work with Apache, you must have the Apache
1041 <tt>AllowOverride All</tt> directive enabled for the directory
1042 where WebCalendar is installed.
1043 Additionally, PHP must be running as an Apache module, not
1046 <span class="note">Note for Oracle and PostgreSQL:</span> You must also change the value of
1047 <tt>magic_quotes_sybase</tt> to <tt>On</tt> within the <tt>php.ini</tt>
1049 <dt>I get an error message from PHP saying "Call to undefined function: ..."</dt>
1050 <dd>This tells you that your version of PHP is missing something that
1051 WebCalendar needs. If the function mentioned is a database login
1052 function (<em>ociplogin</em>, <em>mysql_pconnect</em>, <em>ibase_connect</em>, <em>pg_pconnect</em>),
1053 then you probably do not have the needed database support for your database
1055 If the function is not a database connect call, then check the
1056 <a href="http://www.php.net/manual/en/">PHP manual</a> <a href="http://www.php.net/manual/en/" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>
1057 to see if the function requires a specific version of PHP. You
1058 may have an out-dated version of PHP that requires upgrading.</dd>
1059 <dt>When I try and view certain pages, nothing happens for 30 seconds, then I get a time-out error.</dt>
1060 <dd>On slower or very busy servers, it can take some time for the server
1061 to get all the events. Most PHP installations have a built-in timeout
1062 out of 30 seconds and will interrupt any request that takes longer than
1063 that. This is most likely to happen on the year-long custom report or
1064 on the month view when layers are being used. If you have access,
1065 you can increase the time-out value for PHP in the <tt>php.ini</tt>
1066 file by changing the setting of the <tt>max_execution_time</tt> setting.</dd>
1067 <dt>I get an error message that says "Can't connect to local MySQL server through socket '/tmp/mysql.sock'."</dt>
1068 <dd>This is a PHP/MySQL configuration issue. The value of <tt>mysql.default_socket</tt>
1069 in your <tt>php.ini</tt> file must match the value of <tt>socket</tt> in your
1070 <tt>my.cnf</tt> file. Edit the <tt>php.ini</tt> file to fix this problem.</dd>
1071 <dt>I am not receiving any email messages from WebCalendar.</dt>
1072 <dd>WebCalendar sends two types of email messages:
1073 Notifications<a href="#g_notification">*</a> and Reminders<a href="#g_reminder">*</a>.
1074 Check the following if you are not receiving any email:
1076 <li>You have defined a valid SMTP server in your PHP configuration file
1077 <tt>php.ini</tt>. (The setting is "SMTP" in the "mail_function" section.)</li>
1078 <li>In WebCalendar's System Settings, you have set the "Email Enabled" setting to "Yes".</li>
1079 <li>In WebCalendar's System Settings, make sure you have the "Default sender address"
1081 <br /><span class="note">Note:</span>
1082 Some mail system will reject mail that has a "From" address
1083 that is a different domain from the originating SMTP server.
1084 So, if your SMTP server is smtp.mydomain.com and your "Default sender address"
1085 is calendar@someotherdomain.com, some mail systems may bounce the mail back.</li>
1086 <li>For a Notification, make sure you have the type of Notification
1087 set to "Yes" in the user's Preferences.</li>
1090 <li>Make sure you have "Event reminders" set to "Yes" in the user's Preferences.</li>
1091 <li>Make sure you have <a href="#reminders">setup a cron job</a> to periodically
1092 run the <tt>send_reminders.php</tt> script.</li>
1097 <dt>Some of the pages are displaying text in English rather than <insert your language here></dt>
1098 <dd>The translations have been submitted at various points of WebCalendar development.
1099 Some have not been updated to include newer features.</dd>
1100 <dt>The text that I entered in the <a href="#siteextras">Custom Event Fields</a> is not being translated
1101 to different languages.</dt>
1102 <dd>You will need to add an entry in each of the translation files for any text you add
1103 into the Custom Event Fields.</dd>
1104 <dt>How do I get the most recent version of WebCalendar?</dt>
1105 <dd>You can download the latest public release from SourceForge's
1106 <a href="http://sourceforge.net/project/showfiles.php?group_id=3870">file list for WebCalendar</a> <a href="http://sourceforge.net/project/showfiles.php?group_id=3870" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>.
1108 You can download the latest development code from the CVS server using
1109 the <a href="http://sourceforge.net/cvs/?group_id=3870">instructions provided by SourceForge</a> <a href="http://sourceforge.net/cvs/?group_id=3870" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>. (You will need a CVS client to do this.)</dd>
1110 <dt>How do I install a patch file listed on SourceForge's
1111 <a href="http://sourceforge.net/tracker?group_id=3870&atid=303870">list of WebCalendar patches</a> <a href="http://sourceforge.net/tracker?group_id=3870&atid=303870" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>?</dt>
1112 <dd>Most patches are distributed as context diffs. That means they were produced using the UNIX <tt>diff</tt> command with the <tt>-C</tt> option. The patches are intended to be used with the <a href="http://www.fsf.org/software/patch/patch.html">GNU patch</a> <a href="http://www.fsf.org/software/patch/patch.html" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a> program. This program is standard on most Linux systems and can be obtained as part of the <a href="http://www.cygwin.com">Cygwin</a> <a href="http://www.cygwin.com" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a> package for Windows. Mac OS X will have the patch program installed if they install the developer tools CD.</dd>
1113 <dt>I forgot/lost my admin password. How can I reset it?</dt>
1114 <dd>The easiest way is to admin a new admin user and then use that
1115 new user to reset the password for your old admin account.
1116 Assuming you have deleted the original 'admin' login, you can use
1117 the following SQL to insert a new admin user into the database:
1118 <pre>INSERT INTO webcal_user ( cal_login, cal_passwd, cal_lastname,
1119 cal_firstname, cal_is_admin ) VALUES
1120 ( 'admin', '21232f297a57a5a743894a0e4a801fc3', 'Administrator',
1121 'Default', 'Y' );</pre>
1122 This will add a user with login 'admin' and password 'admin' to the database.
1123 If you still have a user named 'admin', then replace 'admin' in the above
1124 SQL with a different username.
1126 <dt>I get a database error indicating table <tt>webcal_config</tt> does not exist.</dt>
1127 <dd>This is the first table that WebCalendar tries to access, so it
1128 typically means one of the following:
1130 <li>You have not created the database tables as described in the instructions</li>
1131 <li>You have the wrong database name specified in your
1132 <tt>includes/settings.php</tt> file</li>
1137 <div class="top"><a href="#" target="_top">↑ top</a></div>
1141 <h2>Getting Help</h2>
1142 <p>Try the Help/Troubleshooting forum for WebCalendar, hosted at SourceForge.net:</p>
1143 <pre><a href="https://sourceforge.net/forum/forum.php?forum_id=11588">https://sourceforge.net/forum/forum.php?forum_id=11588</a> <a href="http://sourceforge.net/forum/forum.php?forum_id=11588" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a></pre>
1144 <p>If you encounter a bug, please check the
1145 <a href="http://sourceforge.net/tracker/?group_id=3870&atid=103870">list of open and pending bugs</a> <a href="http://sourceforge.net/tracker/?group_id=3870&atid=103870" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>.
1146 If you do <strong>not</strong> see anything similar, submit a new bug.
1148 <div class="top"><a href="#" target="_top">↑ top</a></div>
1151 <a name="license"></a>
1153 <p>WebCalendar is distributed under the open source
1154 <a href="http://www.gnu.org/licenses/gpl.html">GNU General Public License</a> <a href="http://www.gnu.org/licenses/gpl.html" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>.
1155 If you have questions about this license, please
1156 read their <a href="http://www.gnu.org/licenses/gpl-faq.html">GPL FAQ</a> <a href="http://www.gnu.org/licenses/gpl-faq.html" title="Open in new window" target="_new"><img src="newwin.gif" alt="new" class="newwin" /></a>.
1158 <div class="top"><a href="#" target="_top">↑ top</a></div>
1161 <a name="glossary"></a>
1164 <dt><a name="g_activitylog">Activity Log</a></dt>
1165 <dd>A summary of recent updates to calendar data</dd>
1166 <dt><a name="g_assistant">Assistant</a></dt>
1167 <dd>A calendar user that has been designated by another calendar user
1168 (the Boss) to help manage their calendar</dd>
1169 <dt><a name="g_boss">Boss</a></dt>
1170 <dd>A calendar user that has designated another calendar user
1171 (the Assistant) to help manage his calendar</dd>
1172 <dt><a name="g_externaluser">External User</a></dt>
1173 <dd>A calendar participant that does not have a calendar user account</dd>
1174 <dt><a name="g_group">Group</a></dt>
1175 <dd>A mechanism of dividing up a large set of users into smaller sets of users</dd>
1176 <dt><a name="g_layer">Layer</a></dt>
1177 <dd>A function that allows a user to overlay another user's calendar
1178 on top of his own calendar so that the standard day, week and month
1179 pages show both his own and the layered user's events</dd>
1180 <dt><a name="g_ldap">LDAP</a></dt>
1181 <dd>LDAP (Lighweight Directory Access Protocol) is an Internet protocol
1182 used to maintain user directories</dd>
1183 <dt><a name="g_mulituser">Multi-User Mode</a></dt>
1184 <dd>When WebCalendar is configued in Multi-User Mode,
1185 there can be multiple user accounts, each with his
1186 own calendar. Unless Public Access is enalbed, all users
1187 will be required to login before they can access the system.</dd>
1188 <dt><a name="g_nis">NIS</a></dt>
1189 <dd>NIS (Network Information Service) is a UNIX-based user authentication
1190 system for managing user directories in a network</dd>
1191 <dt><a name="g_nonuser">NonUser Calendar</a></dt>
1192 <dd>A participant to a calendar event that is not a calendar user. This is typically used either as a resource (conference room,
1193 laptop computer) that needs to be shared or as a shared calendar
1194 that other users overlay onto their own calendar using layers (company-wide calendar,
1195 holiday calendar, etc.)</dd>
1196 <dt><a name="g_notification">Notification</a></dt>
1197 <dd>An email message that is sent when an event is added, removed
1198 or updated in the user's calendar by another user</dd>
1199 <dt><a name="g_preferredview">Preferred View</a></dt>
1200 <dd>The standard page (day, week, month or year) that will
1201 be presented to the user after logging in
1202 (set in user <a href="#pref">Preferences</a>)</dd>
1203 <dt><a name="g_preferredview">Public Access</a></dt>
1204 <dd>A <a href="#systemsettings">System Setting</a> that will allow anonymous users
1205 to access the calendar.
1206 See the <a href="#samplepublic">simple instructions</a> for
1207 setting this up in the <a href="#faq">FAQ section</a>.
1208 (Requires WebCalendar to be configued in Multi-User Mode).</dd>
1209 <dt><a name="g_reminder">Reminder</a></dt>
1210 <dd>An email message that is sent before an event to remind
1211 the participant</dd>
1212 <dt><a name="g_singleuser">Single-User Mode</a></dt>
1213 <dd>When WebCalendar is configued in Single-User Mode,
1214 there is no concept of users. You will be managing a single
1215 calendar and no login will be required.
1216 Anyone accessing this calendar will have full privileges to
1217 view, add, edit and delete all events.</dd>
1218 <dt><a name="g_timeinterval">Time Interval</a></dt>
1219 <dd>The amount of time each "block" will represent in
1220 either the day or week view
1221 (set in user <a href="#pref">Preferences</a>)</dd>
1222 <dt><a name="g_view">View</a></dt>
1223 <dd>A customized page that presents the events of selected users</dd>
1224 <dt><a name="g_workhours">Work Hours</a></dt>
1225 <dd>The default hours to show in the week and day view where
1226 events are displayed in blocks of time (set in
1227 user <a href="#pref">Preferences</a>)</dd>
1229 <div class="top"><a href="#" target="_top">↑ top</a></div>
1232 <a name="appendixA"></a>
1233 <h2>Appendix A: Using phpMyAdmin</h2>
1235 If you have <a href="http://www.phpmyadmin.net">phpMyAdmin</a>
1236 installed and configured to manage your MySQL database, use the
1237 following steps to setup WebCalendar.
1238 (The following information is based on phpMyAdmin version 2.6.1.)
1241 <li>On the initial phpMyAdmin page, under the "MySQL" heading, the first
1242 option should be "Create new database." Enter the name you have
1243 chosen for the database and press the "Create" button.
1244 (The default database name used by WebCalendar is "intranet".)
1245 After pressing the "Create" button, it should say:
1246 "Database <your database name here> has been created." </li>
1247 <li>Click on the home icon (the small house) in the left-side
1248 navigation. This will bring you back to your phpMyAdmin home page.</li>
1249 <li>(Optional) Create new MySQL user. If you already have
1250 a MySQL login that you would like to use, you can skip this step.</li>
1252 <li>Click on the "Privileges" link under the "MySQL" heading.</li>
1253 <li>Below any existing users listed, click on the link "Add a new User."</li>
1254 <li>Fill in the details of your new database user.
1255 The default username for WebCalendar is "webcalendar"
1256 with a password of "webcal01".
1257 Leave the "Host" field set to "Any host".</li>
1258 <li>From the list of "Global privileges", be sure to select:
1259 SELECT, INSERT, UPDATE, DELETE, FILE, CREATE, ALTER, INDEX, DROP </li>
1260 <li>Click on the "Go" button.</li>
1261 <li>You should see a page that says "You have added a new user."</li>
1263 <li>Click on the "Databases" tab at the top of the page.</li>
1264 <li>From the list of databases on the page, click on the name
1265 of the database that you created.</li>
1266 <li>Click on the "SQL" tab at the top of the page.</li>
1267 <li>At the bottom of the page, there is an area to upload a SQL file.
1268 Click on the "Browse" button and select the <tt>tables-mysql.sql</tt>
1269 file in the WebCalendar toplevel directory.
1270 Then, press the "Go" button.</li>
1271 <li>The top of the page should say "Your SQL-query has been executed
1273 <li>You have now finished creating the WebCalendar database tables.</li>
1277 <div class="top"><a href="#" target="_top">↑ top</a></div>
1280 <a name="appendixB"></a>
1281 <h2>Appendix B: Setting Up Reminders on Windows</h2>
1283 <p>You have two options to choose from when setting up email
1284 reminders on a Windows platform.
1285 You can either install a cron package for Windows,
1286 or you can use the Windows Task Scheduler.
1289 <h3>Installing a Cron Package</h3>
1291 If you install a cron package for Windows, you will need to setup
1292 to setup a cron job.
1293 (UNIX cron is a tool for used to run tasks as specified times anywhere
1294 from every minute to once a year.)
1297 First, you should create a <tt>sendreminders.bat</tt> file
1298 that contains a single line:
1300 <pre>C:\your\path\to\php.exe C:\your\path\to\webcalendar\tools\send_reminders.php</pre>
1301 <p>You can place this <tt>sendreminders.bat</tt> file anywhere on your
1304 <p>Next, you need to setup the cron job.
1305 The crontab entry should look like
1306 the following (replace with the correct path to your
1307 newly created <tt>sendreminders.bat</tt> file):
1310 <pre>1 * * * * C:\your\path\to\sendreminders.bat</pre>
1312 <p>The "1 * * * *" will tell the cron schedule to run this task
1313 at 1 after the hour all day long (12:01am, 1:01am, 2:01am, etc.)
1314 If you only want to run it once per day, you could use:
1316 <pre>1 4 * * * C:\your\path\to\sendreminders.bat</pre>
1317 <p>This would tell the cron scheduler to run the task at 4:01am
1319 For more information about the syntax of cron, check the documentation
1320 for the package you have installed or
1321 view the UNIX man page for crontab
1322 (like <a href="http://www.rt.com/man/crontab.5.html"
1323 target="_blank">this one</a>).
1327 <p>There are many cron packages for Windows available.
1328 Below is a list of packages to choose from.
1329 (Note: use at your own risk. These links are provided
1330 for information only.)
1334 <li><a href="http://cronw.sourceforge.net/"
1335 target="_blank">CRONw</a> (open source) </li>
1336 <li><a href="http://www.gold-software.com/VisualCron-review11507.htm"
1337 target="_blank">VisualCron</a> (freeware)</li>
1338 <li><a href="http://www.nncron.ru"
1339 target="_blank">nnCron</a> (freeware and commercial versions)</li>
1340 <li><a href="http://surguy.net/articles/icron.xml"
1341 target="_blank">iCron</a> </li>
1342 <li><a href="http://p.clark.home.mindspring.com/jcron/index.html"
1343 target="_blank">jCron</a> (freeware) </li>
1346 <h3>Using the Windows Task Schedule</h3>
1348 <p>Follow the steps listed below to setup a new task
1349 in the Windows Task Scheduler.
1350 (These instructions were created with Windows XP Professional.
1351 Other versions of Windows might be different.)
1356 <li>Create a new batch file called <tt>sendreminders.bat</tt>.
1357 The contents of this file should be a single line:
1358 <pre>C:\your\path\to\php.exe C:\your\path\to\webcalendar\tools\send_reminders.php</pre>
1361 <li>On Windows XP, go to Control Panel</li>
1362 <li>Double-click on "Scheduled Tasks."
1363 This brings up a window that says "Scheduled Task Wizard" </li>
1365 <li>Click on "Browse..." </li>
1367 <li>Select the location of your newly created
1368 <tt>sendreminders.bat</tt> file.</li>
1369 <li>Click on "Open" </li>
1371 <li>Change the name of the task. "WebCalendar Reminders" is a good name.
1374 <li>Select how often to perform this task. Select "Daily." </li>
1375 <li>Click on "Next" </li>
1377 <li>Select the start time, then click "Next".
1378 If you are planning on sending out reminders throughout the
1379 day, pick a time shortly after midnight. </li>
1381 <li> Enter your user password as required. Click on "Next." </li>
1383 <li> Select the checkbox "Open advanced properites". </li>
1384 <li> Click on "Finish." </li>
1386 <li> Under the "Schedule" tab, click on "Advanced." </li>
1388 <li> Click on "Repeat Task" and fill in the details of how often
1390 For example, you can set it to run "every 15 minutes", then
1391 click on "until" and set that time to 11:30pm.
1396 <div class="top"><a href="#" target="_top">↑ top</a></div>
1399 <a name="appendixC"></a>
1400 <h2>Appendix C: Displaying Upcoming Events on Your Site</h2>
1403 If you would like to list upcoming events somewhere on a page on your site
1404 (someplace other than the WebCalendar pages),
1405 you can use the <tt>upcoming.php</tt> page to do this.
1406 This page is intended to be included in other pages using the
1407 <tt>iframe</tt> tag.
1409 <p>You may need to modify some of the variables near the top of
1410 <tt>upcoming.php</tt> with a text editor:
1412 <table border="0" style="margin-left: 20px; margin-right: 20px;">
1414 <tr><td valign="top">$public_must_be_enabled</td>
1416 Specifies if Public Access must be enabled in System Settings
1417 for this page to be viewed.
1418 <br/>Default setting: false
1421 <tr><td valign="top">$display_link</td>
1423 Specifies if events should have a link to the URL
1424 within WebCalendar to view the event.
1425 <br/>Default setting: true
1428 <tr><td valign="top">$link_target</td>
1430 Specifies the name of the window that be used for
1432 <br/>Default setting: _top
1435 <tr><td valign="top">$numDays</td>
1437 Specifies how many days of events should be listed.
1438 <br/>Can override this by passing "num" in within the URL
1439 with "upcoming.php?num=60"
1440 <br/>Default setting: 30
1443 <tr><td valign="top">$maxEvents</td>
1445 Specifies the maximum number of events to list.
1446 <br/>Default setting: 10
1449 <tr><td valign="top">$username</td>
1451 The login of the calendar to display upcoming events for.
1452 If you want to see upcoming events for user login "joe",
1453 then you would change this to "joe".
1454 <br/>Default setting: __public__ (The public calendar)
1457 <tr><td valign="top">$allow_user_override</td>
1459 Specifies whether the calendar user can be specified in the URL
1460 (in which case the $username setting will be ignored) using
1461 a URL like "upcoming.php?user=joe".
1462 <br/>Default setting: true
1465 <tr><td valign="top">$load_layers</td>
1467 Specifies if the calendar user's layers should also be
1468 included in the upcoming events.
1469 <br/>Note: Layers must be enabled in the user's preferences.
1470 <br/>Default setting: true
1473 <tr><td valign="top">$cat_id</td>
1475 Specifies a category id to filter events on.
1476 <br/>Note: Categories must be enabled in System Settings.
1477 <br/>Default setting: (empty)
1482 <p>Below is an example of how you would include <tt>upcoming.php</tt>
1483 in a simple HTML page.</p>
1485 <html><head><title>ACME Home Page</title></head>
1487 <h1>Welcome to the ACME Home Page</h1>
1488 <h2>News</h2><
1489 p>No news....</p>
1490 <h2>Upcoming Events</h2>
1491 <iframe src="upcoming.php" width="400" height="400" name="califrame" />
1497 <p><span class="tip">TIP</span>
1498 The <a href="http://www.w3schools.com/tags/tag_iframe.asp"
1499 target="_blank">W3 Schools</a> site provides documentation
1500 about the different options that you can use
1501 with the <tt>iframe</tt> tag.
1505 <div class="top"><a href="#" target="_top">↑ top</a></div>
1508 <a name="appendixD"></a>
1509 <h2>Appendix D: How To Configure For LDAP</h2>
1511 <p>Configuring WebCalendar to use an existing LDAP directory is fairly
1512 simple. It is know to work with OpenLDAP and Novell Edirectory and
1513 should work with other systems as well. <span class="note">Note:</span>
1514 If you use LDAP, the group functionailty of WebCalendar does not yet work.
1517 <p>To configure WebCalendar to use LDAP, do the following:</p>
1519 <li>Configure <tt>settings.php</tt></li>
1520 <li>Configure <tt>includes/user-ldap.php</tt></li>
1523 <p>The first step is to set WebCalendar to use LDAP authentication in
1524 <tt>settings.php</tt>. Instructions on to do this can be found in the
1525 <a href="#appsetup">Application Setup</a> section above.
1526 In summary, the following should be set:<br />
1527 <tt>use_http_auth = false</tt><br />
1528 <tt>user_inc = user-ldap.php</tt><br />
1531 <p>The next step is a little more work and involves editing the
1532 <tt>includes/user-ldap.php</tt> file with a text editor. You will have
1533 to set several configuration variables. If you don't know what to set
1534 the variables to, consult your LDAP system administrator. Documentation
1535 exists for all variables in the file. Finally, users have gotten LDAP
1536 working with OpenLDAP and Novell Edirectory by just changing the
1539 <table border="0" style="margin-left: 20px; margin-right: 20px;">
1541 <tr><td valign="top">$ldap_server</td>
1543 FQDN or IP address of the LDAP server (or localhost).
1544 <br />ex. 'ldapserver.company.com'
1547 <tr><td valign="top">$ldap_base_dn</td>
1549 Specifies the base DN used to search for users
1550 <br />ex. 'ou=people,dc=company,dc=com' or 'o=context,ou=subcontext'
1553 <tr><td valign="top">$ldap_admin_group_name</td>
1555 Specifies a group (complete DN) with admin rights for WebCalendar
1556 <br />You might have to create one in LDAP
1557 <br />ex. 'cn=it,ou=group,dc=company,dc=com'
1562 <h3>Using SSL with LDAP</h3>
1563 <p>If the LDAP server will accept connections over SSL, simply add 'ldaps://'
1564 to the beginning of <tt>$ldap_server</tt>. <br />Example: ldaps://ldapserver.company.com
1567 <h3>Using TLS with LDAP</h3>
1568 <p>If the LDAP server is set up to use TLS, just set <tt>$ldap_start_tls = true</tt>.
1572 <div class="top"><a href="#" target="_top">↑ top</a></div>
1575 <a href="http://validator.w3.org/check?uri=referer"><img
1576 src="http://www.w3.org/Icons/valid-xhtml10"
1577 alt="Valid XHTML 1.0!" class="valid" /></a>