Chief-Banner V1.3.1 - Dokumentation

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

1 Einleitung

Chief-Banner ist eine in PHP geschriebene Funktionssammlung für das Einbinden von Werbebannern und Textlinks. Die zugehörigen HTML-Codes können an zentraler Stelle über Textdateien verwaltet werden. Zusätzlich lassen sich Werbemittel-Codes auch über HTTP-Requests beziehen, es werden dann die entsprechenden URLs angegeben. Ab Version 1.3 ist ein Mechanismus zum Cachen von Inhalten integriert, der Verzögerungen beim Seitenaufbau vermeidet.

Die Werbemittel werden formatiert ausgegeben. So lassen sich Banner z.B. automatisch mit einer Überschrift versehen oder in ein zentrierendes Element einbetten. Bei der Ausgabe von Textlink-Listen können Einträge durch einen beliebigen Separator getrennt werden.

Eine Bannerrotation ist durch das zufällige Auswählen von Werbemitteln zu realisieren. Sollen dabei mehrere Banner auf einer Seite angezeigt werden, kann die mehrfache Ausgabe desselben Banners verhindert werden. Alternativ ist auch die Einblendung wechselnder Meldungen (Message Of The Day) oder Bilder möglich.

Bei der vorliegenden Fassung handelt es sich um Version 1.3.1 vom 20.5.2006. Die jeweils aktuelle Version können Sie auf der Chief-Banner-Homepage herunterladen. Es wird PHP >= 4.3.0 mit cURL-Support benötigt. Das Skript wurde unter PHP 4.3.3, 4.3.10 und 5.1.2 mit den Laufzeit-Optionen register_globals off und allow_call_time_pass_reference off erfolgreich getestet.

Das Archiv enthält folgende Dateien:

LICENSE: Eine Kopie der GNU Lesser General Public License V2.1
LIESMICH.html: Die Datei, die Sie gerade lesen
chief-banner.php: Chief-Banner-Bibliothek

2 Funktionsweise

Die Ausgabe von Bannern oder Links gliedert sich in zwei Schritte: Dem Abholen der auszugebenen Inhalte und der Formatierung mit anschließender Ausgabe. Die Inhalte werden dabei als Arrays übergeben, welche durch zeilenweise organisierte Textdateien und über URLs geladen werden können. Zu diesem Zweck enthält die Datei 'chief-banner.php' folgende Funktionen:

chiefbanner_get_random_entries(&$entries, $count, $remove = true): Wählt aus einem Array eine anzugebende Anzahl von Einträgen zufällig aus, und gibt diese in einem weiteren Array zurück. Die ausgewählten Einträge können dabei aus dem originalen Array entfernt werden.
function &chiefbanner_get_random_strings_from_file($filename, $count): Wie oben, jedoch werden die Einträge aus einer Textdatei ausgelesen.
function &chiefbanner_get_url_contents(&$urls): Holt die Inhalte der in einem Array angegebenen URLs ab. Die Inhalte werden in einem Array zurückgegeben.
function &chiefbanner_get_url_contents_form_file($filename): Wie oben, jedoch werden die URLs aus einer Textdatei ausgelesen.
function &chiefbanner_get_cached_url_contents(&$urls, $cachename, $livetime): Arbeitet wie die Funktion chiefbanner_get_url_contents(), die Inhalte werden jedoch in der über $cachename angegebenen Datei zwischengespeichert und bei Bedarf auch wieder ausgelesen. Die Datei wird automatisch angelegt, und behält für die in $livetime angegebene Anzahl von Sekunden ihre Gültigkeit.
function &chiefbanner_format_entries(&$entries, &$count_out, $format = '%s', $separator = ' '): Formatiert die in einem Array übergebenen Inhalte, und gibt diese in einem String zurück. Auf jedem Eintrag wird dabei der Format-String (%s wird durch den Eintrag ersetzt) angewendet. Einträge werden durch den Separator voneinander getrennt.

