Entwickler Referenz ilchClan 1.1 I

0. Inhalt

1. Einleitung
2. Funktionen
1. bbcode
2. Datenbank
3. eMail
4. Rechte
5. Weiterleitung
6. Smilies
7. escape / unescape
8. sendpm
3. Klassen
1. Design
2. Templates
3. Menu
4. XAJAX (externer Link)
4. Module
5. Ordner Struktur

1. Einleitung

oben

In dieser Dokumentation will ich versuchen einen mini-Überblick über ilchClan 1.1 zu geben. Es sollen die wichtigsten Funktionen und Klassen kurz beschrieben und eine mini-Anleitung für Modulautoren gegeben werden.

2. Funktionen

oben

1. bbcode

oben

bbcode - ersetzt in einem gegebenen Text bbcode-Tags durch HTML-Tags.

Beschreibung:

bbcode (string text [, maxlength int])

Gibt den bearbeitetet Text zurück. Der erste Parameter ist der Text der bearbeitet werden soll, der 2. Parameter ist freiwillig, damit kann bestimmt werden wie lang ein String im übergebenen Text maximal sein darf. Standardmäßig sind das 40 Zeichen.

2. Datenbank

oben

Es gibt eine Reihe von Funktionen die für den Datenbankzugriff zuständig sind und unbedingt benutzt werden sollten. diese Funktionen fangen alle mit db_ an und sind meist nur Aliase für die mysql Funktion. Warum die db_ und nicht direkt die mysql_ Funktion nutzen?

1. weil die Funktion db_query automatisch den String prefix_ in einem übergebenen Query durch das Prefix der Installation ersetzt
2. weil durch die db_ Funktionen theoretisch auch andere Datenbanken wie z.B. postgres.. angesprochen werden könnte. Dafür gibt es bis jetzt zwar noch keine entsprechende Datei, dies könnte aber spielend leicht gemacht werden.
3. weil die db_query Funktion, Fehler ordentlich ausgibt

Jetzt noch eine Liste der Funktionen mit einer kurzen Erklärung.

db_connect	erwartet keinen Parameter sie holt die Daten aus der config.php und stellt die Verbindung her und wählt die Datenbank aus!
db_close	erwartet keinen Parameter, sie schließt die Datenbank Verbindung
db_query	erwartet den Querystring also db_query($abfrage); in diesem Querystring ersetzt die Funktion den Platzhalter prefix_ durch den aktuellen DBPREF in der config.php daher muss man um die Tabelle User richtig abzufragen also nur: db_query("SELECT * FROM prefix_user WHERE name = 'xyz'"); schreiben.
db_result	wie mysql_result, mit Standardwerten 0 für row,field
db_fetch_assoc	wie mysql_fetch_assoc
db_fetch_row	wie mysql_fetch_row
db_fetch_object	wie mysql_fetch_object
db_num_rows	wie mysql_num_rows
db_last_id	wie mysql_insert_id gibt die zuletzt eingetragene ID zurück
db_count_query	erwartet als Übergabe eine Abfrage die etwas Zählt. kann aber auch für andere Dinge missbraucht werden :-)
db_make_sites	diese Funktion sollte wie folgt aufgerufen werden: db_make_sites ($page ,$where ,$limit ,$link ,$table); sie gibt eine Liste mit den Seiten zurück.

3. eMail

oben

wenn mit dem Script eMails geschrieben werden müssen bitte IMMER die Funktion icmail() nehmen. Die Parameter der Funktion werden speziell geprüft, besser als bei der Standard php-Funktion mail() bei der die Parameter überhaupt nicht geprüft werden.

icmail ($mail,$betreff,$text [, $from] [, $html])

$mail = eMail-Adresse an die diese eMail geschickt werden soll.
$betreff = Betreff der eMail
$text = Text/Body der eMail
$from = ein String mit z.B. Name <mail> (Optional)
$html = true/false gibt an ob es eine HTML- oder Text-Mail sein soll (Optional - Standard Text)

4. Rechte

oben

