Revue Calendar
Alanius March 22, 2008
Nodige les:
Php les:
• calendar.php
• calendar_entry.php
• calendar_edit.php
• calendar_add.php
• calendar_edit_submit.php
• calendar_add_submit.php
• calendar_groups.php
Text les:
• calendar_entries.txt
• calendar_log.txt
calendar.php
Als het included wordt zonder dat de url-parameter show waarde true heeft, dan geeft deze le alleen de macro die naar de juiste entries le verwijst (calen- dar_entries.txt meestal).
Als show wel de waarde true heeft, produceert deze le de HTML-output van een tabel met de dagen, activiteiten, enz. Dit produceert dus niet een volledige HTML page, alleen de <table> tags en alles wat er tussen staat.
url-parameters:
• show moet er een tabel komen met de kalenderdata of niet?
• begin, en
• end tussen deze twee timestamps zoekt calendar.php alle entries
• groups calendar.php vertoont alleen activiteiten van deze groepen
calendar_entry.php
1. Klasse CalendarEntry, met drie velden:
• timestamp aantal seconden sinds epoch dat de activiteit plaatsvindt
• text een korte beschrijving van de activiteit, zoals bv promover- gadering of cantus
• groups een text string van de betreende (werk)groepen, lowercase en onderlinge groepen worden gesepareerd door een komma
en een methode:
• ProduceCell bundelt alle data en retourneert HTML-code van
<td> tot en met </td>
2. Een functie ReadEntries met als enige parameter de le name van de le die gelezen moet worden (calendar_entries.txt, maar de mogelijkheid tot uitbreiden bestaat). Deze functie retourneert een array van CalendarEn- try's die uiteraard ingevuld zijn met de juiste waarden.
calendar_edit.php
Produceert de volle HTML-output (van <html> tot </html>) van een form- pagina waarmee een bestaande entry aangepast kan worden. Het is de bedoeling dat deze pagina in een _blank window wordt geopend.
De submit knop stuurt alle form-informatie door naar calendar_edit_submit.php.
url-parameters
• day timestamp van het begin van die dag (dwz: 00:00 's nachts)
• entrynr hoeveelste entry het is van die dag dat aangepast moet worden
calendar_edit_submit.php
Deze le verwerkt de form-informatie die calendar_edit.php doorgestuurd heeft.
Hij zoekt in de le calendar_entries.txt naar de juiste entry en past hem dan goed aan. Ook slaat hij de verandering op in calendar_log.txt.
calendar_add.php
Vrij analoog aan calendar_edit.php. De verschillen zijn dat dit bedoelt is om een nieuwe entry aan te maken, niet een bestaande entry te veranderen, en dat de datum(s) logischerwijze veranderbaar is.
De submit knop stuurt hier alle form-informatie door naar calendar_add_submit.php.
url-parameters
• day timestamp van het begin van die dag waarop de user geclickt had.
Dit wordt getoond in een veranderbare form eld.
calendar_add_submit.php
Deze le verwerkt de form-informatie die calendar_add.php doorgestuurd heeft.
Hij plaatst simpelweg een nieuwe entry in de le calendar_entries.txt (en past calendar_log.txt aan).
calendar_groups.php
Deze le produceert een text string met alle mogelijke (werk)groepen, lowercase en onderling gesepareerd door een komma.
calendar_entries.txt
Een text le waarin alle kalender entries staan, in een welbepaald formaat.
calendar_log.txt
(Optioneel) Een text le die alle veranderingen aan de kalender bijhoudt.
Formaat van calendar_entries.txt
De inhoud van calendar_entries.txt bestaat uit een willekeurig groot aantal u raadt het al entries:
*** Drie asterisks duiden het begin van de entry aan
timestamp 32 bytes die het aantal seconden na de start van de epoch aanduiden wanneer de activiteit gaat plaatsvinden
\n Newline character
** Twee asterisks
text Korte (maar willekeurig lange) beschrijving van de activiteit
\n Newline character
** Twee asterisks
groups betreende (werk)groepen, lowercase en gesepareerd door komma's
\n Newline character
*** Drie asterisks
\n\n Dubbele newline character
Omdat asterisks gebruikt worden in het formaat van entries, kunnen er niet meer dan een opvolgende asterisks in de text (of werkgroepen) voorkomen. cal- endar_add_submit.php en calendar_edit_submit.php moeten dit voorkomen.
Formaat van calendar_log.txt
De formaat waarin de logs bijgehouden worden is niet van groot belang; het moet gewoon leesbaar zijn (door mens en door implementatie van weet-ik-veel- wat). De inhoud bestaat hoedanook uit log entries:
**** Vier asterisks
timestamp Timestamp wanneer de verandering is toegepast
\n Newline character
user Username van de persoon die een verandering maakt
\n\n Dubbele newline character
oldentry De entry (in hierboven beschreven formaat) van wat het eerst was (als de verandering in wezen een additie was, dan heeft dit lengte nul)
newentry De entry (in hierbovenbeschreven formaat) zoals dat het nu is
****\n\n\n Vier asterisks en drie newline characters
Ontwerpbeslissingen
Pluginabiliteit
Om het systeem zo pluginabel mogelijk te maken, heb ik het van zo weinig mogelijk dingen afhankelijk gemaakt. Er wordt geen database gebruikt (be- halve misschien in calendar_groups.php), de implementator moet zelf zien hoe de kalender in zijn website past (omdat het niet layout-afhankelijk is), en cal- endar_edit.php en calendar_add.php zijn popup windows; ook niet afhankelijk van de layout van de web-pagina.
Scheiding van edit en add
Voor de gebruiker is het misschien nauwelijks merkbaar, maar uiteindelijk is er een groot verschil tussen edit en add. Edit betekent, zoek de juiste entry op in onzen le en verander zonodig; add betekent, Zet een nieuwe entry bij onzen
le.
Nut van calendar_groups.php
calendar_groups.php is een le die met de omgeving moet communiceren. Dit wil zeggen, in verschillende implementaties kan calendar_groups.php op een verschillende manier aan de juiste groepen komen. Het zou op een plaats doo- dgewoon een string kunnen zijn die vastligt in de le zelf, maar op een andere plaats zouden de groepen uit een database moeten komen.
Mogelijke uitbreidingen
Weghalen van oude entries
Entries waarvan de timestamp meer dan een dag oud is, worden verplaatst van de le calendar_entries.txt naar de le calendar_entries_old.txt.
Zo is calendar_entries.txt kleiner en kan het dus sneller gelezen worden.
Repercussies
• Er moet een functie MoveOldEntries bij calendar_entry.php die de le calendar_entries.txt leest en opnieuw alles schrijft, maar zonder de oude entries. Deze zet hij bij calendar_entries_old.txt.
• Deze functie moet opgeroepen worden vanuit ReadEntries als hij ziet dat er oude entries bij zijn.
• Er moet een optionele parameter ReadOld bij ReadEntries komen, omdat als deze functie vanuit calendar.php opgeroepen wordt, dan zou het ook kunnen dat de gegeven le name de le name is van de oude entries, niet de nieuwe.
• calendar_edit.php en calendar_edit_submit.php moeten er rekening mee houden dat een te veranderen entry weleens een oude entry zou kunnen zijn. Dit probleem is niet het geval bij add omdat het geen zin heeft een nieuwe entry aan te maken op een datum dat al verstreken is. (Dit is dan ook niet mogelijk.)
• calendar.php moet zowel de actuele entries vertonen als de oude entries.