Die Schlüssel der Einträge werden bei der Verarbeitung der Arrays jeweils beibehalten.

Zum Zweck der Abwärtskompatibilität sind noch folgende Funktionen enthalten, diese werden jedoch in zukünftigen Versionen evtl. entfernt:

print_random_string(&$strings, $format = '%s', $remove = true): Gibt einen zufällig ausgewählten Eintrag mit Hilfe des Format-Strings aus. Der ausgewählte Eintrag kann dabei aus dem Array entfernt werden.
print_random_string_from_file($filename, $format = '%s'): Wie oben, die Einträge werden jedoch aus einer Textdatei gelesen.
print_url_contents(&$urls, $format = '%s', $separator = ''): Gibt die Inhalte der in einem Array übergebenen URLs mit Hilfe des Format-Strings aus.
print_url_contents_from_file($filename, $format = '%s', $separator = ''): Wie oben, die URLs werden jedoch aus einer Textdatei gelesen.

3 Einrichtung

Kopieren Sie die Datei 'chief-banner.php' in ein Verzeichnis innerhalb Ihres PHP-Include-Pfades.

Erstellen Sie für jede Kategorie (z.b. Sidebar-Banner, Fullsize-Banner und Textlinks) eine Textdatei. Jede Zeile in diesen Dateien entspricht dabei genau einem Werbemittel. Tragen Sie die Werbemittel so ein, wie Sie diese auch in Ihre html-Datei einfügen würden (mit Tags etc.). Sollen HTML-Codes über HTTP-Requests eingelesen werden, so geben sie auf jeder Zeile eine URL an. Diese beiden Formen lassen sich allerdings nicht innerhalb einer Datei mischen.

Nun bereiten Sie einen Format-String vor, den Sie an geeigneter Stelle in Ihrer PHP-Seite zuweisen. Dieser gibt an, wie ein entsprechender Eintrag ausgegeben werden soll, und könnte für die Ausgabe einer Überschrift und der Einbettung in ein zentrierendes Element z.B. so aussehen:

$format = '<div align="center">Anzeige<br>%s</div>';

(%s wird dabei durch einen Werbemittel-Eintrag ersetzt)

Die Ausgabe eines Banners kann dann z.B. so erfolgen:

<?php

// Chief-Banner-Funktionen einbinden
include_once 'chief-banner.php';

// Format-String zuweisen
$banner_format = '<div align="center">Anzeige<br>%s</div>';

// Ein zufälliges Werbemittel aus der Textdatei 'banners' einlesen
$ent = &chiefbanner_get_random_strings_from_file('banners', 1);

// Dieses formatiert ausgeben
print chiefbanner_format_entries($ent, $cnt_out, $banner_format, '');

?>

Die Funktion chiefbanner_format_entries() gibt einen String zurück, der hier mit print ausgegeben wird. Die Variable $cnt_out enthält nach dem Aufruf die Anzahl der ausgegebenen Einträge. Es wird jeder Eintrag in dem Array $ent ausgegeben, leere Einträge werden jedoch übersprungen. Der letzte Parameter (hier ein leerer String) wird als Trenner zwischen mehreren Einträgen eingefügt.

3.1 Mehrere Bannner auf einer Seite

Möchten Sie mehrere Banner derselben Kategorie auf einer Seite anzeigen, kann es unerwünscht sein, das gleiche Banner mehrfach angezeigt werden. Um dies zu verhindern, müssen Sie wie folgt vorgehen:

<?php

// ...

// Textdatei 'banners' einlesen
$banners = file('banners');

// Einen zufälligen Eintrag aus $banners holen
$ent = &chiefbanner_get_random_entries($banners, 1, true);

// Diesen formatiert ausgeben
print chiefbanner_format_entries($ent, $cnt_out, $banner_format, '');

// ...

// Zwei weitere Einträge aus $banners holen
$ent = &chiefbanner_get_random_entries($banners, 2, true);

// ...und ausgeben
print chiefbanner_format_entries($ent, $cnt_out, $banner_format, '');