auch hier bitte immer die Funktion des Scripts zum prüfen nutzen! Es gibt einige Funktionen zum prüfen.

has_right ($recht [, $modul])
mit der Funktion has_right kann geprüft werden ob der aktuelle User das Recht ($recht) hat oder das Modulrecht $modul wobei das Modul also der 2. Parameter nicht angegeben werden muss.

is_admin ()
prüft ob der aktuelle User Adminrechte hat

is_coadmin ()
prüft ob der aktuelle User CoAdmin oder Administ

is_siteadmin ( [$modul] )
prüft ob der aktuelle User SiteAdmin, CoAdmin oder Admin ist, oder das Modulrecht $modul hat. Auch hier ist die Angabe eines Modules freiwillig.

user_has_admin_right ($menu [, $sl])
diese Funktion prüft ob der aktuelle User Admin oder CoAdmin ist oder ob er ein Modulrecht hat, kurz ob der User berechtigt ist in den Adminbereich zu gehen. Diese Funktion bitte nicht anstatt is_admin() verwenden. Sie prüft wirklich ob der User in den Adminbereich darf, nicht ob er Admin ist. Der erste Parameter ist das aktuelle $menu Objekt das ist eigentlich überall verfügbar muss also nur angegeben werden. Der zweite Parameter ist standardmäßig auf true was bedeutet, ist der User nicht berechtigt in den Adminbereich zu gehen und nicht eingeloggt wird ihm ein Loginformular angezeigt. Ist dieser zweite Parameter auf false wird kein Loginformular angezeigt wenn der User nicht berechtigt ist. Sondern nur false zurückgegeben.

5. Weiterleitung

oben

wd ($link, $text [, $zeit ] );

Diese Funktion gibt den Text mit dem Link $link darunter aus und leitet auf den Link $link in $zeit (Standard 3 Sekunden) weiter. $link kann (muss aber nicht) ein Array sein das dann wie folgt aufgebaut sein soll, automatisch wird dann zu dem 1. link weitergeleitet.
array (
'link text' => 'link',
'link text 2' => 'link2'
);

6. Smilies

oben

getsmilies()

ohne Parameter gibt die komplette Liste aller Smilies als String zurück.

7. escape / unescape

oben

diese Funktionen sollten auf Strings vor dem Eintragen in eine Datenbank und nach dem Auslesen aus einer Datenbank angewendet werden. Auch hier gibt es einige Funktionen für alles weitere einfach mal in die Datei include/includes/func/escape.php schauen.

escape ($string, $typ)

mögliche Typen sind: "integer","string","textarea"

unescape($string);
entfernt mögliche Slashes wieder.

8. sendpm

oben

diese Funktion hilft beim Versenden von Kurznachrichten über das integrierte System

sendpm ($sid,$eid,$betreff,$text,[$status])

$sid = Userid des Senders
$eid = Userid des Empfängers
$betreff = Betreff der eMail
$text = Text/Body der eMail
$status = Status über Zustand (gelesen/gelöscht)

-1	Posteingang des Empfängers/gelöscht beim Sender
0	Posteingang des Empfängers/Postausgang beim Sender (Standard)
1	gelöscht beim Empfänger/Postausgang beim Sender

2. Klassen

oben

1. Design

die Klasse wird in jeder Datei aufgerufen , sie generiert aus den Design Ordnern der gerade aktiv ist das Design und das Menü. So wird es gemacht ;)

$design = new design ( $titel, $menu [, $welche] [, $seite] );

