Attachments Documentation


Version 2.0 - April 2010

Contents

Introduction

The 'Attachments' extension for Joomla! allows files to be uploaded and attached to articles or other types of content. '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. It has not been tested with version 1.6.

The 'Attachments' extension has been translated into many different languages. Please see the Translations section for the list of available translations. Most of these languages packs are in the process of being updated for 'Attachments' version 2.0.

If you wish to subscribe to an email list for announcements about this extension, please subscribe using this web page:

New features in Version 2.0

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' extension respects these limitations. However, the restriction on 'Legal Image Extensions (File Types)' is ignored.

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 "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:

Display Filename or URL

Normally, when files are uploaded (or URLs are installed) and listed in a list of attachments, the full filename (or URL) is shown as a link to download the attachment. In some cases, the filename (or URL) may be too long for this to work nicely. In the upload form, there is another field called "Display Filename or URL" in which the person uploading the file can insert an alternative filename (or URL) or label to display instead of the full filename (or URL). 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 or URL Length" in the 'Attachments' extension options. It can be set to automatically truncate uploaded displayed filenames; the resulting truncated filename will be inserted into the "Display Filename or URL" field.

Attaching URLs

A new feature in 'Attachments' version 2.0 is the ability to "attach" URLs to content items. When you bring up one of the "Add attachment" dialog boxes, you will see a button labeled as "Enter URL instead". If you click on it you will get an entry field for the URL and see two options:

The URLs are shown with the file-type icon and overlaid with an arrow (indicating that it is a good link) or an red diagonal slash (indicating that it could not be validated). When you edit a URL, you can change whether the link is valid or not to get the overlay you wish. Also note that URL overlays can be disabled entirely using the main Superimpose URL link icons parameter. There are several useful commands relating to URLs (and files) in the "Utilities" command in the back end.

What Can Files Be Attached To?

Besides attaching files or URLs to articles, it is now possible to attach files or URLs to other types of content items such as Sections and Categories (see below). If appropriate 'Attachments' plugins are installed, it may be possible to attach files or URLs to a wide variety of content items such as user profiles, shopping cart product descriptions, etc. Basically any content item that is displayed on the front end and uses the content event 'onPrepareContent' can host attachments (if a suitable 'Attachments' plugin is installed). Content items that invoke content events are typically items that have content to be displayed (such as articles) or have descriptions that will be displayed.

Attaching Files or URLs to Section or Category Descriptions

With this version of attachments, users can attach files to Section and Category descriptions. These descriptions are generally only visible on Section or Category Blog pages, if the basic parameter 'description' is set to Show (via the Menu Editor). Also note that it is not possible to attach files or URLs to Section or Category descriptions in the Section or Category editor. They must be attached using the administrative back end ("Attachments" under the "Component" menu item) or from the front end.

If you wish to learn more about how to develop a new Attachment plugin, there is a manual that is available as part of this 'Attachments' installation:

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, 'attachmentsList'. 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.

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.

Translations

This extension provides translation capabilities and supports the following languages (besides English). Note that most of these languages packs are in the process of being updated for 'Attachments' version 2.0. Thanks to these translators (available versions shown in parentheses):

Also, new translations are being developed for Arabic and Turkish.

Many thanks to these translators! If you would like to help translate the extension to any other language, please contact the author (see the Contact section at the end).

Warnings

Upgrading

Upgrading is much easier now. Simply install the new version of 'Attachments'.

Acknowledgements

Many thanks for the following contributors or resources:

Contact

Please report bugs and suggestions to jmcameron@jmcameron.net