5.7 Spreadsheet_Excel_Writer 

Das Paket Spreadsheet_Excel_Writer ist eines meiner Lieblingspakete. Es gibt Ihnen die Möglichkeit, Excel-Dateien zu erzeugen, und erspart Ihnen den Umweg, CSV-Dateien zu nutzen, wenn Sie tabellarische Daten austauschen wollen.

Eine Excel-Datei besteht aus einer Arbeitsmappe, die ein oder mehrere Arbeitsblätter enthält. In den Arbeitsblättern sind dann wiederum die eigentlichen Tabellenfelder mit den Werten enthalten. Dieses System findet sich bei der Nutzung der Klasse Spreadsheet_Excel_Writer genau so wieder. Somit liefert der Konstruktor der Klasse Ihnen auch ein Arbeitsbuch zurück, in das Sie Tabellenblätter einfügen können, um diesen dann die Daten zu übergeben.

require_once 'Spreadsheet/Excel/Writer.php'; 
// neue Arbeitsmappe 
$mappe = new Spreadsheet_Excel_Writer(); 
// Neues Tabellenblatt 
$preise = $mappe->addWorksheet('Preisliste'); 
// Daten in das Tabellenblatt einfuegen 
$preise->write(0, 0, 'Artikel'); 
$preise ->write(0, 1, 'Preis'); 
$preise ->write(1, 0, 'Hose'); 
$preise ->write(1, 1, '39 Euro'); 
$preise ->write(2, 0, 'Jacke'); 
$preise ->write(2, 1, '20 Euro'); 
$preise ->write(3, 0, 'Socken'); 
$preise ->write(3, 1, '8 Euro'); 
// Weiteres Blatt einfuegen 
$anmerkungen = $workbook->addWorksheet('Anmerkungen'); 
$anmerkungen -> write (0,0,'Alle Artikel sind neu'); 
$mappe->send('Preisliste.xls'); 
$ mappe->close();

Listing 5.7 Ausgabe einer Excel-Datei mit PEAR::Spreadsheet_Excel_Writer

Wie Ihnen in Listing 5.7 vielleicht aufgefallen ist, liegt die zuständige Klassendatei nicht im Unterverzeichnis Files, wie Sie vielleicht erwartet hätten. Der Grund hierfür liegt darin, dass die Kategorien innerhalb des PEAR-Projekts umgestellt wurden. Um hier eine Abwärtskompatibilität zu wahren, ist die Verzeichnisstruktur entsprechend erhalten geblieben.

Der Konstruktor benötigt keinen Parameter und liefert Ihnen ein instanziiertes Objekt, also sozusagen eine Arbeitsmappe (Workbook), zurück. Da sich das Paket sehr schön an den hierarchischen Aufbau von Excel-Dateien hält, sind alle Methoden, die sich auf die gesamte Datei beziehen, immer auf Basis dieses Objekts aufzurufen, wie Sie gleich sehen werden.

Ist die Mappe erstellt, können als Nächstes mit der Methode addWorksheet() einzelne Arbeitsmappen (Worksheets) hinzugefügt werden. Die Methode bekommt jeweils den Namen des Blattes übergeben, der dann auf dem Reiter erscheint, wenn die Datei mit Excel geöffnet wird. Die Methode liefert eine Referenz auf das entsprechende Mappen-Objekt zurück, in das dann die Werte eingefügt werden können, was die Methode write() für Sie erledigt. Sie bekommt die Y- und X-Koordinate des Feldes übergeben, in das die Daten eingefügt werden sollen. Die Y-Koordinate entspricht der Nummer der Zeile und die X-Koordinate der Nummer der Spalte. Die Koordinaten beziehen sich jeweils auf die linke obere Ecke, in der Excel-Darstellung also auf das Feld A1, das die Koordinaten 0,0 hat. In Listing 5.7 wird, nachdem alle Daten eingefügt worden sind, die Methode send() auf das Arbeitsbuch-Objekt angewandt, um die Datei zum Client zu senden. Sie bekommt den Dateinamen übergeben, unter dem die XLS-Datei beim Empfänger ankommen soll. Wie das Ergebnis des Scripts in Excel dargestellt wird, sehen Sie in Abbildung 5.2.

Abbildung 5.2 Darstellung des Ergebnisses in Excel

Die Methode close() übernimmt in diesem Fall das Aufräumen des Speichers. Sie kann die Datei aber auch auf der Festplatte des Servers speichern, wenn Sie diese nicht an den Client senden wollen.

Soll die Datei auf dem Server gespeichert werden, übergeben Sie bereits dem Konstruktor den Dateinamen, unter dem die Datei abgelegt werden soll. Der restliche Quellcode würde sich nicht verändern, nur die Methode send() fällt natürlich weg.

require_once 'Spreadsheet/Excel/Writer.php'; 
// neue Arbeitsmappe mit Dateinamen anlegen 
$mappe = new Spreadsheet_Excel_Writer('Preisliste.xls'); 
 
//Code wie gehabt 
 
$erg=$mappe->close(); 
if (true===PEAR::isError($erg)) 
{ 
   die($erg->getMessage()); 
}