Die Parameter $title und $menu sind Pflicht sie geben einmal den $title der Seite an und einmal das Horizontale $menu. Mit $welche ist gemeint welche Index Datei genommen werden soll. Dort gibt es folgende Möglichkeiten:
1. die Standard Index Datei des aktuelle aktiven Designs hierfür einfach eine 1 eingeben (default)
2. die small_index.htm im Templates Ordner hierfür einfach eine 0 angeben.
3. die index.htm für den Adminbereich hierfür einfach eine 2 angeben.
Dann gibt es noch den Parameter $seite damit kann eine eigene Index Datei für dieses Modul festgelegt werden. Hier kann also einfach ein relativer Pfad ausgehend von der index.php angegeben werden. Wenn diese Datei nicht gefunden wird ,wird die Datei genommen die mit $welche angegeben wurde. Am besten man macht es so wie in allen Foren Dateien gezeigt wird. Dort wird eine index.htm aus dem Ordner include/templates/forum/ genommen. Weil immer die Template Datei aus dem aktuelle aktiven Design genommen werden, kann man so pro Design spezielle index.htm Dateien angeben siehe dazu mehr unter Template klasse.

NEU: Bevor man das Design mit header() benutzt kann man mit addheader() noch Informationen im Kopf des Designs einfügen
$design->addheader('<script type="text/javascript" src="javascript.js"></script>'); Zusätzlich wird die globale Variable $ILCH_HEADER_ADDITIONS während header() auch in den Kopf eingebunden.
Wenn man die Variable ändert, sollte man darauf achten sie nicht zu überschreiben, sonder nur zu erweitern.

Der Header des Designs wird dann mit:
$design->header();
ausgegeben und der footer mit:
$design->footer();
wobei beim Footer eine 1 übergeben werden kann, damit das Script direkt nach der Ausgabe des Footers abbricht.

2. Templates

oben

diese Klasse dient dazu ein Template zu parsen. generell mal liegen alle Templates im Ordner include/templates und davon geht diese Klasse auch aus weiterhin geht die Klasse auch davon aus das alle Templates die Endung .htm haben daran bitte halten!! Beim eröffnen einer Klasse kann man aber durch den zweiten freiwilligen Parameter angeben das das Template im Ordner include/admin/templates liegt, das bietet sich für den Adminbereich an ;-) Die Klasse versuch schlau zu sein und schau immer zuerst im aktuelle aktiven Design nach ob es dort einen Ordner templates gibt in dem die angeforderte Datei evtl. drin ist. Wenn die Datei in diesem Ordner ist dann wird sie daher genommen, obwohl sie auch unter include/templates liegt. Als kleines Beispiel nehmen wir mal die gbook.htm für das Gästebuch.

Normalerweise liegt diese Datei im Ordner include/templates/gbook.htm Außerdem kann ich sie aber unter include/designs/MEINDESIGN/templates/gbook.htm legen und wenn ich jetzt die Datei gbook.htm über das Templatesystem anfordere wird er die in MEINDESIGN nehmen. Hoffe das ist so klar geworden :-)

eine neue Klasse wird aufgemacht mit:

$tpl = new tpl ( 'dateiname' );

eine Datei in einem Unterordner z.b. dem Admin Ordner also include/templates/admin steuert man so an:

$tpl = new tpl ( 'admin/dateiname' );

das .htm kann muss man aber nicht angeben ;)

Es gibt noch einen 2. optionalen Parameter, der angibt wo sich die Templatedatei befindet oder ob man das Template direkt als Variable übergibt.

0	Datei wird in include/templates/ gesucht (Standard)
1	Datei wird in include/admin/templates/ gesucht
2	Datei wird in include/ gesucht
3	Es wird direkt der Inhalt der ersten Variable als Template verwendet

Methoden der Klasse TPL

Folgende Methoden stehen nachdem einlesen starten des Templates zu Verfügung um das Template zu verarbeiten und auszugeben.

