KB message

Aus Kitbooth Wiki: Deutsch

(Unterschied zwischen Versionen)
Wechseln zu:Navigation, Suche
(Die Seite wurde neu angelegt: „== Funktionalität == Die Klasse '''KB_message''' nimmt Erfolgs- und Fehlermeldungen auf, gibt diese aufbereitet wieder aus und lässt sich für die…“)
(Funktionalität)
Zeile 1: Zeile 1:
-
== Funktionalität ==
+
== Beschreibung ==

Version vom 18. März 2012, 10:02 Uhr

Inhaltsverzeichnis

Beschreibung

Die Klasse KB_message nimmt Erfolgs- und Fehlermeldungen auf, gibt diese aufbereitet wieder aus und lässt sich für die Fehlerabfrage benutzen. Dabei werden dem Entwickler alle Einträge angezeigt. Allen anderen Benutzergruppen werden nur eine generelle Nachricht über Erfolg oder Misserfolg einer Operation ausgegeben.

Verwendung

KB_message wird in Kitbooth im Allgemeinen nur einmal instanziert. Dies geschieht bereits in der Core-Funktionalität, steht also jederzeit zur Verfügung. Im globalen Kontext steht die Instanz in der Referenz $msg zur Verfügung. Um die Instanz in einer Klasse oder Funktion zu nutzen, muss diese mit der Funktion $kbc->msg_o() importiert werden.

Manche Klassen und Funktionen nutzen KB_message bereits völlig autark oder können mit zusätzlichen Parametern dazu aufgefordert werden. Zum Beispiel meldet jede datenverändernde Funktion der Klasse KB_db im Falle einer übergebenen Meldung den Status der letzten Datenbankoperation an die KB_message Instanz.

Klasse DB - Nutzung der Message Funktionalität

Beispiel

Meldung wird nicht erzeugt

  $db->sql_query('UPDATE '.DB_PREFIX.'kb_table SET value="1"');

Meldung wird erzeugt

  $db->sql_query('UPDATE '.DB_PREFIX.'kb_table SET value="1"', 'UPDATE kb_table');

Ausgabe (Zeitpunkt - Meldung - SQL Statement):

  0.01 - UPDATE kb_table - UPDATE kb_table SET value="1"

Eingabefunktionen

Die Funktion zum Setzen einer Meldung KB_message::set() erwarten mindestens den Parameter $value. Er wird als Boolean erwartet oder in ihre Entsprechung in true|false umgewandelt. Dabei stellt false einen Fehler dar, true einen erfolgreichen Vorgang. Der Wert wird unverändert als Return zurückgegeben, so dass die sich Funktionen zum pipen eignen (siehe Anwendungsbeispiele). Der Parameter $message sollte eine eindeutige Beschreibung des Vorgangs enthalten.

set()

function set($value, $message=false, $keywords=false){}
Die Auswertung des Parameters $value (true|false) bestimmt, ob es sich um eine Erfolgs- oder Fehlermeldung handelt. Der Parameter $message enthält die zu setzende Meldung. Mit dem optionalen Parameter $keywords können weitere Eigenschaften übergeben werden.

$msg->set(true, "Vorgang war erfolgreich");
$keywords

NOTICE
Das Keyword NOTICE bestimmt, dass der Fehler nicht fatal ist. Die Meldung gibt zwar den Fehler aus, verändert aber nicht den Gesamtstatus aller Meldungen.

$msg->set(false, "nicht kritischer Fehler bei Vorgang", "NOTICE");

set_info()

function set_info($true, $false){}
Die Funktion set_info() kann für einzelne Vorgänge Meldungen setzen. Sie muss zum passend letzten set() Aufruf erfolgen, da die Meldung explizit für diesen Eintrag gesetzt wird. Der Parameter $true enthält dabei die Meldung für einen Erfolg, $false die Meldung für einen Fehler. Die Meldungen über set_info() werden ausschließlich Benutzern der höchsten Stufe angezeigt.

$msg->set_info("Der Vorgang war erfolgreich.", "Der Vorgang war nicht erfolgreich.");

set_main_message()

set_main_message($true, $false){}
Die Funktion set_main_message() setzt eine Meldung, welche allen Benutzern nach Abschluss aller Vorgänge angezeigt wird. Da es nur eine main_message gibt, wird durch einen erneuten Aufruf der vorherige überschrieben. Der Parameter $true enthält dabei die Meldung für einen Erfolg, $false die Meldung für einen Fehler.