Die Methode close() kann einen PEAR_Error zurückliefern. Sind die Daten bereits an den Browser gesendet worden, ist es sicher nicht ganz so wichtig, hier noch eine Fehlerabfrage vorzunehmen. Sollen die Daten allerdings gespeichert werden, ist das ein unabdingbarer Schritt.

Nachdem Sie nun einen ersten Eindruck davon haben, wie einfach die Arbeit mit dem Paket ist, möchte ich ein wenig detaillierter auf die einzelnen Features eingehen.

5.7.1 Arbeitsblätter 

Neben der Methode addWorksheet() gibt es noch andere Methoden, die sich auf die Arbeitsblätter beziehen. Gerade, wenn Sie eine Datei mit vielen Arbeitsblättern erzeugen, kann es hilfreich sein, wenn Sie definieren können, welches Blatt als Erstes angezeigt wird. Mit der Methode activate() können Sie ein Tabellenblatt aktiv schalten, also die dort enthaltenen Daten direkt auf dem Bildschirm anzeigen lassen. Sie bekommt keine Parameter übergeben und wird direkt auf ein Worksheet-Objekt angewandt.

Die Methode setFirstSheet() hat eine ähnliche Zielsetzung. Sie scrollt die Reiter unterhalb der Tabellen so, dass das Tabellenblatt, auf das die Methode angewandt wurde, an erster Stelle steht, aber nicht aufgeblendet wird. Die Reihenfolge der Blätter wird also nicht vertauscht, und es wird auch kein anderes Blatt aufgeblendet.

In einigen Fällen kann es sinnvoll sein, die Darstellungsgröße zu verändern. Excel kennt hierzu die Möglichkeit, ein Tabellenblatt zu zoomen. Der Zoom-Faktor für ein Tabellenblatt kann mit setZoom() definiert werden. Die Methode bekommt den Faktor in Prozent übergeben, wobei 100 die Standardeinstellung ist und 100  % entspricht.

5.7.2 Tabellenfelder 

Wenn Sie sich schon ein wenig näher mit Excel befasst haben, werden Sie wissen, wie umfangreich die Möglichkeiten sind, um Tabelleninhalte zu formatieren. Hierbei stellt sich als Erstes die Frage, welchen Typ eine Information hat, die in einem Feld abgelegt ist.

Formatierung

Im ersten Beispiel habe ich nur die Methode write() genutzt, die die Daten in ein Feld eingefügt hat. Die Methode unterstützt allerdings auch die Möglichkeit, dem Feld gleich eine Formatierung zuzuweisen. Diese Formatierung wird write() als vierter Parameter übergeben, muss allerdings vorher definiert werden. Hierzu ist die Methode addFormat() definiert, mit der Sie eine neue Formatierung in einer Arbeitsmappe anlegen können. Die Methode liefert eine Referenz auf ein Excel-Format-Objekt zurück, dem Sie dann die einzelnen Format-Anweisungen zuweisen können. Hierunter fallen Dinge wie die Ausrichtung innerhalb der Zelle, die Farbe und Ähnliches.

Eine Funktionalität, die recht häufig benötigt wird, ist das Festlegen der Schriftart, was Sie mit setFontFamily() machen können. Die Methode bekommt den Namen der gewünschten Schrift übergeben. Zwar sagt die Dokumentation, dass nur die Strings Times New Roman, Arial oder Courier als Werte akzeptiert werden, aber zurzeit können Sie noch den Namen jeder beliebigen Schriftart angeben. Wichtig ist das insbesondere dann, wenn Sie die Schriftart Courier wünschen. Der Parameter Courier führt unter Umständen zu einer schlechten Darstellung. Mit Courier New nutzt Excel einen TrueType-Font, der eine bessere Darstellung gewährleistet.

$mappe = new Spreadsheet_Excel_Writer(); 
$preise = $mappe->addWorksheet('Preisliste'); 
// Der Mappe ein neues Format hinzufuegen 
$format = $mappe->addFormat(); 
// Schriftart festlegen 
$format->setFontFamily("Courrier New"); 
// Ausgabe in Mappe mit automatischer Formatzuweisung 
$preise->write(0, 0, 'Artikel',$format);

Natürlich können Sie nicht nur die eigentliche Schriftart, sondern auch die Darstellung derselben selektieren. Die Schriftgröße kann mit setSize() definiert werden. setSize() bekommt die gewünschte Größe in Punkt übergeben. Um eine kursive Darstellung einzuschalten, rufen Sie einfach die Methode setItalic() auf. Eine unterstrichene Darstellung erzielen Sie mit setUnderline(), die noch die Zahl 1 oder 2 als Parameter erwartet, womit festgelegt wird, mit wie vielen Linien der Feldinhalt unterstrichen wird. Sie können einen Feldinhalt mit setStrikeOut() übrigens auch durchstreichen. Mit der Methode setBold() können Sie die Schriftart fett darstellen. Des Weiteren haben Sie auch die Möglichkeit, mit setScript(1) einen Text hochzustellen bzw. ihn mit setScript(2) tiefzustellen.

$schrift = $mappe->addFormat(); 
$schrift->setBold(); 
$schrift->setFontFamily('Arial'); 
$schrift->setSize(30); 
$preise->write(0, 0, 'Artikel',$schrift);

