Entwicklung der Extension sm_employeelist

Auf dieser Seite dokumentiere ich die Entwicklung meiner ersten "großen" Extension für TYPO3: sm_employeelist.

Meine Vorgehensweise lässt sich wie folgt gliedern:

1. Analyse der benötigten Funktionen
2. Entwurf der Datenbank
3. Groben Rahmen der Extension im Kickstarter erstellen
4. Manuelle Anpassung des erzeugten Codes und Implementierung der Funktionen

Die Extension soll grob zusammengefasst die folgenden Funktionen bereitstellen.

• Auf Basis der FrontEnd-Benutzer soll eine Mitarbeiterliste bereitgestellt werden, in der zu jedem Mitarbeiter ein Steckbrief enthalten ist, der allgemeine Informationen über diesen enthält (Name, Geburtstag, Hobbys etc.) aber auch die Zugehörigkeit zu Abteilungen des Unternehmens und die Position(en), die er innehat (z.B. Sachbearbeiter).
• Jeder Mitarbeiter wird als FrontEnd-Benutzer angelegt und seine Eigenschaften im Backend über die normale Benutzerverwaltung gesteuert.
• Die Zugehörigkeit zu Abteilungen wird über die Gruppenzugehörigkeit des Benutzers in TYPO3 gesteuert. Die Hierarchie des Unternehmens wird also über die Gruppen abgebildet, was zusätzlich eine Zugriffsbeschränkung auf Seitenebene für einzelne Abteilungen ermöglicht.
• Als zusätzliche Funktionen werden eine Telefonliste, eine Anwesenheitsliste und eine Geburtstagsliste bereitgestellt, auf denen einzelne Mitarbeiter oder ganze Abteilungen wahlweise angezeigt oder ausgeblendet werden können.

Die Extension sm_employeelist bildet die Grundlage für einige weitere Extensions, die ich noch entwickeln werde. Diese sind im folgenden ERM bereits enthalten. Für die eigentliche Extension ist jedoch nur der rot kenntlich gemachte Bereich interessant.

• fe_groups.settings und fe_users.settings enthalten Flags, die die Anzeige der Mitarbeiter/der Abteilung in den verschiedenen Listen regeln.
  • 1: Anzeigen in Mitarbeiterliste
  • 2: Anzeigen in Telefonliste
  • 4: Anzeigen in Geburtstagsliste
  • 8: Anzeigen in Anwesenheitsliste
• Die neue Tabelle tx_smemployeelist_positions enthält die Positionen der Mitarbeiter (z.B. Sachbearbeiter, Prokurist etc.).
• Die neuen Felder in fe_users dürften selbsterklärend sein. Der Inhalt des Feldes description wird auf der Telefonliste neben dem Namen angezeigt.

Die Extension wird zunächst grundlegend im Extension Kickstarter erstellt. Eine Anleitung hierfür gibt es bereits (in Form von Videos), sodass ich nur die wichtigsten Punkte aufführen werde.

1. Extension Key registrieren, da die Extension publik gemacht werden soll.
2. Basisinformationen eintragen.
3. Zusätzliche Sprache hinzufügen (damit man für die Übersetzung nicht noch einmal durch alle Einstellungen muss).
4. Neue Datenbanktabelle anlegen und vorhandene anpassen (Vorlage ist das ERM).
5. Für jede gewünschte Funktionalität ein Frontend-Plugin erstellen.

Nachdem ich das alles gemacht hatte, sah meine Extension im Kickstarter erst einmal so aus:

Nun nur noch auf "View result" klicken und schon kommt eine Fehlermeldung falls man Umlaute oder Sonderzeichen verwendet hat ;) Sollte dies der Fall sein, einfach Patch 2943 einspielen und nochmal versuchen. Dann noch schnell den Speicherort (global oder lokal) auswählen, und fertig ist die Extension (zumindest das Grundgerüst).

• Datumsangaben vor 1970 sind mit dem TYPO3-Feld Date nicht möglich. Hier musste ich einen String input verwenden und diesen im Quellcode der Extension verarbeiten.
• Die Zuordnung zu Positionen geschieht mit Hilfe von Database relation. Dabei habe ich zunächst True M-M relations aktiviert, damit ich nachher besser die Mitarbeiter je Position auslesen kann, dies habe ich jedoch wieder rückgängig gemacht, da die Zuordnung zu den Benutzergruppen auch nicht so abgebildet ist. Als Type habe ich Selectorbox, select from current page ausgewählt.
• Die Einstellungen, in welchen Listen die Mitarbeiter/Abteilungen auftauchen sollen, habe ich über Checkboxes, x Boxes in a row abgebildet. Dieser Feldtyp bildet die Wahlmöglichkeiten direkt als Flag-Feld ab, genau so wie ich es haben wollte.