out($abschnitt)	diese Funktion gibt den $abschnitt des Templates mit echo sofort aus.
get($abschnitt)	diese Funktion gibt den $abschnitt des Templates zurück, er kann also noch weiter verarbeitet werden.
del_ar($ar)	diese Funktion löscht Keys die sonst ersetzt werden würden, (eher unwichtige funktion)
del($k)	löscht einen Speziellen Key da diese aber z.b. in einer Schleife überschrieben werden ist das eher egal
set_get($key,$value,$abschnitt)	diese Funktion setzt ein Key mit dem entsprechend Wert ($value) und gibt den Abschnitt $abschnitt zurück.
set_ar_get($ar,$abschnitt)	diese Funktion setzt alle im array enthaltenden Keys und gibt dann den Abschnitt $abschnitt zurück
set_out($key;$value,$abschnitt)	diese Funktion ist wie set_get() nur das set_out() den Abschnitt $abschnitt direkt mit echo ausgibt
set_ar_out($ar;$abschnitt)	wie set_ar_get() nur das set_ar_out() den Abschnitt $abschnitt sofort mit echo ausgibt
set($key,$value)	setzt einen Key mit $key, und als Wert $value
set_ar($ar)	setzt alle in dem Array enthaltenden Keys und deren Werte als Keys
list_out($key,$ar)	gibt eine Liste mit echo aus, dabei ist $key der Name der Liste und in dem Array müssen in der Rheinfolge der Prozentzahlen in der Liste die jeweiligen Werte stehen. Weiteres zu Listen in einem Template un zum Aufbau findest du weiter unten.
list_exists($name)	gibt TRUE zurück wenn die Liste existiert und FALSE wenn das nicht der Fall ist.
list_get($key,$ar)	Funktioniert wie list_out nur das die Liste zurückgegeben wird und nicht mit echo ausgegeben.

Der Aufbau eines Templates

Dieses Template muss man jetzt erst mit $tpl = new tpl ( 'diese_template' ); einlesen und dann kann man es auf folgende Arten richtig ausgeben. der Platzhalter {name} soll durch meinen Namen (Max Mustermann) ersetzt werden.
$tpl->set('name', 'Max Mustermann');
$tpl->out(0); oder
$tpl->set_out('name', 'Max Mustermann', 0);
oder:
$tpl->set_ar( array( 'name' => 'Max Mustermann' ) );
$tpl->out(0);
oder
$tpl->set_ar_out( array( 'name' => 'Max Mustermann' ) , 0 ); gibt evtl. noch ein paar andere Kombinationen aber das sollte reichen :P...

Beispiel

mal ein etwas komplizierteres Template

wieder mit $tpl = new tpl ( 'dieses_template' ); das Template einlesen. jetzt ist noch ein 2. Abschnitt hinzugekommen und in diesem Abschnitt gibt es 2 Platzhalter. ich gebe hier mal eine Möglichkeit das Template richtig auszugeben...

$tpl->set('name', 'Max Mustermann');
$tpl->out(0);

... weiterer PHP-Code
$ar = array(
  'script' => 'ilchClan',
  'version' => '1.1'
);

$tpl->set_ar_out($ar, 1);

so jetzt ist alles draußen *g*... und ersetzt es gibt wie gesagt Unmengen an Möglichkeiten das Template zu parsen und dann auszugeben.

Beispiel mit Liste

Jetzt noch ein letztes Beispiel mit einer Liste in einem Template das ist wirklich auch sehr leicht.

so jetzt also alle Member dieses Clans ausgeben in der Liste hat es 2 Platzhalter %1 und %2... und die Liste heißt "alleMember"

$tpl->set('version', '1.0.5');
.... jetzt die Liste generieren

$abf = 'SELECT * FROM prefix_users WHERE recht = -3'; // -3 ist Member recht

$erg = db_query($abf);
while($row = db_fetch_assoc($erg)) {
  $liste .= $tpl->list_get( 'alleMember', array ( $row['id'], $row['name']));
}

$tpl->set('alleMember', $liste );
$tpl->out(0);

so damit wären alle Member ausgegeben in einer select box... aber was genau ist da passiert :P
also zuerst mal wird der Platzhalter Version gesetzt das kennen wir ja schon

dann wird eine Abfrage gemacht und zwar alle Member aus der Datenbank, jetzt holen wir die Liste alleMember und übergeben ein Array der Wert der in diesem Array an 1 stelle Steht ersetzt den Platzhalter %1 in der Liste der Wert an 2. Stelle den 2. Platzhalter usw.

dann wird die Liste 'alleMember' noch gesetzt und ausgegeben.