Die Ausrichtung des Feldinhalts können Sie mit setAlign() beeinflussen. Die Methode bekommt jeweils einen Parameter übergeben, der bestimmt, wie sich der Inhalt verhalten soll.

Sie können natürlich auch verschiedene Ausrichtungen kombinieren. Dazu müssen Sie die Methode dann mehrfach aufrufen.

$mittig = $mappe->addFormat();//neues Format 
$mittig ->setAlign("vcenter"); 
$mittig ->setAlign("center"); 
$worksheet->write(0,0,"Mittige Ausgabe",$mittig);

Des Weiteren unterstützt die Methode noch den Parameter merge. Dieser muss immer auf zwei nebeneinander liegende Felder angewandt werden. Er dient dazu, den Inhalt vom linken der beiden Felder virtuell über die beiden Felder zu verteilen. Mit den Zeilen

$schrift = $mappe->addFormat(); 
$schrift->setAlign('merge'); 
$preise->write(0, 0, 'Langer Text',$schrift); 
$preise->write(0, 1, '',$schrift);

wird also Langer Text ausgegeben und über die beiden Felder 0,0 und 0,1 hinweg zentriert, wobei die beiden Zellen aber nicht verbunden werden.

Aber Sie können auch das Laufverhalten des Textes beeinflussen. Mit setTextWrap() können Sie einschalten, dass der Text automatisch umbricht, wenn er zu lang für das Feld ist.

Darüber hinaus können Sie mit setTextRotation() auch noch festlegen, ob der Text in einem bestimmten Winkel gedreht werden soll. Die Methode dreht den Text im Uhrzeigersinn und akzeptiert die Werte 0, 90, 270 und -1. Bei den ersten dreien wird der Text einfach entsprechend der Gradzahl im Uhrzeigersinn gedreht. Der Parameter -1 bewirkt, dass der Text »von oben nach unten« ausgegeben wird und die Buchstaben somit übereinander stehen.

Schwarz-weiße Tabellen sind auf Dauer nicht so interessant. Daher haben Sie natürlich auch die Möglichkeit, Ihre Daten mit ein wenig Farbe aufzulockern. Sollen die Daten einfach nur ein wenig eingefärbt werden, reichen die Methoden setColor() und setFgColor(). Die erste setzt dabei die Farbe des Textes und die zweite die des Hintergrundes. Bitte lassen Sie sich nicht dadurch verwirren, dass die Methode setFgColor() heißt. Bei einer einfachen, flächigen Füllung handelt es sich trotzdem um den Hintergrund. Die beiden Methoden bekommen als Parameter die Information übergeben, welche Farbe genutzt werden soll. Am einfachsten ist es, eine Farbe über einen der vordefinierten Namen anzusprechen, die Sie in Tabelle 5.7 finden.

Neben diesen Farbnamen können Sie auch einen Integer-Wert zwischen 8 und 63 angeben. Hiermit können Sie die Farben ansprechen, die in der aktuellen Excel-Farbpalette vorhanden sind. Da aber nicht dokumentiert ist, welcher Farbcode welche Farbe nach sich zieht, würde ich Ihnen einen anderen Ansatz empfehlen. Und zwar gibt die Methode setCustomColor(), die für das Workbook-Objekt definiert ist, Ihnen die Möglichkeit, selbst eine Farbe zu definieren. Ihr werden vier Zahlen als Parameter übergeben. Der erste definiert, an welchem Platz die Farbe in der Palette abgelegt werden soll. Sie können also eine Zahl zwischen 8 und 63 angeben, die definiert, an welchem Platz der Palette die neue Zahl abgelegt werden soll. Die Farbe, die sich dort ursprünglich befand, wird ersetzt. Bei den anderen drei Parametern handelt es sich um ganzzahlige Werte zwischen 0 und 255. Sie definieren die Intensität der Farbkanäle Rot, Grün und Blau. Und so wird’s gemacht:

// Legt Rot auf den Palettenplatz 8 
$rot=$mappe->setCustomColor(8,255,0,0); 
// Legt Gruen auf den Palettenplatz 9 
$gruen=$mappe->setCustomColor(9,0,255,0); 
// Selektiert den Palettenplatz 8 als Farbe 
$schrift->setColor(8); 
// Selektiert die neu angelegte Farbe 
$schrift->setFgColor($gruen);

Die vorhergehenden Zeilen zeigen, wie Sie auf die neu definierten Farben zugreifen können. Zum einen können Sie diese natürlich über ihren Palettenplatz ansprechen, zum anderen liefert setColor() aber auch einen Wert zurück, den Sie nutzen können, um die Farbe anzusprechen. Üblicherweise handelt es sich dabei um die Nummer des Paletten-Platzes. Die Methode kann auf diesem Weg aber auch ein PEAR_Error-Objekt zurückliefern, wenn ein Fehler auftritt.

