Attachments Documentation
Version 1.3.4 - August 2008
- Introduction
- Uploading Restrictions
- Settings
- Display Filenames
- CSS Styling of Attachment Lists
- File Type Icons
- Warnings
- Upgrading
- Acknowledgements
Introduction
The 'Attachments' extension for Joomla! allows files to be uploaded
and attached to content articles. 'Attachments' includes a
plugin to display the attachments and a component for uploading and managing
attachments. There are options to control who can see the attachments and
who can upload them, along with several other options to increase its
flexibility and usefulness. Note: all options are controlled through
the component manager. This extension only works for Joomla! 1.5 or later.
If you wish to subsribe to an email list for announcements about
this extension, please subscribe using this web page:
This extension provides translation capabilities and supports the following
languages (besides English):
- Bulgarian: This translation was done by Stefan Ilivanov. (Thanks Stefan!)
- Chinese: Traditional and simplified Chinese translations by baijianpeng
(http://www.joomlagate.com). (Thanks baijaing!)
- Dutch: This translation was done by Parvus. (Thanks Parvus!)
- Finnish: This translation was done by Tapani Lehtonen. (Thanks Tapani!)
- French: This translation was done by Pascal Adalian. (Thanks Pascal!)
- German: This translation was done by Michael Scherer. (Thanks Michael!)
- Greek: This translation was done by Harry Nakos. (Thanks Harry!)
- Italian: This translation was done by Lemminkainen. (Thanks Lemminkainen!)
- Norwegian: This translation was done by Espen Gjelsvik. (Thanks Espen!)
- Persian: This translation was done by Hossein Moradgholi of the Parsjoomla project. (Thanks Hossein!)
- Polish: This translation was done by Piotr Wójcik. (Thanks Piotr!)
- Portuguese/Brazilian: This translation was done by Arnaldo Giacomitti
(www.giacomitti.eng.br) and Cauan Cabral (www.cauancabral.net).
- Spanish: This translation was done by Carlos Alfaro. (Thanks Carlos!)
Many thanks to the translators! If you would like to help translate the
extension to any other language, please contact the author (see end).
[Back to top]
Uploading Restrictions
Not all types of attachment files can be uploaded. The 'Attachments' extension
will not allow uploading of files that are not permitted by the Joomla! Media Manager.
To see (or change) what file types are allowed, go to the Global Configuration
page and click on the System tab. In the Media Settings area, there are
options for controlling what types of file extensions and mime types are permitted
for uploads. The 'Attachments' respects these limitations. However, the
restriction on 'Legal Image Extensions (File Types)' is ignored.
[Back to top]
Attachments Settings
All of the settings for 'Attachments' are controlled via the
component manager. To access these settings, go to the administrative
back end and select "Article Attachments" under the "Component" menu. Click
on the "Parameters" button on the right end of the tool bar and you will see
a series of parameters for this extension. These parameters include
the following:
[Back to top]
Display Filename
Normally, when files are uploaded and listed in a list of attachments, the full
filename is shown as a link to download the attachment. In some cases, the
filenames may be too long for this to work nicely. In the upload form, there is
another field called "Display Filename" in which the person uploading the file
can insert an alternative filename or label to display instead of the full filename.
For instance, some abbreviation of the filename could be added in this field. The
field may be edited in the administrative back end when attachments are edited.
Note: There is an option called "Maximum Filename Length" in the plugin options.
It can be set to automatically truncate uploaded displayed filenames; the
resulting truncated filename will be inserted into the "Display Filename" field.
[Back to top]
CSS Styling of Attachment Lists
The lists of attachments on the front end are done using a special
'div' that contains a table for the attachments. The table has
several different CSS classes associated with it to allow the website
developer the flexibility to customize the appearance of the table. Look in
the attachments plugin file CSS file (in plugins/content/attachments.css) for
examples. If you wish to change the style, consider copying the original
styles into the end of the same file and renaming 'attachmentsList' in the
copied section to something of your choice. Edit the Attachments parameter
(in the component manager) and change the parameter attachments table style
to the new class name. Then modify the class definitions in your copied section
appropriately. This approach will allow you to quickly revert to the original
style by changing the plugin parameter attachments table style back to
its default, 'attachmentList'. This also has the advantage that the
section of modified styles can be copied to a file and easily brought back in
when the version of Attachments is upgraded. This could also be done via a
CSS @import command.
[Back to top]
File Type Icons
The 'Attachments' extension adds an icon in front of each attachment in the
list of attachments. If you wish to add a new icon type, follow these steps:
(1) Add an appropriate icon in the directory 'media/attachments/icons', if an
appropriate icon is not already there; (2) Edit the file
'components/com_attachments/file_types.php' and add an appropriate line to the
static array $attachments_icon_from_file_extension which maps a file extension to an icon
name (all in the media/attachments/icons directory). If this does not work,
you may need to add an appropriate line to the array $attachments_icon_from_mime_type. (3)
Don't forget to make copies of the icon file and the updated file_types.php to
some directory outside of the website directories before upgrading the version
of Attachments in the future.
[Back to top]
Warnings
[Back to top]
Upgrading
If you have previously added attachments that you wish to preserve
through an upgrade, use these steps:
- [This step is optional but encouraged, to make sure you have
a backup of the attachments database in case something goes wrong.]
Use phpMyAdmin
(or other SQL editing tool) to save the contents
of the jos_attachments table (Use the 'Export' option with
'Complete' inserts for data (not 'Extended' inserts). You should also
back up the uploaded attachments files (usually in the 'attachments'
directory )
- Go to the Attachments manager in the administrative back end and
click on the item labelled 'Admin' on the right end of the toolbar.
Click on the command 'Disable uninstallation of MySQL Attachments Table'.
This disables the deletion of the attachments database table during
uninstallation of the attachments component.
- Uninstall the 'Attachments' component.
- Uninstall all of the 'Attachments' plugins
- Now install the new release by unziping the release file and
installing all of the new plugins and then the component.
During the installation of the component, the attachments database
table will be updated automatically.
- Reenable all of the 'Attachments' plugins.
- Your attachments should be available again. Go to the Attachments
manager in the administrative back end to verify that your attachments
are okay.
Note that uninstalling the 'Attachments' extension does not
delete the previously uploaded files, but it does remove the attachments
table in the database. So after reinstalling a new version of
'Attachments', it is only necessary to restore the attachments
table to restore all the old attachments.
If you decide not to restore the attachments database, do not forget to delete any
obsolete uploaded files in the attachments subdirectory to avoid filename conflicts
in the future. [Back to top]
Acknowledgements
Many thanks for the following contributors or resources:
- The book Learning Joomla! 1.5 Extension Development: Creating Modules,
Components, and Plugins with PHP by Joseph L. LeBlanc was very helpful
in creating the 'Attachments' extension.
- Many thanks to Paul McDermott for generously donating the search plugin!
This is a very helpful addition!
- The icons for the file types were derived from several sources, including:
Note that most of the 'Attachments' icons were modified from the original
icon images from these websites. If you would like the original versions,
please download them from these websites.
[Back to top]
Please report bugs and suggestions to jmcameron@jmcameron.net.