Hilfe beim Entwickeln von neuen Modulen

Ein neues Modul erfordert mindestens eine Datei, welche im Ordner inc/modules/NAME_DES_MODULS angelegt werden muss.
Die Datei selber muss den Namen mod_NAME_DES_MODULS.php tragen.

Bitte achten Sie darauf, dass der Name des Moduls durchgehend klein geschrieben ist und keine Leerzeichen enthält.

Zum Beispiel für das Modul headline liegt die Datei hier:

inc/modules/headline/mod_headline.php

In dieser Datei müssen zwei Funktionen enthalten sein.
Einmal die Funktion mod_headline_out und mod_headline_in.
Ersetzen Sie headline durch ihren Modulnamen.

Beispieldatei inc/modules/headline/mod_headline.php

<?php

function mod_headline_out($article = array()) 
{
	return '<'.$article['val6'].'>'.$article['val1'].'</'.$article['val6'].'>';
}


function mod_headline_in()
{
	require_once(PATHTOMAINDIR."inc/modules/headline/FormModHeadlineIn.php");
	$form = new FormModHeadlineIn;
	include_once(PATHTOMAINDIR."inc/user/snippets/set_modul_in_vars.php");
	include_once(PATHTOMAINDIR."inc/user/snippets/set_modul_in_formvars.php");
	return $form->output();	
}

?>

function mod_headline_in()

Möchte der Benutzer einen neuen Artikel anlegen und wählt hierfür das Modul headline, dann wird die function mod_headline_in() aufgerufen.
Diese Funktion sollte also das Formular mit den Daten enthalten, die für die Nutzung des Moduls erforderlich sind.
Beim Modul headline ist dies die Art der Überschrift (h1-h4) und der Name der Überschrift.

Die Art der Überschrift wird in der Datenbank unter val6 gespeichert und der Name der Überschrift unter val1.
Grundsätzlich stehen die Felder val1-val20 zur Verfügung.
Da die Felder val1-val5 für die Volltextsuche genutzt werden, sollten Variablen ab val6 gespeichert werden.

Sie können das Formular selber programmieren und die abgeschickten Daten in der Datenbank in der Tabelle hc_articles speichern oder den eingebauten Formularmanager benutzen.

Eine Erleichterung bieten die includes unter Zeile 16 und 17.
Der include unter Zeile 16 packt alle per GET übertragenen Variablen, die sie für die Speicherung des Moduls benötigen in Variablen.
Der include unter Zeile 17 lädt alle Variablen für den eingebauten Formularmanager.
So werden automatisch alle Pflichtfelder wie page_id, area_id, lang_id, etc. mit den Formulardaten in hc_article abgespeichert.

Die Pflichtfelder, welche in hc_article belegt werden müssen sind:

FeldVariableBeschreibung
page_id $_GET['page_id'] Die ID der Seite
area $_GET['area'] Die ID des Area
modul_id $_GET['modul_id'] Die ID des Moduls
lang_id $_GET['lang_id'] Die ID der Spache
mode $_GET['mode'] Der Modus. 1 = Live, 2 = Vorschau
pos $_GET['pos'] Die Position des Artikels
content_type $_GET['content_type'] Die Art des Contents. dyn = dyncontent, fix = fixcontent
createuser_id $_SESSION['user']['user_id'] Die ID des Users, der den Artikel erstellt hat. Bitte nur bei der ersten Erstellung eintragen.
updateuser_id $_SESSION['user']['user_id'] Die ID des Users, der den Artikel zuletzt verändert hat.
updatedate   Das Datum der letzten Veränderung.

Ein SQL-Query für einen neuen Artikel müsste daher so aussehen:

INSERT INTO hc_article (page_id, area, modul_id, lang_id, mode, pos, content_type, createuser_id, val1, val2, ...) VALUES ($_GET['page_id'], $_GET['area'], $_GET['modul_id'], $_GET['lang_id'], $_GET['mode'], $_GET['pos'], $_GET['content_type'], $_SESSION['user']['user_id'], $_POST['val1'], $_POST['val2'], ...)

function mod_headline_out($article = array())

Die Funktion mod_headline_out wird aufgerufen, um einen Headlineartikel auf der Website in HTML darzustellen.
In diesem Fall ist die Darstellung sehr einfach.
Die Variable, welche zuvor in val6 gespeichert wurde, wird genutzt um die Art der Überschrift darzustellen, also h1-h4.
Die Variable, welche in val1 gespeichert wurde, wird als Text für die Überschrift genutzt.

Die Funktion muss immer die Angabe $article = array() als Variable enthalten, da hierin die Daten des Artikels übergeben werden.

Welche Felder kann ich durch ein Modul belegen?

In der Datenbank können die Felder val1 - val20 belegt werden.
Bitte nutzen Sie die Felder val1 - val5 ausschließlich für Textinhalte, die sie auch für die Volltextsuche bereit stellen wollen.
Für Variablen wie in unserem Beispiel die Art der Überschrift, benutzen sie die Felder ab val6.

Die Datei inc/modules/newsletter/mod_newsletter_admin.php

Wenn Sie für ihr Modul erweiterte Funktionen oder Einstellungen bereit stellen wollen, dann können sie im Modulordner eine Datei mit dem Aufbau

inc/modules/MODULNAME/mod_MODULNAME_admin.php

