classAd 4.0 - benutzerhandbuch

Installation

Die Installation ist sehr einfach gehalten, fast 'out-of-the-box':

  1. Editieren Sie die Konfiguration
    Zur Installation ist es zunächst wichtig, dass die "Datenbank"-Sektion der Konfigurationsdatei inc/config.inc.php den Gegebenheiten auf Ihrem Webserver angepasst wird. Editieren Sie hier den Datenbank-Host, den Datenbank-Benutzernamen und das -passwort, sowie den Datenbanknamen. An dieser Stelle sollten Sie auch den Administratornamen und das -passwort ändern - bitte achten Sie darauf diese nicht leer zu lassen, da das Login-Skript dieses aus Sicherheitsgründen nicht akzeptiert.
  2. Starten Sie nun admin_install.php in Ihrem Browser
    Dieses Skript wird die Tabelleneinrichtung für Sie vornehmen. Prüfen Sie, ob Datenbankname/-server/-user korrekt angezeigt werden, dann klicken Sie auf "Datenbank installieren", um die Datenbankinstallation zu starten. Sollten bei der Installation Fehler auftreten, so wird Sie die Installationroutine darüber informieren.
    Wie Sie vorhandene Datenbankeinträge in die neue Version übernehmen können, lesen Sie weiter unten.

    !ACHTUNG: Nach erfolgreicher Installation ist es wichtig, dass die Dateien "admin_install.php" und "admin_update_*.php" gelöscht oder auf nicht-ausführbar gesetzt werden (chmod 000), um eine ungewollte Datenbankmanipulation durch Benutzer zu vermeiden.
  3. Wenn Sie nun admin.php aufrufen, können Sie sich bei der Administration anmelden.
  4. Im Administratormenü sollten Sie sich zunächst Gedanken zum Rubrikenaufbau machen, bei Bedarf freie Felder definieren und schliesslich Rubriken anlegen.
  5. Zur spezielleren Einstellung von Layout, Mail und anderen Variablen prüfen und editieren Sie, vor einer produktiven Nutzung, die Datei inc/config.inc.php.Unter anderem ist es hier wichtig, die URLs und Pfade auf die Anforderungen Ihres Webservers anzupassen.
  6. Für weitere Änderungen ändern Sie die Templates, Sprach- und/oder die Stylesheet-Datei ab. Nähere finden Sie unter Customizing der Anwendung.

Insbesondere bei Unix-basierten Systemen sollten Sie darauf achten, dass das Skript auf die Verzeichnisse /usergraphics und /cache Schreib-/Leserechte hat (s. Bugtracking ). Ebenfalls sollten Sie auf diesen Webservern die Grafikkonvertierung der GD-Library auf Version 1.xx zurückschalten (s. Bugtracking )

Update

Dateienübersicht

CTS ClassAd sollte im Distributionspaket folgende Dateien enthalten:

Datei Funktion
admin.php Anmeldung und Hauptmenü des Administrators
admin_addcategory.php Fügt dem Markt neue Rubriken hinzu (Administrator)
admin_dbmaintain.php Skript zur Datenbankwartung (Administrator)
admin_definefields.php Definieren von freien Datenbankfeldern (Administrator)
admin_deleteoutdated.php Verwaltung und löschen abgelaufener Anzeigen (Administrator)

admin_editcategory.php