Excel kennt aber auch die Möglichkeit, Zellen mit einem Muster zu füllen. Hierbei stehen insgesamt 18 verschiedene Muster zur Verfügung, die Sie mithilfe von setPattern() ansprechen können. Die Member-Funktion bekommt einen Integer-Wert zwischen 1 und 18 übergeben und setzt dann das entsprechende Muster. Ein solches Muster setzt sich immer aus zwei Farben zusammen, wo dann auch endlich eine Hintergrundfarbe zum Tragen kommt. Standardmäßig sind die Zellen mit dem Muster 1 gefüllt, bei dem die Vordergrundfarbe die gesamte Zelle ausfüllt, so dass die Hintergrundfarbe, die Sie übrigens mit setBgColor() festlegen können, nicht zu sehen ist. Nutzen Sie nun ein anderes Füllmuster, wird das aus den beiden Farben kombiniert. In Abbildung 5.3 sehen Sie die unterstützen Muster, die so (natürlich mit wechselnder Musterauswahl) generiert wurden:

$f_muster->setBgColor('white'); 
$f_muster ->setFgColor('black'); 
$f_muster ->setPattern(1);

Abbildung 5.3 Die Füllmuster im Überblick

Zellformate

Wenn Excel eine Zahl in einem Tabellenfeld speichert, so kann diese auf unterschiedlichste Art und Weise dargestellt werden. Ein und derselbe Wert kann also auf verschiedene Arten dargestellt werden, ohne dass der eigentliche Wert verändert wird. Auch dieses Verhalten wird über ein Format gesteuert, das mit setNumFormat() festgelegt wird. Die Methode bekommt einen Integer-Wert übergeben, der definiert, in welchem Format der Inhalt dargestellt werden soll. Format 10 definiert beispielsweise, dass der Inhalt eines Feldes als Prozentzahl dargestellt werden soll. Wäre die Zahl 1 der Wert, so würde sie als 100  % dargestellt.

$f_prozent->setNumFormat(10); 
$worksheet->write(1,1,0.51,$f_prozent); 
//Wird als 51  % dargestellt

Die Formate, die die Methode unterstützt, finden Sie in Tabelle 5.8. Bitte beachten Sie bei der Darstellung, dass sie sich an der Lokalisierungseinstellung von Windows orientiert. Die Daten in der Tabelle basieren auf einer deutschen Lokalisierung.

Ausgabe

Bisher habe ich für die Ausgabe immer die Methode write() genutzt. Sie versucht, selbstständig zu ermitteln, um welche Art von Daten es sich handelt, und diese korrekt auszugeben. Das Paket unterscheidet hierbei zwischen Texten, Zahlen, URLs und Ähnlichem. Sollte ein Fehler bei der Ausgabe auftauchen, geben die Methoden das mithilfe eines Fehlercodes und nicht mit einem PEAR_Error zurück. Für alle gilt, dass sie –2 zurückgeben, wenn die gewählten Zellkoordinaten außerhalb des gültigen Bereichs liegen. Maximal sind 65.535 Zeilen und 255 Spalten zulässig.

Eine etwas ungewöhnliche Ausgabefunktion ist writeBlank(). Sie bekommt nur die Koordinaten eines Feldes und einen Formatbeschreiber übergeben. Dieses Feld wird dann leer initialisiert, und ihm wird das übergebene Muster zugewiesen. Zwar könnten Sie, um ein Feld leer zu initialisieren, auch einfach write() mit einem Leerstring aufrufen, aber writeBlank() ist da sicher eindeutiger, falls der Quelltext mal einem Review unterzogen wird.

Um eine Zahl auszugeben, ist die Methode writeNumber() in der Klasse enthalten. Die Parameter sind dieselben wie bei write(), nur dass die Methode eben nur Zahlen als Ausgabewerte akzeptiert. Lassen Sie eine Zahl mit Nachkomma-Anteil ausgeben, vergessen Sie bitte nicht, dass es sich dabei um einen Float-Wert handeln muss. Der Nachkomma-Anteil muss also mit einem Punkt abgetrennt werden und nicht mit einem Komma.

Einen Text können Sie mit writeString() ausgeben lassen. Auch hier sind die Parameter identisch, wobei zu beachten ist, dass der auszugebende Text maximal 255 Zeichen lang sein darf. Ist er länger, gibt die Methode den Fehlercode -3 zurück. Diese Einschränkung resultiert aus dem zugrunde liegenden Datenformat von Excel 95. In zukünftigen Versionen von Spreadsheet_Excel_Writer wird das BIFF 8-Format unterstützt, das mit Excel 97 eingeführt wurde. Hierin werden auch längere Strings unterstützt.

Eine wirklich interessante Möglichkeit, um längere Texte in einer Tabelle unterzubringen, ist es, Felder mit Kommentaren zu versehen. Hierbei handelt es sich um frei definierbare Texte beliebiger Länge, die zwar einem Feld zugeordnet, aber nicht sofort aufgeblendet werden. Diese werden mit writeNote() geschrieben, das dieselben Parameter wie writeString() übergeben bekommt, wobei natürlich die Begrenzung der Stringlänge wegfällt.