warum gibt es denn den Platzhalter alleMember in dem Template wenn der doch gar nicht gesetzt wurde?
ja stimmt, es wird erstmal die Liste eingelesen und in der Klasse gespeichert und dann wird dort wo die Liste stand der Platzhalter eingetragen ,so dass man ihn verwenden kann.

Platzhalter für Ersetzungen aus dem Sprachfile

als Letzt möchte ich noch ganz kurz auf Sprachfiles eingehen und zwar parsed die template Klasse automatisch Platzhalter nach folgendem Muster:

{_lang_langkey}

die Zeichenfolge "langkey" muss jetzt in der Datei include/includes/lang/de.php (oder en.php, fr.php usw. ) halt drin stehen nach Vorbild... also:

'langkey' => 'dies ist ein languages key',
usw. einfach mal die .de datei ansehen ;)...

NEU: Bedingungen in Templatedateien

Es gibt auch die Möglichkeit direkt Bedingungen in Templatedateien zu verwenden (seit 1.1 D), dabei folgende Syntax.
{_if_{variable}=='wert'}Bei richtiger Bedingung{/_endif}
oder die lange Form (seit 1.1 I)
{_if_{variable}=='wert'}Bei richtiger Bedingung{_else_}Bei falscher Bedingung{/_endif}
Die Variable sollte mit set() oder einem Äquivalent gesetzt sein oder SESSION_AUTHRIGHT lauten, was automatisch durch $_SESSION['authright'] ersetzt wird.
Als Vergleichsoperatoren sind bis 1.1I ==,!=,<>,>=,<= möglich, ab 1.1I dann zusätzlich noch > und <.

3. Menu

oben

das Menu-Objekt enthält die Parameter der Adresszeile in der Reihenfolge wie sie angegeben wurden. Es ist nicht vorgesehen normale PHP-Parameter zu benutzen. Sondern immer über dieses Menu-System zu laufen. Die wichtigste Funktion ist hier die get()-Methode. Direkt mal ein kleines Beispiel:

Du programmierst ein neues Modul es heißt Membermap und die .php Datei liegt im Ordner include/contents diese Datei wird jetzt aufgerufen über:

index.php?membermap

der erste Parameter ist also Membermap. Um jetzt weitere Parameter zu übergeben geht man einfach so vor:

index.php?membermap-insert-1-2

um an den String Membermap zu kommen muss man jetzt aufrufen:

$menu->get(0);

für "insert":

$menu->get(1); usw.

if ($menu->get(1) == 'insert') { echo 'Es wurde etwas eingetragen'; }

so oder so änlich könnte es gehen ;-)...
es gibt dann noch die Funktionen getA und getE wobei getA das ersetze Zeichen des Parameters der gefordert wurde zurückgibt und getE alles nach dem ersten Zeichen ich habe diese Funktionen verwendet um z.B. folgendes zu machen:

String:

index.php?membermap-p2

if ($menu->getA(1) == 'p') {
  $page = $menu->getE(1);
}
echo $page;
würde jetzt 2 ausgeben. ;-) zu beachten ist noch das getE ein Intervall auf den Rückgabewert anwendet also den Rückgabewert in eine Zahl umwandelt.
Vielleicht einfach mal mit der Klasse ein paar Minuten spielen, sollte aber einigermaßen klar sein hoffe ich.

NEU: Alle Funktionen an index.php?membermap-insert-p1-2 gezeigt.

Funktionsaufruf	Rückgabewert
get(0)	membermap
getA(2)	p
getE(2)	1
NEU: getE('p')	1
NEU: getN('membermap')	insert
NEU: exists('insert')	true

4. Module

oben

dafür ist die Tabelle "modules" Zuständige diese Tabelle hat folgende Felder

id

eindeutig, wird automatisch hochgezählt. Bitte beim Eintragen auch automatisch hochzählen lassen!

url

Name der Datei im Ordner include/admin/

name

Name des Modules der im Adminbereich angezeigt wird.

gshow