$msg->set_main_message("Der Vorgang wurde erfolgreich abgeschlossen.", "Der Vorgang konnte nicht erfolgreich abgeschlossen werden.");

Ausgabefunktionen

Die verschiedenen Ausgabefunktionen beinhalten die Ausgaben fertig generierter Blöcke HTML-Markup, das Meldungs-Array, sowie der Boolean mit dem Gesamtstatus.

get_html()

Die Funktion get_html() generiert aus den Meldungen fertigen HTML-Markup, wobei Fehler die CSS-Klassen message und red besitzen, Erfolgsmeldungen die CSS-Klassen message und green. Im Backend erfolgt der Aufruf dieser Funktion für die Ausgabe bereits.

$msg->get_html();

get_message()

Die Funktion get_message() gibt das Array von KB_message zur Weiterverarbeitung zurück.

$array = $msg->get_message();

get_info()

Die Funktion get_info() gibt das Array der mit set_info() gesetzten Meldungen von KB_message zur Weiterverarbeitung zurück.

$array = $msg->get_info();

get_main_message()

Die Funktion get_main_message() gibt das Array der mit set_main_message() gesetzten Meldungen von KB_message zur Weiterverarbeitung zurück.

$array = $msg->get_main_message();

get_status()

Die Funktion get_status() gibt den aktuellen Gesamtstatus als Boolean (true oder false) zurück.

if($msg->get_status()){
}

Anwendungsbeispiele

Meldung setzen und abrufen

Generelle Meldung setzen

$msg->set_main_message("Es hat alles geklappt", "Es ist leider ein Fehler aufgetreten");

Vorgang 1 war erfolgreich

$msg->set(true, "Vorgang 1");

Vorgang 2 war nicht erfolgreich, ist aber kein kritischer Fehler

$msg->set(false, false, "Vorgang 2");

Abrufen der Meldungen im HTML Block

$msg->get_html();

Ausgabe Entwickler (Verarbeitungszeit - Meldung):

0.041 - Vorgang 1
0.073 - Vorgang 2
(Es hat alles geklappt)

Ausgabe Anwender:

 Es hat alles geklappt

Rückgabewerte als Parameter für set() nutzen

In diesem Aufruf wird $msg->set die Rückgabe der Funktion get_somevalue() übergeben. Angenommen diese liefert ein Array zurück, wird durch Typumwandlung in $msg->set() daraus ein true also Erfolg. Durch den unveränderten Return von $value wird das Array dann $val zugeordnet und die IF-Schleife wird wahr. Daher wird das Array mit print_r() ausgegeben. Sollte die Rückgabe von get_somevalue() ein leeres Array sein, wird auch $value ind $msg->set() als false erkannt und entsprechend ein Fehler registriert.

 if($val = $msg->set( $class->get_somevalue() , 'Hole somevalue von class' )){
   print_r($val);
 }

Statusabfrage bei der Verarbeitung nutzen

Beispielhafte Verarbeitungsabfolge:

 $db->sql_query($sql, 'Meldung - INSERT ...');
 $db->sql_query($sql, 'Meldung - DELETE...');
 $fs->create_file($file);
 if($var == true){
   $msg->set(true, "Die Variable $var ist true");
 }

Die obigen Funktionen registrieren selbstständig ihre Meldungen bei KB_message, daher kann zu einem beliebigen Zeitpunkt den Gesamtstatus abfragen und entsprechend reagieren.

 if($msg->get_status()){
   echo "Ausgabe bei erfolgreicher Abarbeitung."
 {
 else{ echo "bitte nochmal versuchen." }

Zusätzliche Meldungen für Anwender ausgeben

Beispielhafte Verarbeitungsabfolge:

 $fs->create_file($file);

Die obige Funktion registriert selbstständig ihre Meldungen bei KB_message. Wenn dem Benutzer vom Status dieser Meldung gesondert berichtet werden soll, kann man folgende Funktion verwenden.

 $msg->set_info("Die Datei wurde erfolgreich erstellt.", "Es trat ein Fehler bei der Dateierstellung auf.");

Ausgabe Entwickler (Verarbeitungszeit - Meldung):

0.041 - create_file Datei anlegen file.txt
(Die Datei wurde erfolgreich erstellt.)
(Es hat alles geklappt)

Ausgabe Anwender:

Die Datei wurde erfolgreich erstellt.
Es hat alles geklappt
Navigation
Werkzeuge