Jax Calendar v1.25
Manual

 

O. General Information

Program and Author
Credits

I. Introduction

What's Jax Calendar? - What do I need it for?
Features
System requirements
License

II. Installation

without mySQL support
with mySQL support

III. Application

Using the calendar admin system
How to link the script (parameters)

IV. Frequently Asked Questions (FAQs)

How to include the calendar control directly to my website?
How to change the colors and fonts?
How to use multiple calendars?
How to change file access permissions on the webserver?
How many entries Jax Calendar can handle?
Where to get informations about Updates and Changes

V. Known Bugs and Problems (Troubleshooting)

Problems with MySQL

VI. List of Changes (ChangeLog)

v1.25, v1.2

 

O. General Information

 

Program and Author

Projekt:   Jax Calendar (Online Event Calendar)
     
Version:   1.25
     
Interpreter:      PHP 4.02+
     
Code:   Andreas John
     
Design:   Andreas John
     
Homepage:   www.jtr.de/scripting/php/calendar/
     
Lizenz:  

Copyright (C) 2002-2003, Andreas John [ Jack (tR) ]

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. A copy of this license you can find in the added text file gpl.txt or on the website of the Free Software Foundation under: http://www.fsf.org/copyleft/gpl.html

Please note, that I can give NO WARRANTY FOR DAMAGES CAUSED BY DIRECT OR INDIRECT USE OF THE PROGRAM...

 

Credits

I want to say a very big Thank You to all people who support this and many other Open Source projects by their hints, translations, affectionate adaptions and links on their websites...

My personal credits go to:

Gerard Farràs Ballabriga http://www.ctfc.es
Helge Larsen
Jarno Ristaniemi http://www.vihrealiitto.fi/lappi
Marc Gavage http://portix.be
Martin Sondermann http://www.kunstphotografie.de
Mitsuhiro Yoshida http://mitstek.com/
Peter Kramer http://www.action-sport.de
Sigrid Henning-Bellwinkel http://bellwinkel.de
Wojciech Dorosz

InteractiveTools.com (bzw. die Entwickler von HTMLarea)

 

I. Introduction

 

What is Jax Calendar? - What do I need it for?

Jax Calendar is an online event calendar system. You can easily add it to your homepage - without any programming skills.

An online event calendar enables you to add dates and events to your homepage. Dependent on current date your visitors get a special summary of current/next events.

 

Features

Jax Calendar comes along with typical features of an online calendar. Additionally it brings some special features. Particularly worth mentioning is the very flexible support of multiple data sources. This makes it possible to use the calendar system both - with a simple text file and a mySQL database system.

Following you find a summary of all important features of Jax Calendar:

 

System Requirements

Jax Calendar was written in PHP 4, a server-side programming language that produces dynamical generated web pages! (If unsure, ask your web space provider for PHP support!)

Jax Calendar is able to save data into both, simple text files and into a mySQL-data base system - that means Jax Calendar also works without mySQL-database-connection!

 

License

Jax Calendar and its components are published under the conditions of the GPL - General Public License in der Version 2 or later! The complete license text you find in the file gpl.txt (part of the packet), respectively on the website of Free Software Foundation under http://www.fsf.org/copyleft/gpl.html

