Jax Calendar v1.25
Dokumentation

 

O. Allgemeine Informationen

Programm und Autor
Danksagungen

I. Einleitung

Was ist Jax Calendar? - Wozu braucht man es?
Leistungsmerkmale (Features)
Systemvoraussetzungen
Lizenz

II. Installation

ohne MySQL-Unterstützung
mit MySQL-Unterstützung

III. Anwendung

Umgang mit dem Kalendarverwaltungssystem
Anwendung / Einbindung des Skriptes

IV. Häufig gestellte Fragen (FAQs)

Wie kann man das Kalender-Steuerelement direkt in seine eigene Webseite einbauen?
Wie kann man die Farben und Schriftarten anpassen?
Wie kann man mehrere Kalendarien gleichzeitig betreiben?
Wie ändert man die Datei-Zugriffsrechte auf dem Webserver?
Wieviele Einträge kann Jax Calendar speichern?
Wo erhalte ich Informationen über Updates und Änderungen?

V. Bekannte Fehler und Probleme (Troubleshooting)

Probleme mit MySQL

VI. Liste der Änderungen (ChangeLog)

v1.25, v1.2

 

O. Allgemeine Informationen

 

Programm und Autor

Projekt:   Jax Calendar (Online Event-Kalendar)
     
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) ]

Dieses Programm ist Freeware im Sinne der "General Public License" Version 2 oder neuer! Den genauen Wortlaut dieser Lizenz finden Sie in der beiliegenden Datei gpl.txt, bzw. auf der Website der Free Software Foundation unter http://www.fsf.org/copyleft/gpl.html

Bitte beachten Sie, dass ich keinerlei Haftung für Schäden übernehme, die im Zusammenhang mit der Nutzung dieser Software auftreten...

 

Danksagungen

Ich möchte allen Leuten ein großes Dankeschön aussprechen, die dieses und viele andere Open Source Projekte durch ihre Hinweise, Übersetzungen, liebevollen Anpassungen und Links auf ihren Webseiten unterstützen...

Mein persönliches Dankeschön geht vor allem an:

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. Einleitung

 

Was ist Jax Calendar? - Wozu braucht man es?

Jax Calendar ist ein Online-Event-Kalendersystem, das Sie ohne Programmiererfahrungen in Ihre Homepage einbauen und beliebig anpassen können.

In einem Online-Event-Kalender können Sie die Termine und Fristen bevorstehender Ereignisse eintragen. Je nach aktuellem Datum bekommen Ihre Besucher eine entsprechend zusammengefasste Liste der bevorstehenden Ereignisse präsentiert.

Eine Demoversion von Jax Calendar finden Sie unter: http://www.jtr.de/scripting/php/calendar/calendar/jax_calendar.php

 

Leistungsmerkmale (Features)

Jax Calendar bietet Ihnen neben den typischen Funktionen eines WWW-Kalendars viele zusätzliche Leistungsmerkmale. Besonders hervorzuheben ist an dieser Stelle die sehr flexible Unterstützung verschiedener Datenquellen, die es Ihnen ermöglicht, das Kalendarsystem sowohl mit einfachen CSV-Textdateien als auch mit einem MySQL-Datenbanksystem zu betreiben.

Nachfolgend finden Sie eine Übersicht der wesentlichen Leistungsmerkmale von Jax Calendar:

 

Systemvoraussetzungen

Jax Calendar wurde in PHP 4 geschrieben, einer serverseitigen Programmiersprache, mit der man dynamisch erzeugte Webseiten erstellen kann! (Fragen Sie gegebenenfalls Ihren Web-Provider nach PHP-Unterstützung!)

Jax Calendar ist in der Lage, die Daten sowohl in einfachen Textdateien, alsauch in einem MySQL-Datenbanksystem abzulegen, dadurch läuft es auch ohne MySQL-Datenbank-Anbindung!

 

Lizenz

Jax Calendar und seine Einzel-Bestandteile unterliegen den Bedingungen der GPL - General Public License in der Version 2 oder neuer! Den genauen Wortlaut dieser Lizenz finden Sie in der beiliegenden Datei gpl.txt, bzw. auf der Website der Free Software Foundation unter http://www.fsf.org/copyleft/gpl.html