Löschen und Editieren von Rubriken in der Datenbank (Administrator)
admin_editmessage.php Verwalten, editieren und löschen von Anzeigen in der Datenbank (Administrator)
admin_editmessagedetails.php Editieren einer einzelnen Anzeige (Administrator)
admin_edituser.php Verwalten, editieren und löschen von Benutzern (Administrator)
admin_edituserdetails.php Editieren von Benutzerdaten (Administrator)
admin_install.php Installationsprogramm
Achtung: Sollte nach erfolgreicher Installtion gelöscht oder deaktiviert werden (chmod 000)
admin_logout.php Logout für den Administrator (Administrator)
admin_phpinfo.php Zeigt PHP-Informationen an (Administrator)
admin_showlog.php Zeigt aufgezeichnete Ereignisse an / Logbuch (Administrator)
admin_statistics.php Zeigt Markt-Statistiken (Administrator)
contact.php Allgemeines Kontaktscript
contactad.php Kontakt bzgl. einer eingetragenen Anzeige
cyclicmain.php Skript, welches allgemeine Wartungsaufgaben ausführt
Achtung: Dieses Skript sollte als Cronjob (oder in anderer Form regelmäßig) gestartet werden
editmessageuser.php Bearbeiten einer Anzeigen durch den besitzenden Benutzer (Benutzer)
generalterms.php Anzeige der AGB
imprint.php Anzeige des Impressum
index.php Hauptrubrikenübersicht / Startseite
lostpassword.php Skript für die Benutzer, die Ihr Passwort vergessen haben
newad.php Neue Anzeige aufgeben
newuser.php Als neuer Benutzer registrieren
releasesubmit.php Anzeige freischalten mittels Email-Code (Administrator ohne Login)
releaseuser.php Freischalten / Aktivierung eines Benutzers, der im Opt-in-Verfahren registriert wurde mittels Email-Code (Benutzer ohne Anmeldung)
rss.php Anzeige der RSS-Informationen
rssfeed.php Generiert den XML-RSS-Feed aus den übergebenen Variablen
searchads.php Suche nach Anzeigen
searchextend.php Erweiterte Suche nach Anzeigen
showad.php Anzeige von Anzeigen (kann per GET-Übergabe aufgerufen werden zur Verlinkung)
tellad.php Weiterempfehlen von Anzeigen
userlogin.php Benutzer-Anmeldung
userlogout.php Benutzer-Abmeldung
usermymessages.php Anzeigenübersicht für Benutzer mit Editiermöglichkeit (Benutzer)
usermysettings.php Bearbeitung von Benutzerdaten (Benutzer)
/inc Verzeichnis: Enthält die benötigten Programmteile
/languages Verzeichnis: Enthält die Sprachdateien für die verfügbaren Sprachen
/styles Verzeichnis: CSS-Dateien
/emailtemplates Verzeichnis: Enthält Email-Templates
/templates Verzeichnis: Enthält HTML-Templates (untergeordnet nach Sprachen)
/graphics Verzeichnis: Alle Grafiken, die zum Ablauf des Skriptes benötigt werden sollten in diesen Ordner kopiert werden. Dieses gilt im besonderen auch für Rubrikenlogos.
/catlogos Verzeichnis: Enthält die Grafiken, die als Rubriken-Logos genutzt werden sollen
/usergraphics

Verzeichnis: Upgeloadete Grafikdateien von Benutzern werden hier gespeichert. Bei Upload eine Bildes werden vom newad.php Script zwei Dateien angelegt - Ein Vorschaudatei und eine Datei, die bei Ansicht der Anzeige angezeigt wird. Löschen Sie niemals Dateien manuell aus diesem Verzeichnis, da die Dateinamen in eindeutige Bezeichnungen umgewandelt werden!
!Achtung: PHP benötigt Schreib-/Leserechte.

/doc Verzeichnis: Enthält diese Dokumentation (untergeordnet nach Sprachen)
/cache Verzeichnis: Enthält die Cache-Dateien des Verzeichnis-Cache
!Achtung: PHP benötigt Schreib-/Leserechte.

Cronjob einrichten

Für notwendige Wartungsarbeiten sollte die Datei cyclicmain.php in regelmäßige Abständen automatisiert aufgerufen werden. Auf Unix-Systemen stehen Ihnen hierfür in der Regel sog. Cronjobs zur verfügung, die eine Art Terminplaner darstellen. Wie genau ein solcher Termin erstellt wird, sagt Ihnen Ihr Webspaceprovider.

!Achtung: Unter Umständen sind zur Einbindung als Cronjob Änderungen am Skript erforderlich, wie z.B. die Angabe einer Shell. Auch zu diesem Thema sollte Ihnen Ihr Provider Auskunft geben können.

Die Zeitabstände zwischen zwei Läufen ist stark von der Nutzung des Marktes abhängig, wie z.B. die Anzahl der neuerstellten Anzeigen. Generell sollte der Zeitabstand zwischen 1 Stunde und 1 Tag liegen.

Folgende Aktionen werden vom Wartungsskript durchgeführt:

Cronjob beim Provider nicht verfügbar

Sollten Sie bei Ihrem Provider keine Möglichkeit haben einen Cronjob zu definieren, so können Sie haben Sie bei ClassAd eine Alternative. Setzen Sie in der Konfigurationsdatei inc/config.inc.php den Parameter $CRONJOB auf FALSE. Diese Lösung ist aber auf jeden Fall die schlechtere Möglichkeit, da einem zufälligen Benutzer die Rechnenzeit aufgebürdet wird, die Wartungsarbeiten auszuführen.

Technisch wird der periodische Ablauf dadurch gesteuert, dass innerhalb des Startseitenskripts ein Zufallsgenerator erzeugt wird, der jeden 1000sten (Standard) Abruf die Wartungsarbeiten durchführt. Die Wahrscheinlichkeit / Häufigkeit kann in der Konfiguraionsdatei durch den Parameter $MAINTAIN_PROBABILITY gesetzt werden und entspricht der Häufigkeit 1 : x (einmal in x Aufrufen) - je größer der Wert, desto seltener wird die Wartung durchgeführt.

RSS-Feed

