Dokumentation der Joomla Erweiterung 'Attachments' (Anlagen)
Version 1.2 - 20. Februar 2008
- Einleitung
- Beschränkungen beim Upload (Hoch laden)
- Einstellungen für 'Attachments'
- Dateinamen anzeigen
- Formatierung der Anlagen-Liste
- Icons für Dateitypen
- Warnhinwise
- Aktualisieren ältere Versionen (Upgrade)
- Danksagungen
Einleitung
Die 'Attachments' Erweiterung ermöglicht es Dateien auf den Server
zu laden und als Anlage für Beiträge zu verwenden. Die 'Attachments'
Erweiterung beinhaltet ein Plugin um die Anlagen anzuzeigen und eine Komponente
um die Anlagen hoch zu laden und zu verwalten. Es gibt neben Einstellungen um festzulegen
wer die Anlagen sehen kann und wer sie hoch laden darf noch etliche weitere Einstellungen
um die Flexibilität und Nützlichkeit zu Erhöhen. Beachten Sie: Alle Einstellungen werden
durch den Komponenten Manager gesteuert. Die Erweiterung funktioniert nur unter Joomla! 1.5
oder höher.
Diese Erweiterung bietet Sprachversionierung an und unterstützt (neben Englisch) folgende
Sprachen:
- Chinesisch: Traditionelle und vereinfachte chinesische Übersetzung von
baijianpeng (http://www.joomlagate.com).
(Danke, baijaing!)
- Holländisch: Übersetzt von Parvus. (Danke, Parvus!)
- Deutsch: Übersetzt von Michael Scherer. (Danke, Michael!)
- Finnisch: Übersetzt von Tapani Lehtonen. (Danke, Tapani!)
- Norwegisch: Übersetzt von Espen Gjelsvik. (Danke, Espen!)
- Portugiesisch/Brasilianisch: Übersetzt von Arnaldo Giacomitti
(www.giacomitti.eng.br) und Cauan Cabral (www.cauancabral.net).
- Spanisch: Übersetzt von Carlos Alfaro. (Danke, Carlos!)
Vielen Dank an die Übersetzer! Wenn Sie bei der Übersetzung der Erweiterung in weitere Sprachen helfen wollen, nehmen Sie bitte Kontakt mit dem Autor auf (siehe unten).
[An den Anfang]
Beschränkungen beim Upload (Hoch laden)
Es können nicht alle Typen von Anlage Dateien hoch geladen werden. 'Attachments'
lässt es nicht zu Dateien hoch zu laden, die nicht vom Joomla! Media Manager zugelassen sind.
Um zu sehen (oder zu ändern) welche Dateitypen erlaubt sind, öffnen Sie die Konfiguration
der Site und wählen Sie die System Registerkarte. Im Bereich Medien finden Sie
Einstellungen um die Dateierweiterungen und MIME-Typen zu kontrollieren, die für Uploads erlaubt
sind. 'Attachments' hält sich an diese Beschränkungen. Die 'Erlaubten Erweiterungen für Bilder (Dateitypen)' werden jedoch nicht beachtet.
[An den Anfang]
Einstellungen für 'Attachments'
Alle Einstellungen für 'Attachments' werden über den Komponenten Manager gesteuert.
Um zu den Einstellungen zu gelangen, gehen Sie in den Adminbereich und wählen Sie im Erweiterungen Menü den Punkt Plugins aus. Wählen Sie 'Content-Attachments' zum Bearbeiten aus. Dort finden Sie auf der rechten Seite eine Reihe von Einstellungen. Diese Einstellungen umfassen folgende Punkte:
- Wer kann die Anlage sehen? Diese Einstellung
legt fest, wer Links zu Anlagen sehen kann. Es gibt derzeit zwei Möglichkeiten:
- 'Jeder' - Wenn dies ausgewählt wird, sind die Links für jeden sichtbar, der die Seite besucht, ob er angemeldet ist oder nicht.
- 'Jeder angemeldete Nutzer'. - Wenn dies ausgewählt wird, können nur Besucher der Seite, die auch angemeldet sind, die Links zu den Anlagen sehen.
- Wer kann Anlagen hinzufügen? Diese Einstellung legt fest, wer Anlagen zu einem Artikel hinzufügen darf. Es gibt zwei Möglichkeiten:
- 'Nur der Autor des Artikels' - Die Links um Anlagen hoch zu laden werden nur dem Autor eines Artikels angezeigt.
- 'Jeder angemeldete Nutzer' - Die Links um Anlage hoch zu laden werden jedem angemeldeten Nutzer angezeigt.
- Anlagen standardmäßig veröffentlichen? Diese 'automatisch veröffentlichen' Eigenschaft steuert es, ob Anlagen standardmäßig veröffentlicht werden, wenn Sie angefügt werden oder nicht. Wenn Anlagen hinzugefügt werden und es ist hier 'Ja' ausgewählt, dann werden sie umgehend veröffentlicht und sind für jeden Nutzer sichtbar. Wenn 'Nein' ausgewählt ist, werden neue Anlagen nicht automatisch veröffentlicht. Ein Administrator muss diese Anlagen vom Backend (Administrationsbereich) aus veröffentlichen um sie für die Nutzer sichtbar zu machen.
- Warnmeldung zur standardmäßigen Veröffentlichung: Sie können die Autoren informieren, die, bei abgeschalteter 'automatisch veröffentlichen' Eigenschaft (siehe vorangegangene Einstellung), Anlagen hinzufügen, wie sie ihre Anlagen freischalten lassen können. Eine entsprechende Meldung können Sie hier eingeben. Wenn das Feld leer ist, wird eine allgemeine System-Nachricht ausgegeben, unter der Annahme, dass der Systemadministrator wegen jeder neu hoch geladenen Anlage kontaktiert werde muss.
- Überschriften anzeigen: Wenn 'Ja' aktiviert ist, wird eine Reihe mit Überschriften über der Liste der Anlagen angezeigt, mit einer Beschreibung, was in jeder Spalte zu sehen ist.
- Beschreibung der Anlage anzeigen? Diese Einstellung legt fest, ob die Beschreibung von jeder Anlage angezeigt werden soll.
- Dateigröße der Anlage anzeigen? Diese Einstellung legt fest, ob für jede Anlage die Dateigröße angezeigt werden soll.
- Änderungsdatum anzeigen? Diese Einstellung legt fest, ob das Änderungsdatum für eine Anlage-Datei angezeigt werden ('Ja') soll oder nicht ('Nein').
- Formatierung für das Änderungsdatum der Anlage:
Sie können ein Format für das Datum bestimmen, indem Sie eine Formatierung entsprechend der PHP date Funktion verwenden. Diese Einstellung ist standardmäßig mit 'M-j-Y g:ia' vorbelegt, was folgender Ausgabe entspricht: 'Sep-29-2007 5:05pm'. Wenn Sie nur das Datum ohne Uhrzeit sehen wollen, dann entfernen Sie folgenden Teil der Formatierung: 'g:ia'
- Maximale Länge des Dateinamens:
Maximale Länge des Dateinamens für die Anlagen-Liste. Dateinamen die länger sind werden gekürzt und unter "display filename" in der Datenbank gespeichert (nur zur Darstellung, der tatsächliche Dateinamen wird nicht geändert). Ein Wert von 0 heißt, dass die Länge des Dateinamens durch diese Einstellung nicht beschränkt wird (Das Feld in der attachments Datenbanktabelle ist auf 80 Zeichen limitiert).
- CSS style für Anlagen Tabelle: Um vorhandene CSS styles der Anlagen-Liste (Tabellen) zu überschreiben, geben Sie bitte hier Ihren eigenen style-Namen an. Der standardmäßige style-Name ist 'attachmentsList'. Beachten Sie den Abschnitt [Formatierung der Anlagen-Liste] für weitere Informationen.
- Modus zum Öffnen der Datei:
Legt fest wie der Link zu Anlagen-Dateien geöffnet wird. 'Im gleichen Fenster' heißt, dass die Datei im gleichen Browserfenster geöffnet wird. 'In einem neuen Fenster' heißt, dass die Datei in einem neuen Browserfenster geöffnet wird. In einigen Browsern führt die Einstellung 'In einem neuen Fenster' dazu, dass ein neuer Tab geöffnet wird.
- Dem System-Dateinamen voranstellen: Diese Einstellung legt fest, ob dem gespeicherten Anlagen-Dateinamen auf dem Server ein numerisches Präfix vorangestellt werden soll oder nicht.
Es gibt drei Möglichkeiten:
- 'ID des Artikels' - Wenn diese Einstellung ausgewählt ist, bekommt der Dateiname die Artikel Id Nummer vorangestellt. Diese Auswahl reduziert die Wahrscheinlichkeit von Dateinamenskonflikten und gewährleisten, dass die Anlagen-Dateien für einen speziellen Artikel in der Ordneransicht zusammen sortiert werden.
Beachten Sie auch, dass mit dieser Einstellung unterschiedliche Dateien mit dem gleichen Dateinamen an verschiedene Artikel angehängt werden können, aber nicht an den selben Artikel
- 'ID der Anlage' - Wenn diese Einstellung ausgewählt ist, bekommt der Dateiname die Anlagen Id Nummer vorangestellt.
Diese Auswahl verhindert jeden Dateinamenskonflikt, da jede Anlagendatei eine eindeutige ID-Nummer erhält. Die Dateien werden in der Ordneransicht in der Reihenfolge der Anlagen(-ID) sortiert.
- 'Nichts' - Wenn diese Einstellung ausgewählt ist, wird der Dateiname so gespeichert, wie er übergeben wurde und erhält keinerlei Präfix. Diese Auswahl erhöht die Wahrscheinlichkeit von Dateinamenskonflikten, da jede hoch geladene Datei einen eindeutigen Dateinamen haben muss.
- Unterverzeichnis für hoch geladenen Dateien:
Die Programmierung der 'Attachments' Erweiterung legt Dateien
in dieses Unterverzeichnis unter der obersten Eben der Joomla! Site.
WARNUNG: Bei Änderungen müssen Sie das neue Unterverzeichnis per Hand erzeugen, bevor Sie weitere Anlagen hoch laden.
Beachten Sie, dass ein verändertes Unterverzeichnis nur die kommenden Uploads betrifft. Vor der Änderung hoch geladene Dateien bleiben im alten Unterverzeichnis und die Einträge in der attachments Datenbank verweisen weiterhin auf diese Dateien.
- Angepasste Überschriften für Anlagen-Listen:
Standardmäßig fügt 'Attachments' die Überschrift 'Anlagen:'
über der Liste der Anlagen eines Artikels ein (wenn der Artikel Anlagen hat).
In manchen Fällen könnte es sein, dass sie für bestimmte Artikel eine andere Überschrift wählen möchten. Sie können den exakten Ausdruck, den Sie verwenden möchten, auf einer Artikel-zu-Artikel Basis angeben. Wenn Sie z.B. für den Artikel 211 die angepasste Überschrift 'Downloads:' verwenden möchten, dann fügen Sie folgendes
zu dieser Einstellung hinzu: '211 Downloads' (ohne die Anführungsstriche).
Verwenden Sie pro Eintrag eine Zeile.
- Blende Anlagen aus für
Durch Kommas getrennte Liste von Schlüsselwörtern oder Bereiche/Kategorien von Artikeln für die die Liste der Anlagen nicht angezeigt werden soll. Zwei besondere Schlüsselwörter können verwendet werden: 'frontpage' um die Anzeige von Anlagen auf der Startseite zu verhindern und 'all_but_article_views' um Anlagen nur in der Artikelansicht darzustellen. (Lassen Sie die Anführungszeichen weg, wenn Sie die Schlüsselwörter in das Feld für die Schlüsselwörter[keywords options] eingeben.) Die Bereichs/Kategorie Ids sollten, getrennt durch einen Schrägstrich(/), als numerische Bereichs und Kategorie IDs eingegeben werden: Bereichs#/Kategorie#, Bereichs#/Kategorie#. Geben Sie nur 'Bereichs#' an um alle Kategorien dieses Bereichs mit einzuschließen. Beispiel: 23/10, 23/11, 24.
- Sicherer Anlagen Download:
Standardmäßig speichert die 'Attachments' Erweiterung Dateien in einem öffentlich zugängliches Unterverzeichnis. Wenn Sie die sichere Art des Download wählen werden die Anlage-Dateien in einem geschützten Unterverzeichnis abgelegt. Die Links im Frontend zum Herunterladen (Downloadlinks) der Anlagen laden zwar die Dateien herunter, sind jedoch keine direkten Links. Das schützt vor unberechtigtem Zugriff, wenn die Nutzer nicht die entsprechende Rechte besitzen. Wenn die sichere Art des Download nicht ausgewählt ist, werden die Links zu den Anlagen entsprechend den obigen Einstellungen angezeigt, die Dateien sind jedoch für jeden abrufbar, der die komplette URL kennt, da das Unterverzeichnis öffentlich ist. Die sichere Einstellung verhindert den Zugriff von Unberechtigten, selbst wenn diese die komplette URL kennen, da diese Einstellung den öffentlichem Zugriff auf das Unterverzeichnis der Anlagen verhindert.
ANMERKUNG: Im sicheren Modus wird die Anlagenliste nicht angezeigt, wenn der Nutzer nicht angemeldet ist, weil es keinen Sinn macht den sicheren Modus zu nutzen außer die Nutzer sind angemeldet.
- Modus für den sicheren Download:
Diese Einstellung steuert, ob Anlage-Dateien als separate Dateien herunter geladen oder im Browserfenster dargestellt werden (wenn der Browser mit dem Dateityp umgehen kann). Es gibt zwei Möglichkeiten:
- 'eingebettet': In diesem Modus werden Dateien, die vom Browser angezeigt werden können (wie Textdateien und Bilder), im Browser angezeigt.
- 'angehängt': In diesem Modus werden Anlagen immer als separate Dateien heruntergeladen.
In jedem Fall werden Anlagen, die nicht im Browser dargestellt werden können als externe Dateien heruntergeladen.
[An den Anfang]
Dateinamen anzeigen
In der Regel wird der volle Dateiname als Link zum Herunterladen der Anlage angezeigt,
wenn Dateien hoch geladen wurden und eine Liste der Anlagen angezeigt wird. In einigen
Fällen könnte der Dateiname zu lang sein um gut dargestellt zu werden. Im Formular zum
Hoch laden gibt es ein weiteres Feld mit der Bezeichnung "Dateinamen anzeigen" in welches
die Person, welche die Datei hoch lädt einen alternativen Dateinamen oder eine Bezeichnung angeben kann,
der/die anstatt des vollen Dateinamens angezeigt wird.
Es könnte z.B. eine Abkürzung des Dateinamens in dieses Feld eingegeben werden.
Das Feld kann, beim Bearbeiten einer Anlage über den Administrationsbereich (Backend), verändert werden.
ANMERKUNG: Es gibt in den Plugin-Einstellungen eine Einstellung "Maximale Länge des Dateinamens".
Es kann verwendet werden um automatisch die Dateinamen hoch geladener Anlagen verkürzt darzustellen; der
dabei entstehende verkürzte Dateinamen wird in das "Dateinamen anzeigen" Feld eingetragen.
[An den Anfang]
Formatierung der Anlagen-Liste
Die Liste der Anlagen wird im Frontend in ein spezielles 'div' eingebunden, welches eine Tabelle für die Anlagen enthält. Die Tabelle ist mit mehreren unterschiedlichen CSS Klassen verknüpft, die dem Webentwickler eine flexible Anpassung der Darstellung der Tabelle erlauben. Schauen Sie in die 'Attachments' Plugin CSS Datei (in plugins/content/attachments.css) um Beispiele zu sehen.
Wenn Sie die Styles ändern wollen, überlegen Sie, ob Sie nicht die originalen Styles an das Ende der gleichen Datei kopieren und 'attachmentsList' im kopierten Bereich in eine eigene Klasse umbenennen. Ändern Sie im Komponenten Manager für die 'Attachments' Komponente ('Artikel Anlagen') die Einstellung CSS style für Anlagen Tabelle um in den neuen Klassennamen.
Dann ändern Sie die Klassendefinitionen in Ihrem kopierten Bereich passend ab. Dieses Vorgehen erlaubt Ihnen schnell in den Ursprungszustand zurück zu kehren, indem Sie CSS style für Anlagen Tabelle wieder in den Standard 'attachmentList' umbenennen.
Es hat außerdem den Vorteil, dass der Bereich der geänderten Styles schnell in eine Datei kopiert werden kann und nach einer Aktualisierung von 'Attachments' wieder zurück. Dies kann ebenfalls mittels CSS @import Anweisung gelöst werden.
[An den Anfang]
Icons für Dateitypen
Die 'Attachments' Erweiterung stellt in der Liste der Anlagen jeder Anlage ein Icon voran.
Folgen Sie diesen Schritten, wenn Sie ein neues Icon hinzufügen wollen:
(1) Fügen Sie im Verzeichnis 'media/attachments/icons' ein passendes Icon hinzu, wenn noch kein passendes vorhanden ist;
(2) Öffnen Sie die Datei 'components/com_attachments/file_types.php' und fügen Sie eine passende Zeile zu dem
static array $attachments_icon_from_file_extension welches eine Dateierweiterung einem Iconnamen zuordnet (alle aus dem Verzeichnis
media/attachments/icons directory). Wenn dies nicht funktioniert, müssen Sie eine passende Zeile zu dem array $attachments_icon_from_mime_type hinzufügen.
(3) Vergessen Sie nicht Kopien von der Icon-Datei und der geänderten file_types.php in ein Verzeichnis außerhalb der Website zu machen, bevor Sie in der Zukunft die Version von 'Attachments' aktualisieren.
[An den Anfang]
Warnhinweise
- Benutzen Sie die Sicherer Anlagen Download Einstellung, wenn Sie sensible oder private Anlagen haben!
Wenn Sie nicht die sichere Einstellung wählen, werden die Anlagen Dateien in eine öffentliches Unterverzeichnis geladen und sind für
jeden erreichbar, der die komplette URL kennt. Die sichere Einstellung verhindert den Zugriff durch jeden, der nicht die entsprechenden Rechte besitzt (wie in den oberen Einstellungen festgelegt). Beachten Sie die obige Besprechung der Sicherer Anlagen Download Einstellung für weitere Details.
- Jedes Mal, wenn eine Datei hoch geladen wird, wird die Existenz des upload
Unterverzeichnisses überprüft. Das Verzeichnis wird angelegt, wenn es nicht existiert.
Wenn der 'Attachments' Erweiterung nicht möglich ist, das Unterverzeichnis
für den Upload zu erstellen, müssen Sie es selber anlegen (und Sie könnten Probleme
haben Dateien hoch zu laden). Stellen Sie sicher, dass Sie dem Unterverzeichnis passende
Rechte geben um Dateien hoch zu laden. In der Unix/Linux Welt, ist das vermutlich etwas wie 744.
- Wenn diese Erweiterung es Ihnen nicht erlaubt bestimmte Dateitypen hoch zu laden
(solche wie zip-Dateien), dann seien Sie sich bewusst, dass diese Erweiterung die Einschränkungen vom Medien Manager für den Upload von Dateitypen berücksichtigt. Dies geschieht um das hoch laden von potentiell gefährlichen Dateitypen wie html oder php Dateien zu verhindern.
Der Administrator kann die Einstellungen des Medien Managers verändern um spezielle Dateitypen hinzuzufügen, indem er zu "Konfiguration" unter dem "Site" Menü geht und die "System" Registerkarte auswählt. Hier kann er die gewünschten Dateierweiterungen und MIME Typen zu der Liste im "Medien" Bereich hinzufügen.
- Das zweite Plugin 'add_attachment_btn_plugin' (im Plugin Manager 'Button - AddAttachment' genannt)
erlaubt es Anlagen zu Artikeln hinzuzufügen während diese im Artikeleditor bearbeitet werden. Das Plugin fügt direkt unter dem
Eingabebereich für den Artikel eine Schaltfläche (Button) mit der Aufschrift "Anlage Hinzufügen" ein. Wenn Sie dieses Plugin
installiert haben, aber die Schaltfläche nicht sehen, dann müssen sie möglicherweise das Button Plugin im Plugin Manager aktivieren.
ANMERKUNG: Die Schaltfläche wird nicht angezeigt, wenn der Artikel das erste Mal erstellt wird, da ein Artikel zumindest einmal gespeichert werden muss, bevor Dateien an ihn angefügt werden können.
- Diese Version scheint korrekt mit SEF (Suchmaschinen-Freundliche URLs) mit JOOMLA! 1.5 RC3 und RC4 zu arbeiten. Die Aktualisierung
von 'Attachments' für RC3 scheint SEF mit RC2 zu zerstören.
[An den Anfang]
Aktualisieren ältere Versionen (Upgrade)
Wenn Sie bereits Anlagen hoch geladen haben, die sie über eine Aktualisierung hinaus erhalten möchten,
dann gehen Sie bitte folgendermaßen vor:
- Verwenden Sie phpMyAdmin (ein anderes SQL Dumping Tool) um die
Inhalte der jos_attachments Tabelle zu sichern (Verwenden Sie die 'Export' Option und wählen Sie "'Complete' inserts" (Vollständige 'INSERT's) aber nicht "'Extended' inserts" (Erweiterte 'INSERT's) für die Daten.).
- Deinstallieren Sie die 'Attachments' Komponente.
- Deinstallieren Sie die 'Attachments' Plugins
- Installieren Sie nun das neue Release, indem Sie die Release-Datei entpacken und dann
das neue Plugin installieren und anschließende die neue Komponente.
- Reaktivieren Sie das 'Attachments' Plugin.
- Zum Schluss verwenden sie phpMyAdmin um die vorher gesicherten Daten wieder in die neu erstellte
jos_attachments Tabelle zu laden.
- Wenn Sie von einer früheren Version als 1.0 auf eine Version nach 1.0 aktualisieren und alte Anlagen
besitzen, müssen Sie passenden Werte in das neue 'icon_filename' eintragen. Sie müssen sich
dazu als Administrator am Backend anmelden und folgende URL in Ihren Browser eingeben:
/administrator/index.php?option=com_attachments&task=add_icon_filenames
Beachten Sie, dass die Deinstallation der 'Attachments' Erweiterung nicht die
bereits hoch geladenen Anlage-Dateien löscht, jedoch die Anlagen Tabelle (attachments
table) aus der Datenbank entfernt. Deshalb ist es nach der (erneuten) Installation einer neuen Version von
'Attachments' nur notwendig die Anlagen Tabelle (attachments
table) wieder herzustellen um alle alten Anlagen wieder zu erhalten.
Wenn Sie sich entscheiden die Anlagen Datenbank nicht wieder herzustellen, dann
vergessen Sie bitte nicht, alle unnötigen Dateien aus dem Unterverzeichnis der
Anlagen zu löschen um im Weiteren Dateinamenskonflikte zu vermeiden.
[An den Anfang]
Danksagungen
Vielen Dank an folgende Mitwirkende oder Quellen:
- Das Buch Learning Joomla! 1.5 Extension Development: Creating Modules,
Components, and Plugins with PHP von Joseph L. LeBlanc war sehr Hilfreich
bei der Erstellung der 'Attachments' Erweiterung.
- Die Icons für die Dateitypen stammen aus unterschiedlichen Quellen, u.a.:
Beachten Sie, dass die meisten Icons der 'Attachments' Erweiterung von den original Icons abgeänderte Versionen sind. Wenn Sie die Originalversionen verwenden möchten, laden Sie diese bitte von den entsprechenden Websites herunter.
[An den Anfang]
Bitte melden Sie Fehler und Anregungen (in englisch) an jmcameron@jmcameron.net.