Nachdem die Extension nun also im Kickstarter grundlegend modelliert wurde, habe ich für jedes Plugin eine Seite im Seitenbaum erstellt und über den Seiteninhaltstyp Plugin einfügen jeweils eines meiner 4 Plugins eingefügt. Danach erscheint auf jeder der Seiten erst einmal der Standardinhalt eines neuen Plugins (ein wenig Text, ein Formular und ein Link). Dadurch kann man schon einmal sicher sein, dass das Plugin zumindest korrekt aufgerufen wird und auch tatsächlich Inhalt ausgibt.

Bevor ich nun mit der eigentlichen Programmierung begonnen habe, habe ich die Extension erstmal meinem SVN-Repository hinzugefügt, aber das ist jedem selbst überlassen. Als IDE habe ich easyEclipse für PHP bzw. einfach den PSPad-Editor verwendet.

Vor Beginn des Programmierung sollte man sich mit den TYPO3 Coding Guidelines vertraut machen.

Als ersten Schritt habe ich die Datei ext_emconf.php ein wenig angepasst, aber nichts weltbewegendes verändert. Einfach mal die Parameter durchschauen und wenn gewünscht was eintragen: die sind selbsterklärend.

In der Datei ext_localconf.php habe ich zunächst das Caching für die Zeit der Entwicklung abgeschaltet. Dies geschieht durch folgende Codezeile:

$TYPO3_CONF_VARS['EXT']['extCache'] = 0;

Als nächstes habe ich versucht meine selbst definierten Klassen zu inkludieren, die ich im Ordner classes auf Ebene der Plugin-Ordner (pi1 etc.) angelegt habe:

require_once(t3lib_extMgm::extPath('sm_employeelist') . 'classes/class.Employee.php');

Leider gibt es auf diese Art Probleme, da die Klasse Employee abgeleitet ist:

class Employee extends tslib_feUserAuth {}

Die Basisklasse ist bei dieser Art des Aufrufs über ext_localconf.php (warum auch immer) noch nicht bekannt. Daher habe ich die benötigten Klassen direkt in der Datei des Plugins (class.tx_smemployeelist_pi1.php) inkludiert.

Zum Testen habe ich mir erst einmal die recht einfache Klasse Employee angelegt:

class Employee extends tslib_feUserAuth
{
  var $firstname;
  var $lastname;
 
  function __construct()
  {
    $this->firstname = "Stefan";
    $this->lastname = "Macke";
  }
 
  function getName()
  {
    return $this->firstname . " " . $this->lastname;
  }
}

Der Aufruf in der Datei class.tx_smemployeelist_pi1.php funktioniert nun recht einfach (nachdem die Klasse Employee wie gesagt in dieser inkludiert wurde). Die folgende Methode gibt nun meinen Namen aus:

function main($content, $conf)
{
  $this->conf = $conf;
  $this->pi_setPiVarDefaults();
  $this->pi_loadLL();
 
  $e = new Employee();
  $content = $e->getName();
 
  return $this->pi_wrapInBaseClass($content);
}

Nachdem die erste Funktion getestet ist, kann die eigentliche Programmierung beginnen. Die interessantesten Funktionen und Zugriffe liste ich nachfolgend auf.

• Der Aufbau meiner Mitarbeiterliste richtet sich nach dem Standardaufbau von "Listenextensions", wie er auch in den erwähnten Video-Tutorials eingehalten wird. Für mich war die Extension gsi_feuser_list besonders interessant, da sie quasi genau meine grundlegenden Anforderungen abdeckt und ich diese daher als "Vorlage" nehmen konnte. Am interessantesten düfte dabei die Datei class.tx_gsifeuserlist_pi1.php sein, die den beschriebenen Aufbau hat.
• Zum Vervollständigen der Inline-Dokumentation (JavaDoc) ist die Extension extdeveval sehr nützlich. Mit ihr kann man z.B. fehlende Dokumentation für Parameter automatisch hinzufügen.
• Einbinden eines HTML-Templates zur Ausgabe der Informationen zu einem einzelnen Mitarbeiter:

  // Template einbinden
  $this->conf['templateFileSingleView'] = $this->conf['templateFileSingleView'] ? $this->conf['templateFileSingleView'] : t3lib_extMgm::siteRelPath($this->extKey) . 'tpl/employeeSingleView.html';
  $template = $this->cObj->fileResource($this->conf['templateFileSingleView']);
  // Marker definieren
  $markers = array();
  $markers['###IMAGE###'] = 'Hier steht später das Bild';
  // Subpart TEMPLATE extrahieren
  $subpart = $this->cObj->getSubpart($template, '###TEMPLATE###');
  // Marker mit Werten ersetzen
  $out = $this->cObj->substituteMarkerArray($subpart, $markers);

• CSS-Styles und TypoScript aus dem Template in setup.txt auslagern
• Hilfetexte hinterlegen (CSH)
• "Hobbys" o.ä. durch die Benutzer selbst änderbar machen
• Name des aktuell angezeigten Steckbriefs in den Titel der Seite übernehmen