Da Excel auch die Möglichkeit unterstützt, Links in einer Tabelle zu nutzen, findet sich natürlich auch eine Methode, diese zu erzeugen. writeUrl() bekommt auch zuerst die Koordinaten der Zelle übergeben, die genutzt werden soll. Danach folgt die URL, auf die der Link verweisen soll. Die URL kann in diesem Fall auf eine »internet-typische« Ressource wie einen http- oder ftp-Server verweisen. Ein Verweis auf andere Tabellenblätter ist zurzeit noch nicht möglich. Dann geben Sie den Text an, der in der Tabelle dargestellt werden soll. Übergeben Sie an dieser Stelle einen leeren String, wird die URL in der Tabelle angezeigt. Ein Link wird standardmäßig blau und unterstrichen dargestellt, wie es in Browsern üblich ist. Sie können aber auch hier das Format noch beeinflussen, indem Sie als fünften Parameter noch einen entsprechenden Formatbeschreiber übergeben.

Besonders interessant ist aber sicherlich die Methode writeFormula(), mit der Sie eine Formel in ein Feld einfügen können. Die Formel wird der Methode als String übergeben, wobei sie genau so anzugeben ist, wie Sie diese in Excel tippen würden. Leider müssen Sie die Formel in Englisch formulieren, was ein wenig ungewöhnlich ist. So wird in Listing 5.8 die Formel =SUM(A1:A3) in das Feld A4 eingefügt.

require_once 'Spreadsheet/Excel/Writer.php'; 
$mappe = new Spreadsheet_Excel_Writer(); 
$tabelle = $mappe->addWorksheet('tab'); 
 
$tabelle->write(0,0,1); 
$tabelle->write(1,0,1); 
$tabelle->write(2,0,1); 
$tabelle->writeFormula(3,0,"=SUM(A1:A3)");

Listing 5.8 Ausgabe einer Formel

Betrachten Sie die Ausgabe in Excel, so wird die Formel allerdings in der Sprache der Zielplattform ausgegeben, wie Sie in Abbildung 5.4 sehen können.

Sollten Ihnen die englischen Formulierungen nicht unbedingt geläufig sein, werden Sie im Internet, z. B. unter http://www.barasch.com/excel/xlFormu las.htm, entsprechende Hilfen finden.

Abbildung 5.4 Darstellung der Formel in Excel

In diesem Zusammenhang ist die Methode rowcolToCell() hilfreich, die die Koordinaten, wie sie für Spreadsheet_Excel_Writer verwendet werden, in Excel-konforme Bezüge umrechnet die statisch aufgerufen werden kann.

$zelle = Spreadsheet_Excel_Writer::rowcolToCell(0, 0); 
echo $zelle; // Gibt A1 aus

Sie können aber nicht nur langweilige Zahlen und Texte in die Tabellen einfügen. Gerade bei endlos langen Zahlenkolonnen kann eine Grafik das Gesamtbild deutlich auflockern. Die Methode insertBitmap() gibt Ihnen die Möglichkeit, eine Bitmap-Datei in die Tabelle einzufügen. Hierbei muss es sich um eine Bitmap mit 24 Bit Farbtiefe handeln. Andernfalls wird die Datei zwar eingefügt, aber nicht korrekt dargestellt. Sollte die Methode einen anderen Fehler feststellen, liefert sie einen PEAR_Error zurück.

insertBitmap() bekommt mit den ersten beiden Parametern die Koordinaten der Zelle übergeben, in die die Bitmap eingefügt werden soll. Danach folgt der Dateiname inklusive eines eventuellen Pfades. Die Methode unterstützt aber noch vier weitere Parameter, die optional sind. Die ersten beiden nach dem Dateinamen legen fest, wie viel Pixel Abstand die Grafik zum Rand des Tabellenfeldes haben soll. Hierbei wird zuerst der horizontale und dann der vertikale Abstand angegeben. Danach können Sie noch zwei Parameter angeben, die die Darstellungsgröße der Datei festlegen. Erst wird die Breite in Pixeln, gefolgt von der Höhe übergeben.

require_once 'Spreadsheet/Excel/Writer.php'; 
$mappe = new Spreadsheet_Excel_Writer(); 
$tabelle = $mappe->addWorksheet('tab'); 
 
// Bild pearsmall.bmp in Feld B2 mit 
// 5 Pixeln Abstand einfuegen 
$erg=$tabelle->insertBitmap (1,1,'pearsmall.bmp',5,5); 
if (PEAR::isError($erg)) 
{ 
   die ($erg->getMessage()); 
} 
 
$mappe->send(time().'.xls'); 
$mappe->close();

Listing 5.9 Einfügen einer Bitmap in eine Tabelle

Das Ergebnis von Listing 5.9 sehen Sie in Abbildung 5.5.

Abbildung 5.5 Excel-Tabelle mit eingefügter Bitmap

Gitternetz

Die Formatierungsmöglichkeiten beschränken sich allerdings nicht nur auf den Feld-Inhalt. Genauso können Sie auch die Gitternetzlinien formatieren bzw. die Breite und Höhe von Spalten und Zeilen verändern.

