Jax Calendar v1.26
Dokumentaatio

 

O. Yleistä

Ohjelma ja tekijä
Kiitokset

I. Esittely

Mikä on Jax Kalenteri? - mihin sitä tarvitaan?
Ominaisuudet
Vaatimukset
Lisenssi

II. Asentaminen

ilman MySQL-tukea
MySQL-tuen kanssa

III. Ohjelma

Ylläpitojärjestelmä
Skriptin toimintaperiaate

IV. Usein kysytyt kysymykset (FAQ)

Kuinka voin tulostaa kalenterin osissa?
Kuinka kalenterin ulkoasua voi muuttaa?
Kuinka voin käyttää useaa kalenteria samaan aikaan?
Kuinka tiedostojen ja hakemistojen oikeuksia muutetaan?
Kuinka monta tapahtumaa Jax Kalenteriin mahtuu?
Mistä saan tiedon uusimmista päivityksistä?

V. Virheet ja ongelmat (Troubleshooting)

Ongelma MySQL:n kanssa

VI. Muutoshistoria (ChangeLog)

v1.26 ,v1.25, v1.2

 

O. Ohjelma ja tekijä

 

Ohjelma ja tekijä

Projekti:   Jax Calendar (Online Event-Kalendar)
     
Versio:   1.26
     
Tulkki:      PHP 4.02+
     
Koodi:
  Andreas John
     
Ulkoasu:   Andreas John
     
Kotisivut:   www.jtr.de/scripting/php/calendar/
     
Lisenssi:  

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

Tämä ohjelma on Freeware ja GPL 2:n (General Public Liecense) alainen. Löydät GPL-lisenssin ohjelmapaketista nimellä gpl.txt, tai voit tutustua siihen osoitteessa http://www.turre.com/licenses/gpl_fi.php

Huom! Tekijä ei ota vastuuta mistään tämän ohjelman käyttäjälle aiheuttamasta rahallisesta, laitteistollisesta tai muusta vahingosta.

 

Kiitokset

Haluan antaa suuret kiitokset tästä ja monesta muusta avoimen koodin projektista. Moni on auttanut minua niin ohjelmoinnin, kääntämisen kuin monen muun ongelman osalta. 

Henkilökohtainen kiitokseni heille kaikille:

Bela-Andreas Bargel http://www.fuldas-tauchertreff.de
Gerard Farràs Ballabriga http://www.ctfc.es
Helge Larsen
Jarno Ristaniemi http://www.vihrealiitto.fi/lappi
Klaus-Peter Lexow
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. Esittely

 

Mikä on Jax Kalenteri - mihin sitä tarvitaan?

Jax Kalenteri on on-line kalenterijärjestelmä, jonka voit asentaa kotisivuillesi ja käyttää ilman varsinaista ohjelmointitaitoja.

Voit tallentaa reaaliaikaisesti tulevien tapahtumien päiviä tai ajanjaksoja sekä kirjoittaa niille seliteosuuden. Näin sivuillasi kävijät saavat aina uusimman tiedon interaktiivisena tapahtumalistana. 

Voit tutustua suomenkieliseen demoversioon osoitteessa: http://www.jtr.de/scripting/php/calendar/calendar/jax_calendar.php?language=Finnish

 

Ominaisuudet

Jax Kalenteri tarjoaa erotuksena muihin yleisiin www-kalentereihin muutamia erityisominaisuuksia. Erityisen huomionarvoista on se, että kalenteri toimii tehokkaasti niin MySQL-tietokannan kuin myös tavallisen CVS-tekstitiedostojen avulla. Voit vapaasti valita kumpaa haluat käyttää.

Jax Kalenterin ominaisuusluettelo:

 

Vaatimukset

Jax Kalenteri on kirjoitettu palvelinpuolen PHP-nimisellä ohjelmointikielellä. Kalenteri kääntyy sellaisenaan PHP4-tulkilla.  (Kysy jo ennen ohjelmiston asentamista, onko käyttämälläsi palvelimella PHP tukea!)

Jax Kalenteri toimii niin tavallisilla tekstitiedostoilla kuin myös tehokkaammalla MySQL-tietokantaohjelmistolla. Jos kalenteriisi tulee paljon merkintöjä, kannattaa asentaa se toimimaan MySQL:n avulla.  Tällöin sinun tulee tarkistaa, tukeeko käyttämäsi palvelin MySQL-tietokantaa!

 

Lisenssi

Jax Kalenteri ja sen yksittäiset komponentit ovat GPL-lisenssin (General Public Liecense) version 2 alla. Löydät GPL-lisenssin ohjelmapaketista nimellä gpl.txt, tai voit tutustua siihen osoitteessa http://www.turre.com/licenses/gpl_fi.php.