Standardmäßig stellt ClassAd einen RSS-Feed zur Verfügung, der auf RSS in der Version 2.0 basiert. Im aktuellen Entwicklungsstand steht dieser Service allen Nutzern ohne weitere Authentifizierung zur Verfügung.

Erreichbar ist der Feed unter http://<IHRE.DOMAIN>/rssfeed.php.

Mit diesem Standardaufruf werden die zuletzt eingetragenen Anzeigen aus dem Markt in einer abgekürzten Version (max. 200 Zeichen pro Anzeige) zurückgeliefert. Die Anzahl der maximal berücksichtigten Datensätze können Sie in der Konfigurationsdatei inc/config.inc.php setzen - der entsprechende Parameter heisst RSS_MAX_COUNT.

In der Konfigurationsdatei sollten Sie auch die weiteren mit RSS_* beginnenden Parameter setzten. Sie legen fest, welchen Titel und welche Beschreibung Ihr RSS-Feed zurückliefern soll (z.B. "Mein kleiner Anzeigenfeed"). Wetierhin kann der RSS_TTL-Parameter gesetzt werden, er gibt vor, in welchem zeitlichen Abstand ein Newsreader Ihren Feed neu anfordert. Beachten Sie, dass dieses nur ein Vorschlag ist und keine verbindliche Reload-Sperre. Der Wert wird in Minuten angegeben.

Ein von ClassAd erzeugter RSS-kompatibler Feed sieht folgendermaßen aus:

<? xml version="1.0" ?>
< rss version =" 2.0 " >
	< channel > 
		< title > Mein kleiner Anzeigenmarkt </ title > 
		< link > http://www.xyz.com/classifieds/index.php </ link > 
		< description > Die neusten Anzeigen von www.xyz.de. Waren aller Art! </ description > 
		< generator > cts classAd 4.00 - www.projects-and-software.de </ generator > 
		< ttl > 60 </ ttl >
		< item > 
			< title > Das ist ein Anzeigentitel </ title > 
			< link > http://www.xyz.com/classifieds/showad.php?adid=24 </ link > 
			< description > Das ist der Anzeigentext </ description > 
			< pubDate > Tue, 10 Oct 2006 22:47:51 +0200 </ pubDate > 
		</ item >
	</channel >
</rss>

Speziellen RSS-Feed zur Verfügung stellen

Einer der Haupteinsatzmöglichkeiten von RSS zählt auch die lose Kopplung von Webseiten. So könnten Sie, z.B. als Anbieter eines Anzeigenmarktes für Haustiere, durchaus davon profitieren, wenn ein Anbieter einer Website für Katzen Ihre neusten Anzeigen einbindet und so Benutzer auf Ihre Webseite leitet.

Aus dem oben genannten Beispiel ergibt sich aber ein Problem: Die Katzen-Website möchte nur Anzeigen für Katzen anzeigen - keine von anderen Haustieren wie Hunden, Meerscheinchen oder Schlangen. Zur Lösung dieses Problems stellt ClassAd einen speziellen RSS-Feed zur Verfügung. Aufgerufen wird dieser durch:

http://<IHRE.DOMAIN>/rssfeed.php?feed=category_latest&cat=17&count=10

Dieser RSS-Feed stellt dem Aufrufer die letzten 10 Anzeigen (vgl. "count"-Parameter) aus der Rubrik mit der ID 17 zur Verfügung. Nutzen Sie das erweiterte Rubrikenmodell, so werden auf die Rubriken berücksichtigt, die im Rubrikenbaum unterhalb der gewählten Rubrik angesiedelt sind.

Um im Beispiel zu bleiben, könnte die Rubrik 17 "Katzen" genannt sein und die Unterrubriken "Hauskatze", "Perserkatze" und "Siamkatze" enthalten. Der Anbieter der Katzen-Website würde nun die neusten 10 Anzeigen aus allen genannten Rubriken erhalten.

RSS-Feed - generelle Hinweise

Gerade bei der Einbindung eines RSS-Feed in eine andere Webseite kann es zur Performanceproblemen auf Ihrem Webserver kommen, wenn die Daten beim Aufrufenden nicht zwischengespeichert / gecacht werden.

Zur Lösung dieses Problems hat es sich als gute Lösung erwiesen, dass der Aufrufende die XML-Rückgabe des Feeds in einer Textdatei auf seinem Webserver speichert. Bei erneuter Nutzung des Feeds kann nun auf diese lokale XML-Datei zurückgegriffen werden - erst wenn die XML-Datei ein gewisses Alter überschritten hat, wir ein neuer Aufruf beim RSS-Server gestartet. Dieses Caching sollte relativ einfach erstellbar sein.

Nachfolgende Versionen von ClassAd werden ein System enthalten, welches permanente ungechachte Anfragen erkennt und abblockt.