Attachments Documentation
Version 1.2 - February 20, 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.
This extension provides translation capabilities and supports the following
languages (besides English):
- Chinese: Traditional and simplified Chinese translations by baijianpeng
(http://www.joomlagate.com). (Thanks baijaing!)
- Dutch: This translation was done by Parvus. (Thanks Parvus!)
- German: This translation was done by Michael Scherer. (Thanks Michael!)
- Finnish: This translation was done by Tapani Lehtonen. (Thanks Tapani!)
- French: This translation was done by Pascal Adalian. (Thanks Pascal!)
- Norwegian: This translation was done by Espen Gjelsvik. (Thanks Espen!)
- 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'
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:
- Who can see attachments: This setting controls
who will be able to see the links for the attachments. There are
currently two options:
- 'anyone' - If this option is selected, the links to the
attachments will be visible to anyone visiting the website, whether
they are logged in or not.
- 'any logged-in user'. - If this option is selected, only
users who are logged into the website will be able to see the links
to the attachments.
- Who can add attachments: This setting controls
who is able to add attachments to articles. There are two
options:
- 'Article author only' - The links to upload articles will only
be visible to the author of the article.
- 'Any logged-in user' - The links to upload articles will be
visible to any user who is logged in.
- Attachments published by default: This 'auto
publish' feature controls whether new attachments are published by
default when they are added. If 'Yes' is selected, when articles
are added, they will published immediately and will be visible to users. If
'No' is selected, new articles will not be published by default.
An administrator will need to publish them from the administrative back end
before the articles will be available.
- Auto Publish Warning: If the auto-publish option is
disabled (see previous option), you may wish to inform those adding
attachments how they can get their attachment published. You can insert an
appropriate message here. If this field is empty, a general system message
will be added suggesting that they contact their system administrator to
any newly uploaded attachments published.
- Show titles: If set to 'Yes', a row of titles will be
added above the list of attachments describing what is in each column.
- Show attachment description: This setting controls
whether the attachment description is shown in the list of attachments.
- Show file size: This setting controls
whether the attachment file size is shown in the list of attachments.
- Show file modification date: If this setting
is 'Yes', the modification date for the file will be added to the
attachment list for articles that have attachments. If 'No' is
selected, no date will be added to the attachment list.
- Format string for modification date: You may
select the format for the modification date by using the format
used by the PHP date function. This setting defaults to "M-j-Y g:ia"
which looks something like this: "Sep-29-2007 5:05pm". If you
prefer to see only the date, remove the "g:ia" part of the
string.
- Maximum filename length:
The maximum filename length for attachments list. Filenames longer than
this will be truncated and put into the display filename (for display purposes
only, the actual filename will not be changed). A value of 0 means the
filename length is unlimited by this option (the filename field in the attachments
database table is limited to 80 characters). Note: If display filenames are truncated
by this option, the truncated filename will be inserted into the "display filename"
field.
- CSS style for attachments tables: To override the CSS
styling of attachments lists, specify your own style name here. The default
style name is 'attachmentsList'. See the [Styling
Attachment Lists] section for more information.
- File link open mode:
This mode how the links to attachment files will be opened. 'In same window'
means the file will be opened in the same browser window. 'In new window'
means the file will be opened in a new window. In some browsers, using the
'In new window' option will actually open the attachment in a new tab.
- Prepend to system filename: This setting
controls whether a numeric prefix should be added to the start
the image filename as it is stored on the server. There are three options:
- 'Article ID' - If this option is selected, the filename
will be prefixed with the article's id number. This choice will
reduce chances of filename collisions and will ensure that the
attachment files for a particular article will sort together in
directory listings. Also note that this option will allow different
files with the same filenames to be attached to different articles, but
not to the same article.
- 'Attachment ID' - If this option is selected, the filename
will be prefixed with the attachment's id number. This choice will
eliminates the possibility of filename collision since each attachment will
always have a unique ID number. The attachment files will sort by the
order of attachment in directory listings.
- 'Nothing' - If this option is selected, the filename
will be saved as given and will not be prefixed with anything. This
option increases the chance of filename collisions since
every uploaded file will need to have a unique filename.
- Subdirectory for uploads: The 'Attachments'
extension code will put files into this subdirectory unde the top
of the Joomla site. WARNING: If this is changed, you must create
the new subdirectory manually before uploading any more attachments.
Note that if this subdirectory is changed, it will only affect future
uploads. Previously uploaded files will stay in the old subdirectory
and records in the attachments database will still point to those files.
- Custom titles for attachments lists: By
default, the 'Attachments' extension inserts the title
"Attachments:" above the list of attachments for an article (if it has
attachments). In some cases, you may prefer using some other term for
specific articles. You may specify the exact term you would like to
use on an article-by-article basis. For example, if you would like article
211 to use the custom title "Downloads:", then add this to this setting:
'211 Downloads' (without the quotes). Use one entry per line.
- Hide Attachments for:
Comma-separated list of keywords or Sections/Categories of articles for which
the attachments list should be hidden. Two special keywords can be used:
'frontpage' to suppress displays of attachments on the front page and
'all_but_article_views' to allow displays of attachments only in article views.
(Omit quotes when entering the keyword options.) The Section/Category IDs
should be entered as numeric section and category IDs separated with a slash(/):
Section#/Category#, Section#/Category#. Specify just 'Section#' to cover all
Categories within the Section. Examples: 23/10, 23/11, 24
- Secure attachment downloads: By default, the 'Attachments'
extension saves attachment files in a publically accessible subdirectory. If you choose
the secure option, the directory in which the attachments are saved will be made
publically inaccessible. The download links for the attachments in the front end will
download the attachment files but will not be direct links. This will prevent access
unless users have appropriate permissions. If secure downloads are not selected,
the links to the attachments will be shown as the options above indicate, but the files
will still be accessible to anyone if they know the full URL, since the subdirectory is
public. The secure option prevents access to users without appropriate
permissions even if they know the full URL, since this option prevents public access
to the attachments subdirectory. NOTE: In secure mode, the attachments list is
not displayed when the user is not logged in because it makes no sense to use secure mode
unless users are logged in.
- Download mode for secure downloads:
This option controls whether files should be downloaded as separate files or displayed
in the browser (if the browser can handle that type of file). There are two options:
- 'inline': In this mode, files that can be displayed by the browser will be
displayed in the browser (such as text files and images).
- 'attachment': With the 'attachment' mode, files will always be downloaded
as separate files.
In either case, files that can't be displayed in the browser will be
downloaded as external files.
[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
- If you have attachment files that are sensitive or private, use the
Secure attachment downloads option!
If you do not use the
secure option, the attachment files are saved in a public subdirectory
and are accessible to anyone that knows the full URL. The secure option
prevents access by anyone that does not have appropriate permissions (as determined
by the options above). See the discussion of the Secure attachment downloads
option above for more detail.
- Every time a file is uploaded, the existence of the upload subdirectory
is checked and it will be created if if it does not exist. If the
'Attachments' extension is unable to create the subdirectory
for uploads, you must create it yourself (and you may have problems uploading
files). Make sure to give the subdirectory suitable permissions for uploading
files. In the Unix/Linux world, that is probably something like 744.
- If this extension does not permit you to upload specific types of files
(such as zip files), be aware that the extension respects the restrictions
placed by the Media Manager on types of files permitted to be uploaded. This
is to prevent uploading of potentially harmful types of files such as html or
php files. The administrator can update the Media Manager settings to add
specific file types by going to the "Global Settings" item under the "Site"
menu, selecting the "System" tab, and added the appropriate file extension and
Mime type to the lists under the "Media Manager" section.
- The second plugin, 'add_attachment_btn_plugin' (called 'Button - AddAttachment'
in the plugin manager) allows attachments to be added to articles while they
are being edited in the article editor. This plugin adds a button just below
the article editing area labeled "Add Attachment". If you have installed this
plugin but do not see the button, the add attachment button plugin probably needs to
be enabled in the plugin editor. Note: The button is not display when articles
are first being created since an article must have been saved at least once
before files can be attached to it.
- If you cannot see the attachments in the front end, there are several possible reasons:
- The 'Content - Attachments' plugin is not enabled. Use the plugin manager
to enable it.
- The option 'Who can see attachments' is set to 'logged-in' and you are
not logged in. This can be changed via the Parameter editor in the
component manager.
- In the 'Content - Attachments' (via the plugin manager), the access
level is not set to 'Public'.
[Back to top]
Upgrading
If you have previously added attachments that you wish to preserve
through an upgrade, use these steps:
- Use phpMyAdmin
(or other SQL dumping tool) to save the contents
of the jos_attachments table (using the 'Export' option use
'Complete' inserts but not 'Extended' inserts for data).
- Uninstall the 'Attachments' component.
- Uninstall both of the 'Attachments' plugins
- Now install the new release by unziping the release file and
installing both of the new plugins and then the component.
- Reenable both of the 'Attachments' plugins.
- Finally use phpMyAdmin to reload the previously saved
attachments data into the newly created jos_attachments table.
- If you are upgrading from a version before 1.0 to one after 1.0 and you
have old attachments, you will need to add the appropriate values to the
new 'icon_filename' field by logging in as the administrator in the
back end and entering the following URL into your browser:
/administrator/index.php?option=com_attachments&task=add_icon_filenames
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 reinstallling 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.
- 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.