Tämä lisenssi tarjoaa sinulle mahdollisuuden kehittää ohjelmistoa vapaasti. Kehittämissäsi tai muuntamissasi ohjelman versioissa on kuitenkin oltava näkyvillä alkuperäinen copyright-ilmoitus ja linkki alkuperäiseen skriptiin, osoitteeseen http://www.jtr.de/scripting/php/calendar.

Lisäksi Jax Kalenteri sisältää htmlArea:n moduulin, mikä on alistettu BSD lisenssin alle. Se tulee ymmärtää ohjelmistosta erillisenä.

 

II. Asentaminen

 

Asentaminen ilman MySQL-tukea

Jax Kalenteri on kirjoitettu palvelinpuolen ohjelmointikielen, PHP4:n avulla.

Jax Kalenteri toimii teksti- tai tietokantapohjaisena. 


Jos käyttämässäsi palvelimessa on jo PHP4-tuki, tee seuraavasti:

  1. Hae viimeisin Jax Kalenteri osoitteesta http:/www.jtr.de/scripting/php/calendar/

  2. Pura zip-paketti (myös kaikki alikansiot)

  3. Avaa globals.inc.php -tiedosto ja muokkaa se tarpeittesi mukaan.

    Voit tehdä tämän myös myöhemmin käyttäen hallinto-ohjelmistoa www-muodossa. Hallinto-ohjelma on nimeltään calendar.admin.php ja se sijaitsee admin -hakemistossa.

    Jos olet esimerkiksi purkanut kalenteripaketin suoraan palvelimesi juureen (/), löydät hallinto-ohjelmiston osoitteesta:

    http://www.minundomain.fi/calendar/admin/calendar.admin.php


  4. Siirrä kaikki tiedostot ja hakemistot palvelimesi kotihakemistoon.

    Tarkista tiedostojen siirtämisen jälkeen oikeudet kaikista .csv-tiedostoista  (oletuksena nimet "mycalendar.csv" ja  "myevents.csv"). Ohjelmaskriptillä tulee olla kirjoitusoikeus näihin tiedostoihin. Muuten saat seuraavan virheilmoituksen: "Error: Couldn't open 'Calendar' ..."

  5. Kun kaikki tiedostot on kopioitu palvelimelle ja tiedostojen oikeudet ovat kunnossa, voit ajaa kalenterin vaikkapa eri kielillä seuravaan kaavan mukaan:

    http://www.minundomain.fi/calendar/jax_calendar.php?language=Finnish

    Parametri language ... määrittää kalenterin kielen (kielitiedostojen täytyy luonnollisesti löytyä language-hakemistosta). Mikäli kieltä ei skriptille erikseen määritellä, se käyttää oletuskieltä, mikä on asetettu konfiguraatiotiedostossa.

  6. Tärkeä tietoturvahuomautus:
    Jax Kalenterissa ei ole omaa salasana-toimintoa, joten sinun tulee estää ulkopuolisten pääsy  admin-hakemiston ylläpitoskripteihin (admin/calendar.admin.php)!

     

Asentaminen MySQL-tuen kanssa

Jax Kalenteri on tuotettu niin, että se toimii niin puhtauden tekstitiedostojen kuin myös MySQL:n avulla. Kun tallennettuja merkintöjä on useita satoja tai tuhansia, kalenteri toimii huomattavasti tehokkaammin MySQL-tuella.

Jos sinulla on jo palvelimessasi MySQL, toimi seuraavasti:

  1. Asenna Jax Kalenteri (kts.  "asentaminen ilman MySQL-tukea").

  2. Aja ylläpito-ohjelma palvelimella. Ohjelma löytyy admin-hakemistosta.

  3. Muuta tarvittavat tiedot ohjelman avulla tai tee tarvittavat muutokset suoraan globals.inc.php -tiedostoon. Aseta MySQL:n tiedot oikein (palvelin, tietokannan nimi,  käyttäjätunnus ja salasana).

  4. Käynnistä phpMyAdmin (tai vastaava ohjelma MySQL-palvelimen hallintaan)  ja aseta seuraavalla koodilla oikea taulukkorakenne:
    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. Tärekä tietoturvahuomautus:
    Jax Kalenterissa ei ole omaa salasana-toimintoa, joten sinun tulee estää ulkopuolisten pääsy  admin-hakemiston ylläpitoskripteihin (admin/calendar.admin.php)!

 

III. Ohjelma

 

Ylläpitojärjestelmä

Lisättäessä uutta päivää kalenterin hallintajärjestelmässä, tulee huomioida kaksi asiaa:

1. Tapahtuman aikajakso