Die Breite einer Spalte kann mit setColumn() verändert werden. Da die Methode mehrere Spalten gleichzeitig beeinflussen kann, erwartet sie die Nummer der ersten und der letzten Spalte als Parameter. Danach geben Sie die gewünschte Breite der Spalte in Zeichen an. Angenehm ist, dass Sie optional noch ein vorher definiertes Format angeben können, das dann für alle Felder der Spalten übernommen wird. Als letzter Parameter wird zusätzlich noch ein boolescher Wert unterstützt. Mit ihm können Sie angeben, ob die Spalte versteckt werden soll, was normalerweise nicht der Fall ist. Eine Spalte wird in Excel dadurch versteckt, dass sie in der Darstellung auf die Breite 0 reduziert wird, was die Methode dann für Sie macht.

Eine ähnliche Methode mit Namen setRow() existiert auch für die Zeilen. Sie kann allerdings nur eine Zeile manipulieren und bekommt daher nur die Nummer der Zeile sowie die Höhe übergeben. Allerdings ist die Höhe hier in Zeilen anzugeben, was ein wenig gewöhnungsbedürftig ist. Als dritten Parameter können Sie auch hier noch ein Format übergeben, das dann für die gesamte Zeile übernommen wird.

Die Rahmen der einzelnen Felder können sowohl ein- und ausgeschaltet als auch eingefärbt werden. Die Darstellung der Rahmen kann mit den Methoden setTop() (oberer Rahmen), setLeft() (linker Rahmen), setBottom() (unterer Rahmen) und setRight() (rechter Rahmen) eingestellt werden. Die Methoden bekommen jeweils die Nummer des gewünschten Rahmenformats übergeben, wobei 8 Formate (von 0 – 7) zur Verfügung stehen. Das Script aus Listing 5.10 generiert eine Übersicht der Linienarten, die Sie in Abbildung 5.6 sehen können.

require_once 'Spreadsheet/Excel/Writer.php'; 
$mappe = new Spreadsheet_Excel_Writer(); 
$tabelle = $mappe->addWorksheet('tab'); 
 
for ($i=0; $i < 8; $i+=1) 
{ 
   $f[$i]=$mappe->addFormat(); 
   $f[$i]->setTop($i); 
   $f[$i]->setBottom($i); 
   $tabelle->write(1,$i,"wert = $i",$f[$i]); 
} 
$mappe->send(time().'.xls'); 
$mappe->close();

Listing 5.10 Generieren verschiedener Linienarten

Abbildung 5.6 Darstellung verschiedener Linienarten in Excel

Sie können aber nicht nur die Form der Linien, sondern auch deren Farbe verändern. Auch hierzu sind wieder einzelne Methoden vorgesehen, die für jede einzelne Rahmenlinie die Farbe bestimmen. Sie heißen setTopColor() (oberer Rahmen), setLeftColor() (linker Rahmen), setBottomColor() (unterer Rahmen) und setRightColor() (rechter Rahmen). Sie akzeptieren dieselben Farbwerte, wie sie schon bei setColor() beschrieben wurden.

5.7.3 Drucken 

Ein besonders nettes Feature ist, dass das Paket schon die Druckvorgaben für eine Excel-Datei festlegen kann. Sollten Sie nicht mit Excels Druckvorgang vertraut sein, würde ich Ihnen empfehlen, sich erst einmal ein wenig in Excel umzuschauen, da die Möglichkeiten etwas verwirrend sein können.

Möchten Sie die Auswirkungen dieser Methoden in Excel nachvollziehen, wählen Sie den Druck-Dialog an. Unten links in diesem Dialog-Fenster findet sich ein Button Vorschau. Wenn Sie diesen Button anwählen, zeigt Excel Ihnen die Druckvorschau, in der Sie die spätere Darstellung auf Papier kontrollieren können.

Die nachfolgend beschriebenen Methoden beziehen sich immer auf ein Tabellenblatt und nicht auf eine gesamte Mappe.

Bevor Sie darüber nachdenken zu drucken, sollten Sie sich vor Augen führen, dass der Ausdruck auf Papier erfolgt. Das hört sich banal an, wird aber oft vergessen. Papier kennt unterschiedliche Größen (A4 oder Letter), Formate (hoch oder quer), und der Leser kann auf Papier auch nicht einfach »zoomen«.

Welches Papierformat Verwendung findet, können Sie mit setPaper() festlegen. Möchten Sie das in Deutschland übliche A4-Format festlegen, übergeben Sie der Methode die Zahl 9.

$tabelle->setPaper(9);

Offiziell unterstützt die Methode nur die Konstanten 1 für »US Letter« und 9 für A4. Allerdings werden Sie feststellen, dass auch viele andere Formate akzeptiert und korrekt übernommen werden. Allerdings gleicht Excel das gewählte Format mit denen ab, die der Drucker unterstützt, so dass es vorkommen kann, dass Sie ein Format wählen, das so aber nicht angezeigt wird. Die wichtigsten Formate finden Sie in Tabelle 5.9.

Benötigen Sie noch andere Papierformate, können Sie die Beschreibung des Excel-Formats von OpenOffice.org zu Rate ziehen, das Sie unter der URL http://sc.openoffice.org/excelfileformat.pdf    [Die Papierformate finden Sie in der aktuellen Version des Dokuments (27 März 2005) auf Seite 195. ] finden.

Um ein Hoch- oder Querformat festzulegen – der Standard ist ein Hochformat –, stehen zwei Methoden zur Verfügung. setPortrait() können Sie nutzen, um zu definieren, dass die Seite im Hochformat gedruckt werden soll. setLandscape() hingegen schaltet das Querformat ein.