This license allows you to use and copy this software freely and to develop improvements. Furthermore you are bound not to touch the copyright notes resp. to set a link to the original script (http://www.jtr.de/scripting/php/calendar)!

Jax Calendar contains the module htmlArea which is published under a BSD-like license. (consider that separately!)

 

II. Installation

 

Installation without mySQL support

Jax Calendar was written in PHP 4, a server-side programming language that produces dynamical generated web pages! (If unsure, ask your web space provider for PHP support!)

Jax Calendar is able to save data into both simple text files (csv files) and into a mySQL-data base system - that means Jax Calendar also works without mySQL-database-connection!


If you already have PHP support please do the following:

  1. Download latest version of Jax Calendar from
    http:/www.jtr.de/scripting/php/calendar/ !

  2. Unpack the .zip-archive! (including all sub directories!)

  3. Open file globals.inc.php (in directory calendar) using a texteditor. Fit the configuration variables to your needs!

    You can also do this settings later directly on your website (using the administration program). The administration program calendar.admin.php is in directory admin (relatively to the path of your calendar script)

    For example: if you put Jax Calendar in the main directory of your website (/) you can access the admin script calling

    http://www.yourdomain.tld/calendar/admin/calendar.admin.php

  4. Upload all directories and files of Jax Calendar onto your website!

    After uploading the script to your webspace make sure by setting file access permissions that the script has full write access to the to the .csv-files (mycalendar.csv and myevents.csv) otherwise the script produces errors like "Error: Couldn't open 'Calendar' ..."

  5. If you have uploaded script and set write permissions you can link it onto your website, e.g.:

    http://www.ihredomain.de/calendar/jax_calendar.php?language=French

    The parameter language ... tells the script which language to use. (this of course implies that there is a language template in language directory, otherwise the default language set in globals.inc.php will be choosed!)

  6. Important Security Note:
    Jax Calendar has no active password protection! So you have to make sure that nobody but you has access to the admin scripts (admin/calendar.admin.php) directory. This you usually do by setting directory protection using your webspace configuration frontend!

 

Installation with mySQL support

Jax Calendar was designed to be able to save data to both - simple text files and mySQL database tables. Running a big calendar with many thousands of entries mySQL is expected to give you a better performance...

If you have mySQL support please do the following:

  1. Install Jax Calendar (see "Installation without mySQL")...

  2. Run the administration frontend on your website! The program you find in directory admin (in relation to the path of your calendar script).

  3. Set [Change Settings] data source to "mySQL database" and input the database login information (server, database name, user id and password)!

  4. Start phpMyAdmin (or your favourite mySQL monitor tool) and create the following table structures:
    CREATE TABLE mycalendar (
    id int(11) NOT NULL auto_increment,
    event_start varchar(30) default NULL,
    event_end varchar(30) default NULL,
    x24 int(11) NOT NULL default '0',
    reminder_start varchar(30) default NULL,
    reminder_end varchar(30) default NULL,
    status varchar(30) NOT NULL default '',
    event_title varchar(255) NOT NULL default '',
    event_key varchar(32) NOT NULL default '',
    PRIMARY KEY (id)
    ) TYPE=MyISAM; CREATE TABLE myevents (
    id int(11) NOT NULL auto_increment,
    event_key varchar(32) NOT NULL default '',
    event_description text NOT NULL,
    PRIMARY KEY (id)
    ) TYPE=MyISAM;
  5. Important Security Note:
    Jax Calendar has no active password protection! So you have to make sure that nobody but you has access to the admin scripts (admin/calendar.admin.php) directory. This you usually do by setting directory protection using your webspace configuration frontend!

 

III. Application

 

Using the calendar admin system

Creating new Dates in calendar admin system you have to distinguish two seperate time spans:

1. Event Time

The event time spans time from when to when a event will happen. This information is only of relevant for the visitors, but it does not influence the time when the event is displayed in calendar!

If you set click on "whole day", later in event list the calendar only shows the date (without time) of the event. If event time start and event time end are equal the calendar only shows the start time.

2. Reminder Time

The reminder time spans time from when to when an event will be displayed in calendar! This most often is not equal with event time.

Expample:

If you want to enter the date for the event "Internationale Grüne Woche", from 17 to 26 January 2003 in Berlin. If you want the event announced at least 3 month before type in event time 17.1.2003 to 26.1.2003, click on "whole day" and enter 17.10.2002 to 26.1.2003 for reminder time...

 

The field State is not completely implemented at the moment. At the moment there you can enter letters to emphasize events. Next release comes with personal defined icons for that field. This of course will not touch the letter-entries you make today...

 

How to link the script (parameters)

After you have installed Jax Calendar as described in Chapter "Installation" you can set links to the script from your website. You can influence outputs of the script manipulating the parameters behind the "?"...

http://www.meinedomain.tld/calendar/jax_calendar.php?Y=2003&m=4&d=17&cal_id=0&language=english

Parameter Y and m define what year and month is shown in the calendar.

cal_id specifies the calendar (if you run multiple calendars with the script -> see FAQ: How to use multiple calendars)

language sets the language of messages and days of the week. Its important to make sure that a coressponding language template exists (in directory language). Otherwise the script sets the language that is defined in globals.inc.php.

 

 

IV. Frequently Asked Questions (FAQs)

 

How to include the calendar control directly to my website?

Jax Calendar consists of three modules. The modul main.inc.php is obligatory. It does all important initialisations and calculations. The modules calendar.inc.php and eventlist.inc.php build the controls for Calendar and Eventlist. To see how to include the modules have a look at jax_calendar.php.

If you include the moduls directly into your pages please don't forget to set a copyright note or link to the download site of Jax Calendar!

 

How to change colors and fonts?

To change outer appearance there are some predefined CSS stylesheets in directory styles. You can change them using a simple texteditor.

 

How to use multiple calendars?

If you want to run more than one Calendar with the same script you can select the corresponding calendar by parameter cal_id. e.g:

http://../jax_calendar.php?cal_id=1

For security reasons the filename of the calendar is not forwarded directly by URL.
The allocation between calendar ID and calendar name you have to set manually in globals.inc.php. e.g:

...

// Title and Data Source
$calendars[0]->title = "Jax Calendar";
$calendars[0]->data_source = "csvfile";

$calendars[1]->title = "Ein zweiter Kalendar";
$calendars[1]->data_source = "mysql";

$calendars[0]->css = "styles/default.css";
$calendars[1]->css = "styles/ice.css";

$calendars[0]->calendar_file = "mycalendar.csv";
$calendars[0]->event_file = "myevents.csv";

$calendars[1]->calendar_file = "mycalendar";
$calendars[1]->event_file = "myevents";

...

The example shows how to use a second calendar with the same script:

http://../jax_calendar.php?calendar_id=1

access a second calendar based on a mySQL table.
Equivalent the URL

http://../jax_calendar.php?calendar_id=2

accesses a third calendar file and so on...

You can freely choose the data source (mysql/csvfile) for any single calendar!

 

How to change file access permissions on the webserver?

If your webserver runs on Unix (Apache) you have to use the Unix command chmod to change the file access permissions. (How to do this conveniently using your FTP client is described below)

Syntax of chmod is:

chmod rwxrwxrwx filename

r = read
w = write
x = execute

The command expects three 3-digit tupels representing the access permissions for the single "groups" : [rwx][rwx][rwx]

The groups: (from right to left)

all users
all users in same group as owner
owner only

in binary notation:

chmod [rwx][rwx][rwx]

is equivalent to

chmod [111][111][111]

resp. in hex notation with

chmod [7][7][7]

thats all - here you have the chmod command to allow "all" access to files:

chmod 777 calendar.csv

(the required access permissions depend on webservers configuration. If you are suspiciously and do not want to give script all access (777), try to increase rights step by step until the script works!)

Most FTP clients, as WS-FTP support chmod-command conveniently from their user interface. Using WS-FTP you only have to click with right mouse button on a file (in remote window) and then you have to klick on chmod and so on...

 

How many entries Jax Calendar can handle?

Currently I am running the Calendar on one of my websites with 200 dates in CSV mode. Theoretically the script is able to handle several 1000 entries (depending on your webservers capacity and data source). For running larger calendars mySQL is recommended...

 

Where to get informationen about updates and changes

  1. On my website (http://www.jtr.de/scripting/php/calendar) ;-)

  2. In Admin Script there is a link "Check for Updates". To the left of it there is a small green spot. If it blinks gree-yellow there is a new update. If it blinks red yellow there is a security relevant update that you should install!

  3. Sign into "JtR News"-Newsletter! (http://www.jtr.de/scripting/php/newsletter/newsletter)

 

V. Known Bugs and Problems

 

Problems with mySQL

Jax Calendar saves only one entry, resp. it always shows the same entry!

You probably have not set up the database using the sql dump (in admin-directory) and forgot to create the field "id" (very important!!)

 

VI. List of Changes (Change Log)

 

Changes in Version 1.25:

Changes in Version 1.2:

 


If you have found any errors or have questions or suggestions for improvement then please don't hesitate to contact me directly!


Berlin, 20 April 2003 - Jack (tR)