Tapahtuman aikajakso tarkoittaa aikoja, jolloin tapahtuma alkaa ja jolloin se loppuu. Näiden aikojen asettaminen ei ole ainoastaan kalenterin lukijalle tärkeää vaan se vaikuttaa myös ilmoitusjaksoon.  

Jos "tapahtuma kestää koko päivän" -kohta on valittuna, ilmoitusaika määritellään alempiin kenttiin. Jos ilmoittamisen aloitushetki on sama kuin lopetushetki, ainoastaan ilmoittamisen aloitushetki huomioidaan.

2. Muistutuksen ajanjakso

Muistutuksen ajanjakson määrittäminen vaikuttaa siihen, missä vaiheessa tapahtuma ilmestyy tapahtumalistaan. Tämä ei ole tietystikään aivan sama kaikissa tapahtumissa.

Esimerkiksi:

Lisäät vaikkapa kansainvälisen Berliinissä 17.-26.1. välisenä aikana järjestettävän Vihreä viikko -tapahtuman kalenteriisi. Voit vapaasti määritellä, että tapahtuma ilmestyy vaikkapa kolme kuukautta aikaisemmin tapahtumalistallesi. Se ns. "hyppää" esiin.

Tässä tapauksessa, jos tapahtuman ajanjakso on 17.1.2003 -26.1.2003, sinun tulee määritellä ilmoituksen ajanjaksoksi 17.10.2002-26.1.2003.

 

Ohjelmassa on myös mahdollisuus korostaa tiettyjä tapahtumia. Voit lisätä tila-kenttään esimerkiksi huutomerkin merkitsemään erityisen tärkeää tapahtumaa. Merkki näkyy tapahtumalistalla oletusarvoisesti punaisena ja lihavoituna.

 

Skriptin toimintaperiaate

Kun olet asentanut ohjelman kappaleen II mukaan, voit vaikuttaa skriptin nimen jälkeisiin parametreihin vapaasti. Näin voit tehdä esim. suoria linkkejä kalenteriisi. Skripti toimii näin:

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

Parametetreilla Y ja  m määritellään vuosi ja kuukausi, jolta ajalta kalenterimerkintöjä haetaan.

cal_id:llä määritelään, mitä kalenteria haluat käyttää. (Lue FAQ: Kuinka voin käyttää useaa kalenteria samaan aikaan?)

language -parametrilla voit määritellä kielen, jolla kalenteri näytetään. Mikäli URL:ssa ilmoitettua kieltä ei löydy language -hakemistosta, tulostetaan kalenteri sillä oletuskielellä, mikä on määritelty tiedostossa globals.inc.php.

 

 

IV. Usein kysytyt kysymykset (FAQ)

 

Kuinka voin tulostaa kalenterin osissa?

Jax Kalenteri on muodostettu moduuleista. Tämä mahdollistaa kalenterin tulostamisen osissa. Voit tulostaa joko tapahtumalistan tai varsinaisen kalenteriosuuden erikseen. Tiedosto  main.inc.php tekee kaikki keskeiset proseduurit kalenteria varten. Tiedostot calendar.inc.php ja eventlist.inc.php tulostavat kalenteriosuuden ja tapahtumalistaosuuden erikseen. Katso kalenterin moduulien erikseen tulostamisesta mallia tiedostosta jax_calendar.php.

Mikäli muutat kalenteria jollakin tavalla sovittaaksesi sen sivuillesi, muista säilyttää myös kaikissa muunnelluissa versioissa alkuperäinen copyright-ilmoitus ja osoite alkuperäisiin skripteihin!

 

Kuinka kalenterin ulkoasua voi muuttaa?

Kaikki kalenterin ulkoasuun liittyvä määritellään styles -hakemistosta löytyvissä Stylesheet-tiedostoissa. Näitä tiedostoja voi muokata tavallisella tekstinkäsittelyohjelmalla.

 

Kuinka voin käyttää useaa kalenteria samaan aikaan?

Jos haluat käyttää samaan aikaan useampaa kalenteria, voit kutsua toista kalenteria seuraavalla komennolla:

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

Turvallisuussyistä tiedoston nimeä, jossa kalenteri fyysisesti sijaitsee ei voi näyttää suoraan URL-osoitteessa, vaan se tulee määritellä erikseen tiedostoon globals.inc.php. Esimerkiksi:

...

// Title and Data Source
$calendars[0]->title = "Ensimmäinen Jax Kalenteri";
$calendars[0]->data_source = "csvfile";

$calendars[1]->title = "Toinen Jax Kalenteri";
$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";

...

Kalenterit määritellään siis seuraavasti:

