Attachments Documentation

Version 1.3.4 - August 2008

  1. Introduction
  2. Uploading Restrictions
  3. Settings
  4. Display Filenames
  5. CSS Styling of Attachment Lists
  6. File Type Icons
  7. Warnings
  8. Upgrading
  9. 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): 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:
  1. [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 )
  2. 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.
  3. Uninstall the 'Attachments' component.
  4. Uninstall all of the 'Attachments' plugins
  5. 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.
  6. Reenable all of the 'Attachments' plugins.
  7. 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: [Back to top]

Please report bugs and suggestions to jmcameron@jmcameron.net.