?>

Das zweite Argument von chiefbanner_get_random_entries() gibt die Anzahl der abzuholenden Einträge an. Das dritte, ob die ausgewählen Einträge aus dem $banners-Array entfernt werden sollen. Durch Angabe von true können diese dann kein zweites Mal angezeigt werden.

3.2 Linklisten

Das Skript läßt sich auch verwenden, um Linklisten (wie z.B. für Backlinks etc.) formatiert auszugeben. Dazu wird, analog zu oben beschriebenem Vorgehen, eine Textdatei mit HTML-Links angelegt.

<?php

// ...

// Textdatei 'links' einlesen
$links = file('links');

// Alle Einträge formatiert ausgeben
print chiefbanner_format_entries($links, $cnt_out, '%s', ' &middot; ');

?>

Hier wird als Separator zwischen den Einträgen jeweils ein Gregorianisches Komma ausgegeben.

3.3 Ausgabe von über URLs bezogenen Inhalten

Erstellen Sie bitte eine Textdatei mit einer URL in jeder Zeile. Die Inhalte dieser URLs können dann folgendermaßen ausgegeben werden:

<?php

// ...

// Einlesen der Textdatei 'urls' und Abholen der referenzierten Inhalte
$ent = &chiefbanner_get_url_contents_from_file('urls');

// ...und ausgeben
print chiefbanner_format_entries($ent, $cnt_out, $banner_format, '');

?>

Sollten die URLs bereits in einem Array vorliegen, dann kann zum Abholen der Inhalte auch die Funktion chiefbanner_get_url_contents() verwendet werden. Dieser wird ein Array mit URLs übergeben und gibt, wie die Funktion chiefbanner_get_url_contents_from_file() auch, ein Array mit den entsprechenden Inhalten zurück.

Das Nachladen von Inhalten aus dem Netz kann zu einer spürbaren Verzögerung beim Seitenaufbau führen. Um diesen Effekt zu vermeiden, können die Inhalte lokal gecachet werden:

<?php

// ...

// Textdatei 'urls' einlesen
$urls = file('urls');

// Abholen der referenzierten Inhalte
$ent = &chiefbanner_get_cached_url_contents(
	$urls, 'cache/cached-url-contents', 10*60*60);

// Ausgabe der Inhalte
print chiefbanner_format_entries($ent, $cnt_out, $banner_format, '');

?>

Die Inhalte der URLs werden in der Datei 'cache/cached-url-contents' zwischengespeichert. Sollte die letzte Akualisierung dieser Datei mehr als zehn Stunden zurückliegen, so werden die Inhalte aus dem Netz nachgeladen und erneut abgelegt. Ein sofortiges Nachladen kann durch das Löschen der Cache-Datei erzwungen werden. Beachten Sie bitte, das der Webserver Schreibrechte für das Verzeichnis 'cache' haben muß, damit die Cache-Datei angelegt werden kann.

4 Änderungen zu Vorversionen

V1.3.1

Ein Bug in der Funktion chiefbanner_get_url_contents() in Verbindung mit PHP 5 wurde behoben

V1.3

Die Funktion chiefbanner_get_cached_url_contents(() wurde hinzugefügt

5 Kontakt

Aktuelle Informationen finden Sie auf der Chief-Banner-Homepage. Wenn Sie Fragen zu dem Skript stellen oder einen Kommentar abgeben möchten, können Sie dies im Chief-Banner-Forum tun. Bitte geben Sie bei Problemen immer die verwendeten PHP- und Skript-Versionen an!

Bitte unterstützen Sie die Entwicklung weiterer, frei verfügbarer Skripte durch das Setzen eines Links zu http://www.internalscripts.de. Vielen Dank!

Anschrift des Autors

Carsten Meier
Under de Diek 19
D-26757 Borkum
Deutschland

Website: Internal Scripts - PHP-Skripte
E-Mail: [cm at internalscripts dot de]

Fragen zur Benutzung des Skripts bitte im Forum stellen!