Toinen kalenteri, mikä käyttää MySQL-tietokantaa merkitään URL:ssa seuraavasti

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

ja vastaavasti kolmas kalenteri merkitään:

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

jne...

Huom! Eri kalenterit voivat  käyttää erilaisia tallennusmenetelmää (MySQL tai CVS-tekstitiedostot) samanaikaisesti!

 

Kuinka tiedostojen ja hakemistojen oikeuksia muutetaan?

Jos käytät palvelinta tekstitilassa (UNIX-järjestelmät), kannattaa sinun käyttää komentoa chmod tiedostojen ja hakemistojen oikeuksien muuttamiseen.  Oikeuksien muuttaminen tapahtuu kuitenkin helpommin FTP-ohjelmiston avulla. Seuraavassa lyhyt selostus chmod-komennosta:

Komennon perussyntaksi on seuraavanlainen:

chmod rwxrwxrwx tiedoston_nimi

r = lukuoikeus
w = kirjoitusoikeus
x = suoritusoikeus

Komennossa määritellään kolmelle eri "rymälle" oikeudet samaan aikaan: [rwx][rwx][rwx]

Ryhmät vasemmalta oikealle:

Kakki käyttäjät
Kaikki saman ryhmän käyttäjät, mihin tiedoston omistaja kuuluu
Käyttäjä itse

Komento voidaan antaa myös binäärimuotoisena seuraavan kaavan mukaan:

chmod [rwx][rwx][rwx]

ja sama komento annettaisiin binäärisesti seuraavasti:

chmod [111][111][111]

tai desimaalimuodossa seuraavasti:

chmod [7][7][7]

Jos haluat antaa kaikille käyttäjille kaikki oikeudet tiedostoon, kirjoita:

chmod 777 calendar.csv

(Tarvittavat oikeudet riippuu täysin palvelimesi ylläpitäjän tekemistä asetuksista. Älä siis suoraan anna kaikkia oikeuksia kaikille (777), vaan kokeile muolla oikeuksilla ensin. Skriptin antamat virheilmoitukset eivät ole kenenkään vahingoksi!)

Useimmissa FTP-ohjelmissa oikeuksien muuttaminen on erittäin helppoa (esim. WS-FTP). Näissä ohjelmissa, kuten WS-FTP:ssä, sinun ei tarvitse kuin klikata tiedostoa oikealla hiiren painikkeella ja sen jälkeen asettaa oikeat oikeudet.

 

Miten monta tapahtumaa Jax Kalenteriin mahtuu?

Tällä hetkellä kalenteriohjelmaa on testattu noin 200:n tapahtuman listalla. Lista tallennettiin tekstimuodossa (CVS-tiedostoon) ja toimi hyvin. Teoriassa skriptin toimivuuden rajana on vain käytettävissä oleva palvelimen laskuteho ja aika, joka eri prosesseille maksimissaan annetaan. Kalenteri toimii siis ongelmitta vielä tuhansien tapahtumien listalla. Suurempiin kalentereihin suositellaan kuitenkin käytettäväksi MySQL-tauluja.

 

Mistä saan tiedon uusimmista päivityksistä?

  1. Kotisivuiltamme (http://www.jtr.de/scripting/php/calendar) luonnollisesti ;-)

  2. Pääkäyttäjän hallinnointiskriptistä. Klikkaa vain hallinnointisivulla olevaa kohtaa "päivitykset". Vasemmalla sivulla näkyy pieni vihreä merkki, jos uusia päivityksiä ei ole, pieni keltainen merkki, jos uudempi versio on saavavilla ja punainen merkki, jos uusi ohjelman turvallisuuteen liittyvä päivitys on saatavilla. Turvallisuuspäivitykset ovat erityisen tärkeitä.

  3. Rekisteröi itsesi "JtR News"-uutispalveluun. (http://www.jtr.de/scripting/php/newsletter/newsletter)

 

V. Virheet ja ongelmat

 

Ongelma MySQL:n kanssa

Jax Kalenteri tallentaa vain yhden tapahtuman tauluun, ja näyttää aina saman tapahtuman.

Todennäköisesti unohdettu esimerkkitaulua ja unohdettu liittää ID-kenttä, mikä on pakollinen.

 

VI. Muutoshistoria (Change Log)

 

Muutokset versioon 1.26:

Muutokset versioon 1.25:

Muutokset versioon 1.2:

 


Mikäli löydät ohjelmistosta virheen, sinulla on kysymyksiä tai ongelmia skriptien kanssa tai haluat antaa kehittämisidean, ole hyvä ja ota minuun suoraan yhteyttä!


Berlin, 10.05.2003 - Jack (tR)
Rovaniemi, Finland, 17.05.2003 - zQw