wird es für den User im Admin Menü angezeigt (0 nein, 1 ja)

ashow

wird das Modul als Link im Admin Menü angezeigt für den Admin (0 nein, 1 ja)

fright

kann man dafür Modulrechte vergeben (0 ja, 1 nein)

wenn also ein Modul eines der Aktionen machen soll dann muss es in diese Tabelle eingetragen werden.

Bitte bei einem eigenen Modul darauf achten das diese Referenz beachtet wird und im Zweifel evtl. kurz fragen bevor man eine Funktion doppelt schreibt ;-) also immer die vorhandenen Funktionen nutzen wenn möglich. Ansonsten auch an die Ordnerstruktur halten die in dieser Referenz beschrieben wird.

Wenn ein Module es zulässt also nur kleine Änderungen erforderlich sind bitte eine Anleitung schreiben was der User in welcher Datei ändern soll und zusätzlich die geänderten Dateien beilegen. Wenn ein großes Modul erstellt werden soll bitte kein bestehendes Modul einfach ändern sondern wirklich ein neues schreiben, z.B. also eine große Erweiterung für das Forum, hier sollte dann optimaler weise einfach eine aktuelle Kopie der Forumdateien gemacht werden und diese mit neuem Namen neu erstellt werden also meinForum usw. und in diesem neuen Forum dann die Erweiterung durchführen. So bleibt ausgeschlossen das sich Modulautoren in die Quere kommen.

Bei kleinen Änderungen bitte die Anleitung wie für phpbb beschrieben wird benutzten.

http://www.phpbb2.de/kb.php?mode=article&k=11

ich denke so ein Vorgehen ist sehr gut und vor allem schön einheitlich!

Module für 1.1 werden geprüft bevor sie freigeschaltet werden. Unbedingt an diese Regeln halten und bei Unklarheiten unbedingt nachfragen!!

5. Ordner Struktur

oben

wie ist das Script aufgebaut? Folgendermaßen:

include/

hier liegen nur die Weiteren Ordner drin. Keine Dateien Keine eigenen Ordner!

include/backup

hier liegt BigDump, was zum Rückspielen von Backups benutzt werden kann, außerdem werden Backups hier gespeichert, wenn ausgewählt

include/contents

hier liegen alle Dateien für den Content drin, sobald mehr als eine Datei für ein Modul benötigt wird werden die Dateien in einen Modulordner im Ordner include/contents gelegt. Siehe Forum Modul.

include/admin

hier liegen alle Dateien für den Adminbereich die Dateien sollten so heißen wie die zugehörige Datei im contents Ordner. Alle Templates für den Adminbereich liegen im Ordner include/admin/templates Auch hier gilt. Hat ein Modul mehrere Templates bitte einen Ordner dafür anlegen. Die Templates Dateien sollten gleich heißen.

include/templates

hier liegen alle Templates Ordner für den Contentbereich und für die Boxen die Dateien sollten mit Ausnahme der Endung gleich heißen wie die Datei im content Ordner

include/boxes

hier liegen alle Dateien für die Boxen.

include/designs

hier liegen alle Designordner bitte keine Dateien oder ähnliches hier ablegen nur die Ordner der Designs. Siehe zur genauen Beschreibung die Design Dokumentation

include/downs

bzw. include/downs/downloads dieser Ordner ist für Downloads reserviert, hier können weitere Ordner für andere Download Module angelegt werden. der Ordner

include/downs/downloads

ist für das download-Modul.

include/includes/class

hier werden Klassen die eingefügt werden sollen reingelegt.

include/includes/func

hier sind alle Funktionen drin, für größere Funktionen oder Funktionsgruppen bitte eine eigene Datei anlegen. Auch für eigene Module bitte eine eigene Funktionsdatei anlegen wenn benötigt.

include/includes/js

hier sind alle Javascript Dateien die für das Script benötigt werden zu finden.

include/includes/lang

hier liegen alle Sprachdateien

include/images

für Bilder sollte selbsterklärend sein, für eigene Bild hier bitte einen neuen Ordner anlegen!