anlegen. Diese muss die Funktion mod_MODULNAME_admin enthalten.
Sobald HumbleClouds eine Datei mit diesem Namen und dieser Funktion findet, steht im Bereich Systemeinstellungen unter dem Menupunkt Module der entsprechende Modulname. Beim Anklicken des Namens wird die obige Funktion aufgerufen. Dies kann wie beim Modul newsletter der Ausgangspunkt für mehrere Einstellungen, Funktion und Ansichten sein.

Hier der Inhalt der Datei mod_newsletter_admin.php

<?php

function mod_newsletter_admin() {
	include_once(PATHTOMAINDIR."inc/modules/newsletter/mod_newsletter_mails.php");
	echo mod_newsletter_mails();
	echo '<div id="submenuleft">';
	include_once(PATHTOMAINDIR."inc/modules/newsletter/mod_newsletter_submenuleft.php");
	echo mod_newsletter_submenuleft("mod_newsletter_mails");
	echo '</div>';
	
}

?>

Von hier aus gilt grundsätzlich:
Wird der GET-Variablen ac ein Wert übergeben, der den Aufbau mod_MODULNAME_irgendwas hat, dann wird in dem Modulordner nach der Datei mod_MODULNAME_irgendwas.php gesucht und die Funktion mod_MODULNAME_irgendwas() aufgerufen.

Zum Beispiel bewirkt der Aufruf der Seite

www.ihre-domain.de/hc-admin/user/?ac=mod_newsletter_subscriber

dass Humble Clouds schaut, ob die Datei

inc/modules/newsletter/mod_newsletter_subscriber.php

existiert und die Funktion

mod_newsletter_subscriber()

enthält. Danach wird die Funktion aufgerufen.

Dies ist eine recht einfache und flexible Variante, Module mit zusätzlichen Funktionen auszustatten.

Die Datei inc/modules/newsletter/mod_newsletter_settings.php

Eine Möglichkeit wichtige Einstellungen für Module (wie z.B. bei dem Modul newsletter) bereits auf der Ebene der Website beim Anlegen des Artikels bereitzustellen bietet das Anlegen der Datei

inc/modules/MODULNAME/mod_MODULNAME_settings.php

Beim Anlegen eines Artikels und Auswahl des Moduls wird geschaut, ob sich im Modulordner diese Datei findet und diese die Funktion mod_MODULNAME_settings() enthält. Werden diese gefunden, bietet Humble Clouds oben rechts ein Direktzugriff auf diese Funktion an.

Beim Modul newsletter können so schon im Bereich der Websiteadministration beim Anlegen des Newsletters die Einstellungen für den Newsletter vorgenommen werden. Dadurch muss der User nicht erst in die Systemadministration gehen und dort in die Moduleinstellungen.

Benutzung des Humble Clouds Formularmanagers

Hier finden Sie eine kleine Einführung in die Benutzung des Formularmanagers.
Im Fall des Moduls Headline wird dieser beim Aufruf der Funktion mod_headline_in() aufgerufen.

Datei mod_headline.php

function mod_headline_in()
{
	require_once(PATHTOMAINDIR."inc/modules/headline/FormModHeadlineIn.php");
	$form = new FormModHeadlineIn;
	include(PATHTOMAINDIR."inc/user/snippets/set_modul_in_vars.php");
	include(PATHTOMAINDIR."inc/user/snippets/set_modul_in_formvars.php");
	return $form->output();	
}

In Zeile 3 und 4 wird die Datei FormModHeadlineIn.php eingebunden und eine neue Instanz der Klasse erzeugt.
Die includes in Zeile 5 und 6 binden die wesentlichen Daten in den Formularmanager ein, damit diese mit den Formulardaten in die Datenbank eingetragen werden.
Zeile 7 stellt das Formular dar.

Datei FormModHeadlineIn.php

<?php

include_once(PATHTOMAINDIR."inc/classes_lib/class_Forms.php");

class FormModHeadlineIn extends Forms
{
	public $DataBase = "hc_articles";
	public $DBFields = array("val1", "val6");
	
	public function showForm()
	{
		$form = '<form action="'.URL::getDynUrl().'" method="post">
					<table border="0" cellspacing="0" cellpadding="0" style="font-size:12px; line-height:25px">';
		$form .= '<tr>
					<td>Headline</td>
					<td>Text</td>
					<td></td>
				</tr>
				<tr>
					<td>
						<select name="val6">
							<option value="h1"'.($this->data['val6'] == "h1" ? ' selected="selected"' : '').'>Überschrift 1</option>
							<option value="h2"'.($this->data['val6'] == "h2" ? ' selected="selected"' : '').'>Überschrift 2</option>
							<option value="h3"'.($this->data['val6'] == "h3" ? ' selected="selected"' : '').'>Überschrift 3</option>
							<option value="h4"'.($this->data['val6'] == "h4" ? ' selected="selected"' : '').'>Überschrift 4</option>
						</select>
					</td>
					<td><input type="text" name="val1" value="'.str_replace('"', '&quot;', $this->data['val1']).'" style="width:160px"></td>
					<td><input type="submit" value="speichern" name="sent"></td>				
				</tr>';
		$form .= '</table>
				</form>';
		return $form;
	}

}
?>

Pflichtangaben der neuen Klasse, welche eine Instanz der Klasse Forms sein muss, sind die Variablen

public $DataBase, weche den Namen der Tabelle enthalten muss, in welche die Daten eingetragen werden sollen,
public $DBFields, welche die Felder der Tabelle enthält, welche beschrieben werden sollen und die
function showForm(),  welche als Ausgabe das Formular enthält.

Innerhalb der function showForm() kann über die interne Variable $data auf alle in $DBFields angegebenen Feldinhalte zugegriffen werden.