Die Informationsseite zum Script inkl. Downloadmöglichkeit und Online-Demo finden Sie hier!
csvTool ist als Administrationstool für beliebige kleine Plain-Text Datenbanken geeignet (getrennt durch ";", Tabulator oder ein anderes Kennzeichen), wo webbasiert Änderungen vorgenommen werden müssen. Klassisches Beispiel ist eine kleine Adresskartei, auf die mehrere Personen Zugriff haben sollen. Es können Datensätze editiert, gelöscht und neu hinzugefügt werden. csvTool benötigt nur sehr wenige Konfigurationseinstellungen: Pfad zur CSV-Datei, Trennzeichen innerhalb der Zeile und Titel - fertig (nebst ein paar Datenbankunabhängigen Einstellungen wie Pfad zu den Bildern und dem CSS-Stylesheet).
csvTool ermöglicht es ebenfalls, bestimmte Felder als Pflichtfelder oder (optional erweiterbares) Dropdown-Felder zu definieren und/oder die erlaubten Feldwerte einzuschränken. Da es universell mit allen möglichen Datenquellen eingesetzt werden kann, ist die Defintion dieser Angeben in einer separaten Datei erforderlich und etwas komplizierter. Für Formulare die sehr genau geprüft werden sollen ist die Definiton daher etwas mühsam resp. benötigt eine gewisse Einarbeitungszeit.
Die Hauptmaske der Datenbank steht uneingeschränkt jedem Besucher zur Verfügung: wer csvTool nur einem bestimmten Besucherkreis zur Verfügung stellen will, sollte das Script-Verzeichnis mit einer .htaccess-Datei schützen. Weitergehende Aktionen wie Detailansicht, editieren, neue Datensätze hinzufügen oder löschen von Datensätzen können mit einem Passwort (pro Aktion ein eigenes möglich) geschützt werden. Eine weitergehende Benutzerverwaltung ist nicht möglich.
Folgende Dateien müssen kopiert und mit den entsprechenden Berechtigungen versehen werden:
|
|
| $moreThanOne | Legt fest, ob mit dieser Installation von csvTool nur eine Datei (0) oder mehrere Dateien (1) editiert werden können. |
| $dataFile | Abhängig vom $moreThanOne Wert: $moreThanOne=0: Definiert den Standort der Datendatei (UNIX-Pfad). Wenn die Datei zum Download angeboten werden soll, muss sich diese Datei ggf. ausserhalb des cgi-bin Verzeichnisses befinden. $moreThanOne=1: Definiert die erlaubten Dateinamen mittels Perl-Regular-Expression (siehe Kapitel 2.4. und 2.5.) |
| $dataFileB | Abhängig vom $moreThanOne Wert: $moreThanOne=0: Legt den Browser-Pfad (Download-URL) zur Datendatei fest. Wird der Wert leer gelassen, bietet das Script die Datei nicht zum Download an. $moreThanOne=1: Definiert den Pfad zur Browser-Datei (siehe Kapitel 2.5.). Bei gesetzem Anzeige-Passwort ($viewPass) wird der Download-Link nie angezeigt. |
| $filePrefix | nur bei $moreThanOne=1 relevant, definiert eine Zeichenfolge, die vor den Dateinamen gesetzt wird. |
| $splitChar | Definiert das Trennzeichen innerhalb eines Datensatzes, z.B. ";", "," oder "\t" (=Tabulator) |
| $csvTemplate | Definiert den Namen eines weiteren Templates mit einer Kopie der Daten in frei definierbarer Form. Dateiname muss zwingend auf .template enden. Mehr Informationen siehe Kapitel 2.8.. |
| $title | Titel der Datenbank (wird auf der Webseite angezeigt und erscheint als Betreff bei optionaler Mailbenachrichtigung) |
| $useBBtags | Legt fest, ob die BB-Tags [b][/b] (fett), [i][/i] (kursiv), [u][/u] (unterstrichen), [img][/img] (Bild), [a][/a] (Link) und [br] (Zeilenumbruch) in Datensätzen erlaubt sind. |
| $autoLink | Definiert, ob URLs und Mailadressen automatisch in Links umgewandelt werden (1) oder nicht (0) |
| $order | Legt fest, ob die Sortierung der Suchergebnisse erlaubt (1) oder verboten (0) ist |
| $editGIF | Browser-Pfad zum Editieren-GIF |
| $viewGIF | Browser-Pfad zum Detailansicht-GIF |
| $delGIF | Browser-Pfad zum Löschen-GIF |
| $css | Browser-Pfad zum CSS-Stylesheet |
| $template | UNIX-Pfad zum Template, siehe Kapitel 2.6. |
| $changeMail | Mailadresse für optionale Mailbenachrichtigung: wird diese eingetragen, wird bei jedem neuen, editierten oder gelöschten Datensatz ein Mail mit den Details an diese Adresse gesendet. |
| $senderMail | Absender-Mailadresse bei Benachrichtigungen (sofern aktiviert). Leer=Empfänger-Adresse wird auch als Absender verwendet. |
| $sendmail | Pfad zu sendmail (nur bei Mailbenachrichtigung relevant) |
| $numbShow | Anzahl anzuzeigende Datensätze pro Seite (egal ob mit aktivierter Suche oder nicht) |
| $pageShow | Anzahl direkt anzuspringende Datensatz-Seiten. 0=keine direkten Seitenlinks, nur relevant wenn $numbShow > 0. Beispiel: Benutzer ist auf Seite 5, bei $pageShow=2 sind Seiten 3,4,5,6 und 7 direkt zugänglich. |
| $logFile | Detailliertes Logfile aller Aktionen (optional; leer=kein Log) |
| $csvExport | Wenn dieser Wert auf 1 gesetzt wird, können Suchergebnisse optional als CSV gespeichert werden (Checkbox neben Such-Button). 0=kein CSV-Export von Suchergebnissen |
| $viewPass | Passwort, um einen Datensatz im Detail anzusehen (leer=kein Passwort notwendig, N/A = Funktion ist deaktiviert) |
| $editPass | Passwort, um einen Datensatz zu editieren (leer=kein Passwort notwendig, N/A = Funktion ist deaktiviert) |
| $delPass | Passwort, um einen Datensatz zu löschen (leer=kein Passwort notwendig, N/A = Funktion ist deaktiviert) |
| $addPass | Passwort, um einen neuen Datensatz zu erfassen (leer=kein Passwort notwendig, N/A = Funktion ist deaktiviert) |
| $search | Definiert Suchmaske: 0=ein Suchfeld, es wird in allen Spalten gesucht 1=Suchfeld füt alle Spalten 2=Suchfeld für alle in der Hauptübersicht sichtbaren Spalten 3=Suchfelder können bei $searchUserDef definiert werden |
| $searchUserDef | nur bei $search=1: Suchfelder durch ; getrennt |
| $searchRequired | 0=Suche optional (Anzeige aller Datensätze möglich), 1=Suche zwingend erforderlich |
| $searchPrefix | Wird der Suche vorangestellt, Perl Regular Expression (z.B. ^ = Suche beginnt am Feldanfang) |
| $searchPostfix | Wird der Suche hinternangestellt, Perl Regular Expression (z.B. $ = Suche endet an Feldende) |
| $searchCharsForbidden | verbotene Zeichen in Suchanfrage, Perl Regular Expression ([^A-Z] = nur Buchstaben erlaubt, [öäüÖÄÜ] = keine Umlaute erlaubt) |
| $searchMinLength | minimale Länge der Suchanfrage. 0=alles erlaubt. Bei $searchRequired=0 und $searchMinLength=3 ist eine Abfrage aller Datensätze erlaubt, wenn aber gesucht wird muss der Begriff mindestens 3 Zeichen enthalten. |
| $srchRules{"Feldname"} | Definiert Suchparameter pro Feld und übersteuert $searchMinLength, $searchPrefix und $searchPostfix, wenn für Suchspalte hier ein Wert definiert ist. Format: Länge§§Prefix§§Postfix, z.B. 3§§^§§$, wenn der Suchbegriff min. 3 Zeichen enthalten soll und der Inhalt des kompletten Feldes anstelle eines Teiles davon erforderlich ist. |
Mit der Angabe von $moreThanOne=1 kann csvTool mehrere Dateien verwalten. Hierbei ist es möglich, zu definieren, dass z.B. nur Dateien im aktuellen Verzeichnis und/oder mit der Dateiendung .csv editiert werden können.
Hierbei sind folgende Parameter von Bedeutung:
| $moreThanOne | muss auf 1 gesetzt werden |
| $dataFile | Regular-Expression mit den erlaubten Dateinamen (siehe Kapitel 2.4.). Beispiel: \.csv$: muss mit .csv enden database: muss Text "database" enthalten ^[a-z0-9\.\-]$: Darf nur Buchstaben, Zahlen sowie . und - enthalten (kein Verzeichniswechsel) |
| $dataFileB | Definiert den Browser-Pfad, der der Datei vorne angefügt wird. Beispiel: Dateien liegen unter "/home/www/xyz.ch/html/test/*.csv", Script unter "/home/www/xyz.ch/cgi-bin/csvtool/csvtool.cgi". In diesem Fall sollte "/home/www/xyz.ch/html/test/" als $filePrefix gewählt werden, "/test/" als $dataFileB. |
| $filePrefix | Analoges Beispiel zum $dataFileB für den UNIX-Pfad: der hier angegebene Wert wird vorne an den Dateinamen angefügt, kann z.B. ein UNIX-Pfad sein. |
Die Dateinamen setzen setzen sich also wie folgt zusammen:
Damit csvTool mit mehreren Dateien funktioniert, muss der Dateiname der URL übergeben werden. Dies erfolgt mit dem Parameter file=DATEINAME.EXT. Ebenfalls kann auch ein Titel übergeben werden (fehlt dieser, wird der Text von $title verwendet). Eine URL kann also beispielsweise so aussehen:
http://www.server.ch/cgi-bin/csvtool.cgi?file=xyz.csv&title=Mein%20Titel
csvTool kann ein Template einbinden, um sich besser in die Homepage zu integrieren. Dazu kann optional beliebiger HTML-Code ober- und/oder unterhalb der Datentabelle angegeben werden.
Dazu definiert man beim Suchparameter $template eine Template-Datei (UNIX-Pfad). Diese Datei wird verarbeitet und markierte Bereiche werden 1:1 ausgegeben.
Jeder Code zwischen <!--headerStart--> und <!--headerEnd--> (Steuerungstag muss jeweils auf einer separaten Zeile stehen) wird ganz am Anfang der Datei unverändert ausgegeben.
Gleiches gilt für <!--footerStart--> und <!--footerEnd--> (Steuerungstag muss ebenfalls auf einer separaten Zeile stehen): Dieser Code wird ganz am Schluss ausgegeben.
csvTool bietet eine sehr genaue Möglichkeit, Feldwerte vor dem speichern zu prüfen und so nur gültige Werte zuzulassen. Das Regelwerk ist extrem flexibel und basiert auf Perl Regular Expressions (siehe folgendes Kapitel), benötigt allerdings leider etwas Einarbeitungszeit/Erfahrung.
Das Regelwerk wird jeweils in einer gleichnamigen Datei mit der Endung ".rules" definiert. Ein Regelwerk für die Datei "meinedatei.csv" muss also "meinedatei.csv.rules" heissen und sich im selben Verzeichnis befinden.
Das Regelwerk ist so aufgebaut, dass es wiederum mit csvTool bearbeitet werden kann (eigene Installation oder editieren von mehreren Dateien in csvTool aktivieren). Der Aufbau sieht wie folgt aus:
#ID;Feldname;Wert 1;Anrede;((Herr|Frau)) 2;!Name;.*\d.*
Nun aber der Reihe nach:
Der einfachste Fall einer Einschränkung ist ein Dropdown. Dieses wird mit zwei öffnenden Klammern am Anfang und zwei schliessenden Klammern am Ende definiert. Die einzelnen Werte sind durch | getrennt, steht am Schluss ein .* kann das Dropdown erweitert werden. Beispiele:
((Herr|Frau)) definiert, dass ein Dropdown mit den zwei Werten "Herr" und "Frau" angezeigt wird. Es muss zwingend einer dieser zwei Werte ausgewählt werden.
Mit ((|Herr|Frau)) wird ein Dropdown mit drei Werten angezeigt: [leer], Herr und Frau
((Herr|Frau|.*)) führt dazu, dass ein Dropdown mit "Herr" und "Frau" angezeigt wird, man jedoch die Möglichkeit hat, auch einen beliebigen anderen Text einzugeben.
.*(\[br\])?.* kennzeichnet, dass das Feld auch Zeilenumbrüche enthalten kann (aber nicht muss). Das Eingabefeld wird in der Erfassungs- und Editier-Maske als mehrzeiliges Eingabefeld angezeigt. Mehrzeilige Eingaben durch manuelle Eingabe des BB-Codes [br] sind immer möglich, diese "Spezialregel" dient nur dazu, das Eingabefeld mehrzeilig darzustellen.
Auch eine Definition, ob ein bestimmtes Zeichen im Wert vorkommen muss oder nicht vorkommen darf ist keine Hexerei. Hierbei definiert man über den Feldnamen die genaue Aktion. Mit "Anrede" muss nachfolgendes beim Feld "Anrede" vorkommen, mit "!Anrede" darf folgendes im Feld "Anrede" auf keinen Fall vorkommen.
a.* definiert, dass der Text mit einem "a" beginnen muss und dann beliebige Zeichen folgen dürfen (.*).
Mit .*a.* muss der Text ein "a" enthalten, mit .*[ab].* ein "a" oder "b".
Einzelne Zeichen die entweder/oder vorkommen dürfen gehören in eckige Klammern, Wörter in runde Klammern. Genug der Theorie, hier ein paar Beispiele
1;Telefon;\+?[0-9 \+]+ definiert, dass im Feld "Telefon" nur Zahlen und Leerzeichen erlaubt sind. Einzig das erste Zeichen darf ein + sein, muss aber nicht
2;Land;((Schweiz|Deutschland|.*)) zeigt für das Feld "Land" ein Dropdown mit den Werten "Schweiz" und "Deutschland". Es darf aber auch ein anderer Wert eingetragen werden.
3;!Name;.*\d.* definiert, dass das Feld "Name" keine Zahl (\d) enthalten darf.
4;Mail;[\w\.\-]+\@[\w\.\-]+\.\w+ ist bereits ein Filter für Mailadressen: Zuerst muss ein oder mehrere Buchstaben oder Zahlen (\w = a-z A-Z und 0-9), Punkte oder Bindestriche kommen, dann ein @-Zeichen, dann wiederum Buchstaben, Zahlen, Punkte, Bindestriche (mind. 1 Zeichen), dann ein Punkt und nochmals mindestens ein Buchstabe.
5;Strasse;.{1,} definiert, dass Strasse mindestens ein Zeichen enthalten muss (Pflichtfeld)
6;Ort;.{1,30} definiert, dass Ort zwischen 1 und 30 Zeichen enthalten muss (also Pflichtfeld mit Textlängenbeschränkung)
7;!Vorname;.*(Hans|Fritz).* besagt, dass das Feld "Vorname" weder "Hans" noch "Fritz" enthalten darf.
Das Formular für einen neuen Datensatz ist in den Standard-Einstellungen leer und muss vom Benutzer ausgefüllt werden. csvTool erlaubt es, dass Felder bereits mit Standard-Werten vorbelegt werden können.
Dazu muss im Verzeichnis der Datendatei eine Datei mit der zusätzlichen Dateiendung ".default" erstellt werden, wie es bei den Regeln (vorheriges Kapitel) mit der .rules-Datei der Fall ist. Standardwerte für die Datei "meinedatei.csv" müssen also in der Datei "meinedatei.csv.default" erfasst werden, die sich im selben Verzeichnis befindet.
Das Datei ist so aufgebaut, dass sie wiederum mit csvTool bearbeitet werden kann (eigene Installation oder editieren von mehreren Dateien in csvTool aktivieren). Der Aufbau sieht wie folgt aus:
#ID;Feldname;Wert 1;Vorname;Hans 2;Fax;keiner
Nun aber der Reihe nach:
Das Beispiel oben würde also das Feld "Vorname" mit dem Wert "Hans" vorbelegen und das Feld "Fax" mit "keiner". Für die Standardwerte existieren noch einige spezielle Platzhalter:
| <!--datum--> | Datum in langer Schreibweise, z.B. 1. Dezember 2008 |
| <!--datumTTMMJJJJ--> | Datum in kurzer Schreibweise, z.B. 01.12.2008 |
| <!--datumTTMMJJ--> | Datum in kurzer Schreibweise mit zweistelliger Jahreszahl, z.B. 01.12.08 |
| <!--zeit--> | Zeit im Format hh:mm:ss, z.B. 15:36:47 |
Datenquelle von csvTool ist stets die definierte CSV-Datei mit ihren Spaltenüberschriften. Manchmal ist es aber evtl. notwendig, dass die Daten in genau definierter Struktur zur Verfügung stehen, welche csvTool mit der Standard-Datenquelle nicht abdecken kann (Wiederholung eines Feldes in einer anderen Spalte, mehrere Felder zu einem Feld zusammenfügen, Wenn-Abfragen im Stil von "Wenn Feld X = Y dann schreibe hier Z", nur eine Auswahl von Feldern etc.). Dafür existiert in csvTool die Möglichkeit, zusätzlich zur Haupt-CSV noch ein frei definieres zusätzliches CSV-Template zu definieren. Hauptdatenquelle bleibt aber immer noch das Haupt-CSV: Felder die dort nicht vorhanden sind, können nicht erfasst werden und das zusätzliche CSV-Template ist nur eine Kopie des Haupt-CSV, welche bei jedem Speichervorgang neu geschrieben wird.
Bei sehr grossen CSV-Dateien (mehr als 20'000 Datensätze) kann durch die Verwendung eines CSV-Templates die Performance je nach Serverleistung unter Umständen erheblich eingeschränkt sein.
Der Dateiname des Templates muss zwingend auf .template enden. Die Zieldatei wird ohne diese Dateiendung im selben Verzeichnis wie die Template-Datei abgelegt. Das Template path/to/file/test.csv.template erstellt also eine test.csv im Ordner path/to/file.
Ein CSV-Template besteht aus einer beliebigen Anzahl Header-Zeilen (0-n) welche jeweils einmal am Anfang der CSV-Datei eingefügt wird und einer beliebigen Anzahl Datenzeilen (1-n), welche pro Datensatz wiederholt wird.
Der Aufbau des CSV-Templates sieht wie folgt aus:
Ein Template kann somit beispielsweise so aussehen:
Anrede;Name;Strasse;PLZ Ort;Land<!--headerline--> <!--anrede-->;<!--vorname--> <!--name-->;<!--strasse-->;<!--plz--> <!--ort-->;<!--land--><!--if:land=§CH-->
In diesem Fall würde das zusätzliche CSV Vorname und Name sowie PLZ und Ort in jeweils ein Feld schreiben. Ebenfalls würde die Spalte "Land" mit dem Kennzeichen "CH" ergänzt, wenn diese leer ist (Details zur IF-Abfrage siehe nächstes Kapitel).
Um nur einen Teil eines Feldes auszugeben kann mit einem Substring-Befehl gearbeitet werden. Dazu muss hinter dem Feldnamen ein §, gefolgt von der Position des ersten Zeichens (beginnend bei 0) und der Anzahl Zeichen eingegeben werden. Beispiel:
Hierbei würden die ersten drei Zeichen des Feldes "feldname" ausgegeben.
Im zusätzlichen CSV-Template ist es möglich, mittels IF-Abfrage (WENN-Bedingung) einen bestimmten Text nur dann auszugeben, wenn eine Bedingung erfüllt oder nicht erfüllt ist. Der Syntax sieht wie folgt aus:
Im Text können auch Feldnamen ausgegeben werden, müssen aber mit #!--feldname--# statt <!--feldname--> geschrieben werden. Ebenfalls kann mit \n ein Zeilenumbruch eingefügt werden.
Beispiel für einige IF-Abfragen:
Dies führt dazu, dass der Text "[leer]" nur ausgegeben wird, wenn das Feld "ort" leer ist, ansonsten wird hinten der Ort ausgegeben.
Als weiteres Beispiel kann man den Inhalt von Feldern, die in kurzer Schreibweise erfasst sind anpassen:
Zudem sind auch numerische Vergleiche möglich:
Perl Regular-Expressions dienen der Mustererkennung von Text-Feldern. Weiterführende Informationen findet man z.B. unter http://de.wikipedia.org/wiki/Reguläre_Ausdrücke. Nachfolgend sollten die wichtigsten Funktionen aufgeführt werden:
Bei csvTool können Regular Expressions in der Suche, der Definition von Suchparametern sowie bei den Texteinschränkungen von Feldern verwendet werden.
| . | Beliebiges Zeichen |
| \d | Ziffer (0-9), auch schreibbar als [0-9] |
| \D | Keine Ziffer (alles ausser 0-9), auch schreibbar als [^0-9] |
| \w | Alphanumerische Zeichen inkl. _ und Zahlen aber ohne Umlaute, auch schreibbar als [a-zA-z0-9_] |
| \W | Nicht-Alphanumerisches Zeichen, auch schreibbar als [^a-zA-Z0-9_] |
| \s | Leerzeichen und andere White-Spaces (\n \r \t \f [FormFeed]), auch schreibbar als [ \t\r\n\f] |
| \S | Kein Leerzeichen, auch schreibbar als [^ \t\r\n\f] |
| ^ | Beginn des Strings |
| $ | String-Ende |
| [] | Auswahlmöglichkeiten einzelner Zeichen / ODER |
| (abc|def) | Auswahlmöglichkeiten mehrer Zeichen / ODER (abc oder def) |
| \. \[ \] \/ \( \) \{ \} \? \+ \$ | Die Zeichen . [ ] / ( ) { } ? + $ |
| \n \t \r \f | haben ihre normale Bedeutung (Zeilenumbruch, Tabulator, Carriage-Return, Form-Feed |
Zudem gibt es noch spezielle Tags für Mengenangaben, wie oft ein Zeichen hintereinander vorkommen muss.
| ? | Kein- oder einmal, {0,1} |
| * | Keinmal bis beliebig oft {0,} |
| + | Ein- oder mehrmal {1,} |
| {7} | siebenmal |
| {3,5} | Drei- bis fünfmal |
| {4,} | Viermal oder mehr |
In ein paar praktischen Beispielen kann das wie folgt aussehen:
| .{5} | Wert muss 5 beliebige Zeichen enthalten |
| Hans.*Muster | Muss die zwei Wörter "Hans" und "Muster" enthalten (zuerst Hans, dann Muster, dazwischen darf sich beliebiger Text befinden) |
| (Meer|Strand|Sand) | Muss mindestens eines der erwähnten Wörter beinhalten |
| \d{3}\s\d{2}\s\d{2} | Muss eine Kombination wie "099 99 99" enthalten (Telefonnummer, Block mit 3, 2 und 2 Zahlen, dazwischen jeweils ein Leerzeichen |
| [12]?\d?\d\.[12]?\d?\d\.[12]?\d?\d | Muss eine IP-Adresse enthalten |
| ^Ich.*!$ | Text muss mit "Ich" beginnen und "!" enden |
| Copyright © 2009 by Jürg Sommer, scripts@cgicorner.ch http://www.cgicorner.ch |
Letzte Änderung: 30. Mai 2009 |