Gerade in Firmen kann es vorkommen, dass ein Papier mit Briefkopf oder einer fest eingedruckten Adresse für die Ausgabe genutzt werden soll. In einem solchen Fall ist es hilfreich, wenn Sie die Ränder, also den Bereich, in dem nicht gedruckt werden darf, beeinflussen können. Die hierfür vorgesehenen Funktionen sind in der Lage, die Seitenränder für den eigentlichen Inhalt zu beeinflussen. Das heißt im Umkehrschluss, dass eine Kopf- oder Fußzeile sich durchaus noch ober- oder unterhalb des eigentlichen Inhalts befinden kann. Excel sieht bei der Blattgröße DIN A4 links und rechts standardmäßig einen Rahmen von 1,9 cm und oben und unten von 2,5 cm vor. »Oben«, »unten« etc. beziehen sich hierbei auf die Darstellung im Ausdruck, d. h. eine Drehung des Blattes wird hierbei berücksichtigt. »Oben« bezieht sich nach wie vor auf die Oberkante des Blatts und nicht plötzlich auf die linke Seite. Die nachfolgenden Methoden bekommen alle die Größe des Randes in Zoll als Parameter übergeben. Ein Zoll entspricht 2,54 cm, wobei zu beachten ist, dass Excel auf die erste Stelle nach dem Komma rundet. Eine Randbreite von 1 Zoll wird zu 2,50 cm, und 2 Zoll werden zu 5,10 cm.

Um alle Rahmen gleich breit zu machen, nutzen Sie am einfachsten setMargins(). Mit $tabelle->setMargins(1.5); legen Sie eine gleichmäßige Rahmenbreite von 1,5 Zoll fest. Möchten Sie die seitlichen Rahmen identisch groß machen, bietet sich setMargins_LR() an. setMargins_TB() dient dazu, den oberen und unteren Seitenabstand gleichzeitig zu korrigieren. Natürlich haben Sie auch die Möglichkeit, jeden Abstand einzeln zu manipulieren, was mit den Methoden setMarginTop() (oben), setMarginLeft() (links), setMarginBottom() (unten) und setMarginRight() (rechts) möglich ist.

Eine Kopf- oder Fußzeile können Sie mit setHeader() bzw. setFooter() einfügen. Die Methoden bekommen als ersten Parameter jeweils den Text übergeben, der als Kopf- bzw. Fußzeile genutzt werden soll. Die Texte werden zentriert ausgegeben und können zum jetzigen Zeitpunkt leider auch nicht formatiert werden. Der Abstand zum oberen bzw. unteren Papierrand ist standardmäßig auf 0,5 Zoll eingestellt. Bevorzugen Sie einen anderen Abstand, können Sie diesen mit dem zweiten Parameter festlegen. Bitte beachten Sie hierbei, dass es nicht zu einer Überschneidung mit den Seitenrändern des eigentlichen Dokuments kommen sollte, die Sie mit den setMargin-Methoden festlegen können.

Um die Darstellungsgröße des Ausdrucks zu korrigieren, können Sie die Daten, ähnlich wie in der Bildschirmdarstellung, zoomen. Den Zoomfaktor legen Sie mit setPrintscale() fest. Die Methode bekommt eine Zahl als Parameter übergeben. Ein Wert kleiner als 100 verkleinert die Darstellung auf dem Papier prozentual, wohingegen ein Wert größer als 100 zu einer Vergrößerung führt.

Die ausgedruckten Daten werden standardmäßig links oben ausgerichtet. Um die Daten im Ausdruck horizontal zu zentrieren, rufen Sie centerVertically() auf. centerHorizontally() leistet das Gleiche für die horizontale Achse. Beide Methoden beziehen sich nicht auf die absolute Position auf dem Papier, sondern auf die Position der Daten zwischen den Seitenrändern, die Sie mit den setMargin-Methoden festgelegt haben.

Gerade dann, wenn Sie ein schönes Layout erstellt haben, kann es sehr störend sein, wenn das Gitternetz der original Excel-Tabelle mit ausgedruckt wird. Das kann mit hideGridlines() verhindert werden.

Excel kann aber mehr, als alle Daten einfach nur auszudrucken. Sie können auch definieren, welche Teile einer Tabelle ausgedruckt werden sollen, wo sich ein Seitenumbruch befinden soll und welche Zeilen als Kopf- bzw. Fußzeile genutzt werden sollen.

Um nicht alle Daten auszugeben, können Sie den zu druckenden Bereich mit printArea() einschränken. Die Methode bekommt vier Zahlen übergeben, die, der Reihe nach, die erste Zeile, die erste Spalte, die letzte Zeile und die letzte Spalte definieren, die gedruckt werden sollen. Die Bereiche außerhalb dieses so definierten Vierecks werden nicht gedruckt. Nutzen Sie diese Methode nicht, wird der gesamte Inhalt des Tabellenblatts gedruckt.