Diese Lizenz erlaubt es Ihnen vor allem, die Software frei weiterzugeben und natürlich weiterzuentwickeln. Desweiteren sind Sie hiermit verpflichtet, einen Copyrighthinweis, bzw. einen Link zum Originalskript (http://www.jtr.de/scripting/php/calendar) beizubehalten!

Jax Calendar enthält ausserdem das Modul htmlArea, das einer BSD-ähnlichen Lizenz unterliegt, die sie evtl. gesondert berücksichtigen müssen.

 

II. Installation

 

Installation ohne MySQL-Unterstützung

Jax Calendar wurde in PHP 4 geschrieben, einer serverseitigen Programmiersprache, mit der man dynamisch erzeugte Webseiten erstellen kann! (Fragen Sie gegebenenfalls Ihren Web-Provider nach PHP-Unterstützung!)

Jax Calendar ist in der Lage, die Daten in einfachen Textdateien, sowie in einem MySQL-Datenbanksystem abzulegen, es läuft auch ohne MySQL-Datenbank-Anbindung!


Verfügen Sie für Ihre Website bereits über PHP-Unterstützung, dann tun Sie bitte folgendes:

  1. Laden Sie sich die aktuellste Version von Jax Calendar herunter http:/www.jtr.de/scripting/php/calendar/ !

  2. Entpacken Sie das .zip-Archiv! (inklusive aller Unterverzeichnisse!)

  3. Öffnen Sie die Datei globals.inc.php (im Verzeichnis calendar) mit einem Texteditor und passen Sie die Variablen Ihren Bedürfnissen an!

    Sie können diese Einstellungen auch später über das beiliegende Verwaltungsprogramm auf Ihrer Website durchführen. Das Admin-Programm heißt calendar.admin.php und befindet sich standardmäßig im Verzeichnis admin (relativ zum Pfad Ihres Kalendarskripts).

    Wenn Sie Jax Calendar also beispielsweise im Hauptverzeichnis Ihrer Website unterbringen (/) finden Sie das Verwaltungsprogramm unter

    http://www.ihredomain.de/calendar/admin/calendar.admin.php


  4. Laden Sie alle Verzeichnisse und Dateien von Jax Calendar auf Ihre Website!

    Nachdem Sie das Skript auf Ihren Webspace hochgeladen haben, stellen Sie mit Ihrem FTP-Client die Zugriffsrechte für die .csv-Dateien (standardmäßig "mycalendar.csv" und "myevents.csv") so ein, dass das Skript vollen Schreibzugriff darauf hat! Sonst meldet Ihnen das Skript beim Start den Fehler "Error: Couldn't open 'Calendar' ..."

  5. Wenn Sie alle Dateien hochgeladen haben, und die Zugriffsrechte korrekt gesetzt haben, können Sie das Skript auf Ihrer Website verlinken. z.b.

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

    Der Parameter language ... gibt dem Skript explizit vor, welche Sprache verwendet werden soll. (Für diese muss natürlich eine entsprechende Sprachvorlagedatei im Verzeichnis language existieren, ansonsten wird automatisch die Sprache gewählt, die über das Konfigurationsprogramm eingestellt wurde!)


  6. Wichtiger Hinweis zur Sicherheit:
    Jax Calendar besitzt keinen eigenen Passwort-Schutz! Stellen Sie also bitte über das Konfigurationssystem Ihres Webspace sicher, dass niemand ausser Ihnen Zugriff auf das Verzeichnis mit dem Administrationsskript (admin/calendar.admin.php) hat!

 

Installation mit MySQL-Unterstützung

Jax Calendar wurde so entworfen, dass es sowohl einfache Textdateien, als auch MySQL-Datenbanktabellen zur Speicherung der Einträge verwenden kann. Der Betrieb mit einem MySQL-Datenbanksystem ist bei großen Kalendarien mit mehreren tausend Einträgen in der Regel schneller als die CSV-Variante...

Verfügen Sie über MySQL-Unterstützung dann tun Sie bitte folgendes:

  1. Installieren Sie Jax Calendar (wie bei "Installation ohne MySQL")...

  2. Führen Sie das Administrationsprogramm auf der Website aus!
    Das Programm finden Sie im Verzeichnis admin (relativ zum Pfad Ihres Kalenderskriptes).

  3. Setzen Sie unter [Einstellungen ändern] bzw. in der Datei globals.inc.php die Datenquelle auf "MySQL-Datenbank" und tragen Sie die Zugriffsdaten (Server, Datenbankname, Benutzerkennung und Passwort) für Ihren MySQL-Server ein !

  4. Starten Sie phpMyAdmin (oder ein Monitorprogramm für Ihren MySQL-Server) und legen Sie die folgenden Tabellenstrukturen an:
    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. Wichtiger Hinweis zur Sicherheit:
    Jax Calendar besitzt keinen eigenen Passwort-Schutz! Stellen Sie also bitte über das Konfigurationssystem Ihres Webspace sicher, dass niemand ausser Ihnen Zugriff auf das Verzeichnis mit dem Administrationsskript (admin/calendar.admin.php) hat!

 

III. Anwendung

 

Umgang mit dem Kalendarverwaltungssystem

Beim Anlegen von neuen Terminen im Kalendar-Verwaltungssystem wird zwischen zwei verschiedenen Arten von Zeiträumen unterschieden:

1. Ereigniszeitraum

Der Ereigniszeitraum gibt an, von wann bis wann ein Ereignis stattfindet. Diese Information ist nur Inhaltlich von Bedeutung, beeinflusst den Zeitpunkt der Anzeige der Termine nicht!

Wird bei einem Termin das Häkchen bei "ganztägig" gesetzt, so wird für den Termin später nur das Datum, ohne Uhrzeit in der Eventliste des Kalendars angezeigt. Ist der Startzeitpunkt gleich dem Endzeitpunkt, so wird nur der Startzeitpunkt angezeigt.

2. Erinnerungszeitraum

Der Erinnerungszeitraum gibt an, von wann bis wann der Termin in der Eventliste angezeigt werden soll! Dieser dürfte in der Mehrzahl der Fälle nicht identisch mit dem Ereigniszeitraum sein.

Beispiel:

Sie möchten einen Termin für die Internationale Grüne Woche, die vom 17. bis 26. Januar 2003 in Berlin stattfindet in Ihren Kalendar eintragen, und möchten, dass dieser Termin mind. 3 Monate vor der Messe angezeigt wird.

In diesem Fall tragen Sie als Ereigniszeitraum die Zeit vom 17.1.2003 -26.1.2003 ein, machen ein Häkchen bei ganztägig und tragen als Erinnerungszeitraum die Zeit vom 17.10.2002-26.1.2003 ein...

 

Das Feld Status ist im Moment übrigens noch nicht vollständig implementiert. Bisher haben Sie die Möglichkeit dort Buchstabenkürzel einzugeben, um Ihre Termine zu kennzeichnen, bzw. hervorzuheben. Für die nächste Version ist die "Bestückung" mit benutzerdefinierten Icons geplant. Ihre bisherigen Buchstaben-Einträge werden dadurch natürlich nicht beeinflusst.

 

Anwendung / Einbindung des Skriptes

Nachdem Sie den Kalendar wie in Kapitel II beschrieben installiert haben, können Sie Ihre Webseiten mit dem Skript verlinken. Dabei haben Sie die Möglichkeit, über die Parameter nach dem Fragezeichen Einfluss auf die Ausgaben des Skript zu nehmen.

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

Über die Parameter Y und m können Sie festlegen für welches Jahr und für welchen Monat der Kalendar angezeigt werden soll.

cal_id gibt den verwendeten Kalendar an (falls Sie mehrere Kalendarien über das Skript verwalten -> siehe FAQ: Verwaltung mehrerer Kalendarien)

language gibt die Sprache an, in der die Wochentage und Meldungen des Kalendars angezeigt werden sollen. Wichtig ist, dass für die in der URL angegebene Sprache auch eine entsprechende Sprachvorlage im Verzeichnis language existiert! Andernfalls wird die Sprache gewählt, die in globals.inc.php festgelegt wurde.

 

 

IV. Häufig gestellte Fragen (FAQs)

 

Wie kann man das Kalender-Steuerelement direkt in seine Homepage einbauen?

Jax Calendar besteht aus drei Modulen. Das Modul main.inc.php ist obligatorisch und führt alle nötigen Vorberechnungen und Initialisierungen für den ordnungsgemäßgen Betrieb durch. Die Module calendar.inc.php und eventlist.inc.php stellen jeweils die beiden Steuerelemente für den Kalendar und die Eventliste bereit. Wie Sie die Module am einfachsten einbinden, ist in der Datei jax_calendar.php anschaulich demonstriert.

Falls Sie die Module direkt in Ihre eigenen Webseiten einbinden möchten, vergessen Sie bitte nicht den Urheberrechtsvermerk, bzw. einen Link zur Download-Seite von Jax Calendar mitzuübernehmen!

 

Wie kann man die Farben und Schriftarten anpassen?

Dafür stehen im Verzeichnis styles verschiedene vordefinierte Stylesheets zur Verfügung, die man nach Belieben mit einem Texteditor verändern kann.

 

Wie kann man mehrere Kalendare gleichzeitig betreiben?

Möchten Sie dem Skript mehr als einen Kalendar betreiben, können Sie den entsprechenden Kalendar mit dem Parameter cal_id auswählen. z.B:

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

Aus Sicherheitsgründen kann der Dateiname des Kalendars nicht direkt mit der URL weitergegeben werden. Die Zuordnung zwischen Kalender-ID und Kalendername müssen Sie zur Zeit noch von Hand in der Datei globals.inc.php vornehmen.

...

// 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";

...

Im Beispiel wird ein weiterer Kalendar mit dem selben Skript benutzt:

Ein Kalendar auf Basis der MySQL-Tabelle secondbook ist über die URL

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

erreichbar Äquivalent wird mit der URL

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

eine dritte Kalendardatei zur Speicherung verwendet, usw...

Sie können für jeden einzelnen Kalendar die Datenquelle (mysql/csvfile) frei wählen!

 

Wie ändert man die Datei-Zugriffsrechte auf dem Webserver?

Wenn Ihr Webserver unter Unix arbeitet (Apache) müssen Sie den Unix-Befehl chmod zum Ändern der Dateirechte verwenden. (Wie Sie das bequem von Ihrem FTP-Client aus machen können, ist weiter unten beschrieben)

Die Syntax von chmod lautet:

chmod rwxrwxrwx filename

r = lesen
w = schreiben
x = ausführen

Der Befehl erwartet drei 3er-Tupel welche die Zugriffsrechte für die "Gruppen" angeben: [rwx][rwx][rwx]

Die Gruppen von rechts nach links:

Alle Benutzer
Alle Benutzer der gleichen Gruppe wie Besitzer
Nur der Besitzer

Die Tupel kann man sich auch in Binärdarstellung vorstellen:

chmod [rwx][rwx][rwx]

wäre äquivalent mit

chmod [111][111][111]

bzw. in dezimalschreibweise mit

chmod [7][7][7]

und da haben wir auch schon den fertigen chmod Befehl um "allen" Zugriff auf die Dateien zu geben:

chmod 777 calendar.csv

(Die benötigten Dateirechte hängen von der Webserver-Konfiguration ab. Wenn Sie misstrauisch sind, und dem Skript nicht die vollen Rechte (777) geben wollen, erhöhen Sie die Rechte langsam, bis das Skript fehlerfrei läuft!)

Die meisten FTP-Clients, wie z.B. WS-FTP unterstüzen den chmod-Befehl bequem von der Oberfläche aus. Man muss bei WS-FTP z.B. nur mit der rechten Maustaste auf eine Datei im Ftp-Fenster klicken, dann auf chmod, dann die zu setzenden Attribute usw...

 

Wie viele Einträge kann Jax Calendar speichern?

Zur Zeit teste ich das Skript auf einer meiner Websiten mit ca. 200 Terminen im CSV-Format. Theoretisch müsste das Skript in Abhängigkeit von der verfügbaren Rechenzeit/-leistung ihres Webservers und der Datenquelle problemlos mehrere 1000 Einträge verwalten können. Für größere Kalendare bietet sich die Verwendung von MySQL als Datenquelle an...

 

Wo erhalte ich Informationen über Updates und Änderungen?

  1. Auf der Website (http://www.jtr.de/scripting/php/calendar) natürlich! ;-)

  2. Im Admin-Skript gibt es einen Link "Auf Updates überprüfen". Links neben dem Link ist ein kleiner grüner Punkt. Blinkt dieser grün-gelb, gibt es ein neues Update. Blinkt dieser rot-gelb, gibt es ein sicherheitsrelevantes Update, dessen Installation wichtig ist!

  3. Tragen Sie sich in den "JtR News"-Newsletter ein! (http://www.jtr.de/scripting/php/newsletter/newsletter)

 

V. Bekannte Fehler und Probleme

 

Probleme mit MySQL

Jax Calendar speichert nur einen Eintrag, bzw. zeigt immer den gleichen Eintrag an!

Sie haben wahrscheinlich nicht die Beispieltabellen (im admin-Verzeichnis) verwendet, und vergessen das Feld "id" (Pflichtfeld!!) anzulegen

 

VI. Liste der Änderungen (Change Log)

 

Änderungen in Version 1.25:

Änderungen in Version 1.2:

 


Sollten Sie Fehler finden, oder haben Sie Fragen oder Verbesserungsvorschläge, zögern Sie bitte nicht, und wenden Sie sich einfach direkt an mich!


Berlin, 20.04.2003 - Jack (tR)