Generieren Sie eine umfangreiche Tabelle, kann es sehr hilfreich sein, die Seitenumbrüche manuell festzulegen. Tun Sie das nicht, versucht Excel, so viele Daten auf einer Seite auszugeben wie möglich, was allerdings bei umfangreichen Tabellen sehr störend sein kann. Auch hier stehen wieder zwei Methoden zur Verfügung, um die horizontalen (setHPagebreaks()) und die vertikalen (setVPagebreaks()) Umbrüche zu definieren. Die erste ist hierbei für die Umbrüche zwischen den Zeilen und die zweite für die Umbrüche zwischen den Spalten zuständig. Beide Member-Funktionen bekommen ein Array übergeben, in dem die Nummern der Zeilen bzw. Spalten angegeben werden, nach denen jeweils der Umbruch eingefügt wird.

Die letzten beiden sehr hilfreichen Methoden, um den Ausdruck zu formatieren, sind repeatRows() und repeatColumns(). Sie sind bei sehr großen Tabellen sehr hilfreich. Müssen Sie eine Tabelle im Ausdruck über mehrere Seiten verteilen, so fehlen auf dem zweiten Blatt normalerweise die Überschriften der Spalten bzw. die Kommentare am Anfang einer Zeile. Beide Methoden akzeptieren die Nummer einer Spalte bzw. Zeile, die wiederholt werden soll. Diese Spalte bzw. Zeile wird dann auf jedem ausgedruckten Blatt links bzw. oben wiederholt, so dass die Daten besser interpretierbar sind.

In Listing 5.11 finden Sie noch ein kleines Beispiel, das das Zusammenspiel der Methoden verdeutlicht. Hierbei wird eine kleine Tabelle erzeugt, die die Verkaufspreise für bestimmte Produkte berechnet. Die Tabelle wird des Weiteren für den Ausdruck vorbereitet. Allerdings werden nur zwei Spalten, die mit Kopf- und Fußzeile versehen sind, vergrößert ausgedruckt.

require_once 'Spreadsheet/Excel/Writer.php'; 
 
$mappe = new Spreadsheet_Excel_Writer(); 
$tabelle = $mappe->addWorksheet('Preise'); 
 
// Spaltenueberschriften 
$tabelle->write(0,1,'Hose'); 
$tabelle->write(0,2,'Jacke'); 
$tabelle->write(0,3,'Schuhe'); 
$tabelle->write(0,4,'Hemd'); 
 
// Zeilenkommentare 
$tabelle->write(1,0,'Einkauf'); 
$tabelle->write(2,0,'Marge'); 
$tabelle->write(3,0,'Steuer'); 
$tabelle->write(4,0,'Verkaufspreis'); 
 
$f_prozent=$mappe->addFormat(); 
$f_prozent->setNumFormat(10); 
 
$f_euro=$mappe->addFormat(); 
$f_euro->setNumFormat(44); 
 
for ($spalte=1; $spalte < 5; $spalte+=1) 
{ 
   // Unser Einkaufspreis 
   $tabelle->writeNumber(1,$spalte, 15*$spalte,$f_euro); 
   $ek=Spreadsheet_Excel_Writer::rowcolToCell(1,$spalte); 
 
   // 10  % Marge 
   $tabelle->writeNumber(2,$spalte, 0.10,$f_prozent); 
   $marge=Spreadsheet_Excel_Writer::rowcolToCell(2,$spalte); 
 
   // 16  % Steuer 
   $tabelle->writeNumber(3,$spalte, 0.16,$f_prozent); 
   $steuer=Spreadsheet_Excel_Writer::rowcolToCell(3,$spalte); 
 
   // Formel zum Berechnen des Verkaufspreises 
   $tabelle->writeFormula(4,$spalte, 
                          "=$ek+$ek*$marge*$steuer",$f_euro); 
} 
 
// A4-Papier 
$tabelle->setPaper(9); 
 
// Ueberschrift um 1 Zoll nach unten versetzt 
$tabelle->setHeader('Übersicht Jacke und Schuhe',1); 
 
// Fusszeile 
$tabelle->setFooter('Nur für den internen Gebrauch'); 
 
//Rahmen auf 2 Zoll festlegen 
$tabelle->setMarginTop(2); 
 
// Nur Daten fuer Jacke und Schuhe ausgeben 
$tabelle->printArea(0,2,4,3); 
 
// Ausgabe zentrieren 
$tabelle->centerVertically(); 
$tabelle->centerHorizontally(); 
// auf 200  % vergroessern 
$tabelle->setPrintScale(200); 
$tabelle->repeatColumns(0); 
$mappe->send(time().'.xls'); 
$mappe->close();

Listing 5.11 Ausgabe einer Tabelle mit Formatierung für den Druck

Die Darstellung dieses Codes in der normalen Excel-Ansicht finden Sie in Abbildung 5.7 und die Druckvorschau in Abbildung 5.8.

Abbildung 5.7 Darstellung der Tabelle in Excel

Abbildung 5.8 Druckvorschau in Excel

Abschließend bleibt zu sagen, dass das Paket noch ein paar Funktionen mehr bietet, als ich hier erwähnen konnte. Alles zu erläutern würde den Rahmen dieses Buches sprengen, aber ich denke doch, dass ich zumindest die interessantesten und wichtigsten Funktionen erwähnt habe.