Attachment User Guide

This Guide is intended for all phpBB users using the Attachment Mod. It answers common questions and gives a quick overview of features and the internal workings of this Mod.

  1. Introduction
  2. Feature List
  3. What do you need in order to run certain features
  4. Admin Rights or 'Why do you need a User Account' ?
  5. The Attachment Administration Panels
    1. Control Panel
    2. Management
    3. Quota Limits
    4. Shadow Attachments
    5. Synchronize Attachments
  6. The Extensions Administration Panels
    1. Extension Control
    2. Extension Groups Control
      1. Extension Groups Forum Permissions
    3. Forbidden Extensions
    4. Special Categories
  7. General Administrative Settings and Features (HowTo's)
    1. How to set up Permissions for Attaching and Downloading
    2. The Quota System
    3. How to set up Default quotas
    4. How to set up User and Group quotas
    5. How Quota Limit Changes will affect User and Group Quotas
    6. How to get Thumbnails working
  8. How to use the Attachment Mod
    1. Posting and Editing Attachments - Posts and Private Messages
    2. Additional Viewable Areas
      1. User Profiles
      2. User Attachment Control Panel
  9. Common Problems attaching Files
    1. Filesize too big / Post Mode not specified / Blank Page
    2. Could not attach File, but Post has been stored / Filesize is 0 all over the time
    3. General Error: Could not Attach File
    4. I am able to attach files in Private Messages, but with normal Posts i cannot Attach files
    5. No Attachments are displayed
  10. Copyright and Disclaimer

1. Introduction

This User Guide is intended to give an overview of what the Attachment Modification is capable of and teach you how to setup and utilize its features. It should answer the most common questions and give you the chance to use the full power of the Attachment Mod.

While reading this, you will stumble over some terms and explanations you might not know; keep these in mind, they may be explained in further paragraphs. If you find errors or would like to contribute something please contact me.

If you have Support Questions, please go to the Opentools Board and ask your Question there.

Happy reading, Acyd Burn.

2. Feature List

The following is a list of Attach Mod features

  1. Full Permissions System
    You are able to set Download Permissions, Upload Permissions and Extension Groups per Forum Permissions.
  2. Able to add comments to Attachments
  3. Automatic Deletion of Attachments if Posts are deleted (manual Delete, pruning, within the Moderator Control Panel or the User Attachment Control Panel).
  4. Editing of existing Attachments.
    Able to Delete/Add/Change Comment and Update Attachments while editing Posts.
  5. If the local path for Attachments is changed in admin, all previous posted attachments will be displayed correctly.
  6. Category support (Special behaviour instead of just presenting a link to the attached file)
    1. Special behaviour on Images:
      Thumbnail Support
      Image Link Presentation depending on Dimensions
      Inline Images
    2. Stream Files directly within Posts. Supported Types:
      aif, aifc, aiff, asf, asx, au, avi, ivf, m3u, mid, midi, mlv, mp2, mp3, mp2v, mpa, mpe, mpeg, mpg, mpv2, rmi, snd, wav, wax, wm, wma, wmx, wmv, wvx
    3. Play Flash Files within Posts (Also supports compressed Flash MX Files).
  7. An image for displaying in front of Attachments and Threads containing Attachments (definable).
    Able to define an Image for Forum View and for every Extension Group.
  8. Maximum Upload Size definable.
    Maximum Upload Size per Extension Group definable.
  9. Multiple attachments in one post.
    Maximum number of attachments per post definable.
  10. Multiple attachments in one PM.
    Maximum number of attachments per PM definable.
  11. Attachment Quotas:
    1. Overall Attachment Quota
    2. User Attachment Quotas
    3. Group Attachment Quotas
    4. Quotas are definable for PM Boxes and Upload
  12. Download counter.
  13. Download Method selectable for every Extension Group.
    This is very useful for Data types needing a 'real' link, for example real media files.
  14. Three Upload Methods:
    1. Upload
    2. FTP Upload
    3. FTP Remote Upload
  15. Able to display Attachments in Preview Window.
  16. Able to display Attachments in Review Window.
  17. User Attachment Control Panel.
  18. Attachment Limit Box within Private Message Box.
  19. Attachment Upload Stats in Users Profile.
  20. Special Admin Modules:
    1. Manage Forbidden Extensions
    2. Manage allowed Extensions (Delete, Add, Assign new group)
    3. Manage Extension Groups
    4. Manage Special Categories
    5. Synchronize Attachments
    6. Delete Shadow Attachments (those Attachments not deleted with posts, for whatever reason)
    7. A complete Attachment Control Panel (with an integrated search feature)
    8. Much more! To sum it up, a fully customizable Attachment Feature for your Board.
  21. Language Packs:
    For up-to-date Language Packs and more information please visit http://www.opentools.de/attach_mod/ or the Language Pack Forum at http://www.opentools.de/board (if someone is willing to translate the Attachment Mod to other Languages, please contact me at Opentools.de)
  22. Database-support: mysql, mysql4, mssql, mssql-odbc, postgresql

3. What do you need in order to run certain features

You need the following to use the FTP Upload Feature (Remote and Normal):

  1. FTP Extensions built into the PHP Installation.

You need the following to create Thumbnails:

  1. ImageMagick installed on the Server (you are not able to install this if do not have root administrative access to your server).

OR

  1. GD Extensions built into the PHP Installation.

It is highly recommended to use ImageMagick if it is installed on the server.
If the exec() function is not allowed to be called within your PHP Installation, you are unable to use ImageMagick to create thumbnails.

4. Admin Rights or 'Why do you need a User Account' ?

With the Attachment Mod the Administrator has special rights when it comes to attaching Files.

The following Restrictions are not taken into account for Admins:

  1. Able to exceed the allowed Filesize.
  2. Able to attach all allowed and activated Extensions.
  3. Able to exceed the maximum Number of Attachments per Post/PM.
  4. Able to attach and download files in all forums.
  5. Default Quota for Admins is set to the complete Attachment Filesize Quota.

If you are testing the Attachment Mod and want to be sure that all Restrictions you have set are actually working, please create a normal User Account for testing.

5. The Attachment Administration Panels

5.1 Control Panel

The Control Panel is intended for the Administrator to manage the attached Files, to see some Statistics and search for Attachments.

There are four possible Modes that you are able to view at the control panel: Statistics, Search Attachments, Attachments by an particular User and All Attachments.

  1. Statistics
View:   
Statistic Value
Number of Attachments: 21
Total Filesize: 1.89 MB
Attachment Quota: 50 MB
Number of Posts with Attachments: 13
Total Number of Attachments in Private Messages: 2
Number of Topics with Attachments: 11
Independent Users Posted Attachments: 3

As you can see, the Statistics gives you a short overview of all posted Attachments.

  1. Search Attachments
View:   
Search Attachments
Filename:
Use * as a wildcard for partial matches
File Comment:
Use * as a wildcard for partial matches
Search for Author:
Use * as a wildcard for partial matches
Attachment size smaller than (bytes):
Attachment size greater than (bytes):
Download count is smaller than:
Download count is greater than:
More than this many days old:
Search Options
Forum:
Select sort method: 
Order: 

Very self explanatory, isn't it?

  1. View Attachments by Username

The first thing to do is to view the Username based Statistics

View:   Select sort method:   Order   
# Username Attachments Size (KB)
 1  testuser  11   553.68 
 2  Acyd Burn  10   1376.83 
 3  Anonymous  1   2.29 
 

Now I want to see which Attachments the User 'testuser' has attached, therefore I click on the Username.

View:   Select sort method:   Order   
# Filename File Comment Extension Size (KB) Downloads Post Time Posted in Topic Delete
 1  acyd_ava.gif gif 3.1 17 Nov 2002 08:55 pm fsgjiosd
 2  acyd_ava.gif gif 3.1 17 Nov 2002 09:01 pm zrezerw
 3  linux10.jpg jpg 48.04 17 Nov 2002 08:56 pm fsgjiosd
 4  linux13.jpg jpg 108.27 17 Nov 2002 08:56 pm fsgjiosd
 5  linux13.jpg jpg 108.27 17 Nov 2002 09:01 pm zrezerw
 6  linux_chick1.jpg jpg 53.29 17 Nov 2002 09:01 pm zrezerw
 7  linux_chick1.jpg jpg 53.29 17 Nov 2002 08:59 pm sdgsdag
 8  acyd.jpg jpg 43.52 17 Nov 2002 08:59 pm sdgsdag
 9  takeittux.jpg jpg 21.46 17 Nov 2002 08:59 pm sdgsdag
 10  linux13.jpg jpg 108.27 17 Nov 2002 09:02 pm Private Message
 11  acyd_ava.gif gif 3.1 17 Dec 2002 08:56 pm Private Message
  
Mark all :: Unmark all

Here you are able to change the Download Counts and Comments manually. You are also able to view each Attachment, delete them or go directly to the Topic where it is posted at.

  1. View All Attachments

This Panel looks like the Username based Attachments Panel and the one you see after you have searched for an Attachment. The only difference is that you see all Attachments, not only the ones you have searched for or the ones one User has attached.

5.2 Management

This Section describes the Administration Panel->Attachments->Management Screen.

We will go through every configuration option and explain what it means and how it will affect the board.

Upload Directory
Enter the relative path from your phpBB2 installation to the Attachments upload directory. For example, enter 'uploads/attachments' if your phpBB2 Installation is located at http://www.yourdomain.com/phpBB2 and the Attachment Upload Directory is located at http://www.yourdomain.com/phpBB2/uploads/attachments.

Ok, this Option is for defining your Upload Directory, where your uploaded Files will be placed into.

If you use (or want to use) FTP Upload this setting is not needed, the Attachment Mod will use the FTP Settings instead. Please only let the Attachment Mod place files into this Upload Directory, do not upload files for your own into this directory. If you do so, they will be overwritten and the Shadow Attachments Screen will be confused.

Examples:

Your Website URL for uploaded files: http://www.yoursite.com/phpBB2/uploads/attachments
Upload Directory: uploads/attachments

Your Website URL for uploaded files: http://www.yoursite.com/uploads
Your Website URL to your phpBB2 Board: http://www.yoursite.com/phpBB2
Upload Directory: ./../uploads

You see, the Upload Directory is always relative to your phpBB2 Directory. Of course you are able to set absolute paths too, but you have to know the 'complete' directory (and not URL) then.



Attachment Posting Icon
This Image is displayed next to Attachment Links in individual Postings. Leave this field empty if you don't want an icon to be displayed. This Setting will be overwritten by the Settings in Extension Groups Management.

The Attachment Posting Icon is a little Image displayed beside links to Attachments within Posts and Private Messages.
This setting defines the default Image, if you define Posting Icons for Extension Groups, this default Setting will not be used, only for those Extension Groups with an undefined Icon. The Path is relative to your phpBB2 Directory.



Attachment Topic Icon
This Image is displayed before topics with Attachments. Leave this field empty if you don't want an icon to be displayed.

The Attachment Topic Icon is for defining a little Image displayed in front of topics containing Attachments. It is not only for displaying within viewforum, it will be displayed within the Moderation Control Panel and the Private Message Box too.



Attachment Display Order
Here you can choose whether to display the Attachments in Posts/PMs in Descending Filetime Order (Newest Attachment First) or Ascending Filetime Order (Oldest Attachment First).
Descending
Ascending

This Setting is for defining the Ordering of Attachments within Posts and Private Messages. This affects only those Posts and Private Messages with more than one Attachment. For ordering, the Time the Attachment got uploaded is used and not the time the Post was made.



Filesize
Maximum filesize for Attachments. A value of 0 means 'unlimited'. This Setting is restricted by your Server Configuration. For example, if your php Configuration only allows a maximum of 2 MB uploads, this cannot be overwritten by the Mod.

This Setting defines the Maximum Filesize for one Attachment. This Setting is restricted by your PHP Configuration.
If your provider does not allow file uploads or set them to 0 byte, or restricted it to 2 MB for example, the Mod is unable to overwrite this value.
If your provider has set the maximum upload size to 2 MB and you define a filesize of 5 MB, you are only able to upload a maximum filesize of 2 MB.



Attachment Quota
Maximum Disk Space ALL Attachments can hold on your Webspace. A value of 0 means 'unlimited'.

This is your highest Attachment Quota Setting, even the Administrator is not allowed to exceed this Limit.
This Setting is to prevent too many uploads; most providers are setting limitations to usable disk space.



Maximum Filesize in Private Messages Folder
Maximum Disk Space Attachments can use up in each User's Private Message box. A value of 0 means 'unlimited'.

This setting is a default Quota Limit for every users' Private Message Box. Users without a quota setting are limited to this Filesize within their Private Message Box.
This setting determines the total space taken by all Attachments within the users' Private Message Box, not the size of each file.



Default Quota Limit
Here you are able to select the Default Quota Limit automatically assigned to newly registered Users and Users without an defined Quota Limit. The Option 'No Quota Limit' is for not using any Attachment Quotas, instead using the default Settings you have defined within this Management Panel.
 Upload Quota 
 PM Quota 

This Setting defines your Default Quota Limits. The Upload Quota is for limiting the User on Attachments posted in Messages, and the PM Quota on Attachments within users Private Message Box. Since within this example a PM Quota of 'No Quota Limit' is set, the 'Maximum Filesize in Private Messages Folder' Setting will be used.
If the Upload Quota is set to 'No Quota Limit' the 'Attachment Quota' Setting will be used. Please keep in mind, even if you set a Upload Quota Limit higher than the Attachment Quota, this Limit will fall back to the defined Attachment Quota, because this is your highest definable Value.



Maximum Number of Attachments
The maximum number of attachments allowed in one post.

This Setting is for defining the maximum Number of Attachments allowed to be uploaded to one Post.



Maximum number of Attachments in one Private Message
Define the maximum number of attachments the user is allowed to include in a private message.

This Setting is for defining the maximum Number of Attachments allowed to be uploaded to one Private Message.



Disable Attachment Mod
This option is mainly for testing new templates or themes, it disables all Attachment Functions except the Admin Panel.
Yes   No

This Option is for disabling the Attachment Mod.



Allow Attachments in Private Messages
Allow/Disallow attaching files to Private Messages.
Yes   No

This Option is for allowing or disallowing Users to be able to attach Files to Private Messages.



Do you want to display Attachments in the Topic Review Window ?
If you choose yes, all attached Files will be displayed in Topic Review when you post a reply.
Yes   No

This Option let you choose whether you want to show previously posted Attachments within the Topic Review Window while Replying to Threads or not. Please keep in mind allowing this Option will add additional Load to your Posting Page.



Show new Attachment Posting Control Panel
Choose whether to display the Attachment Posting Control Panel (yes) or the old method with two Boxes for Attaching Files and editing your posted Attachments (no) within your Posting Screen. The look of it is very hard to explain, therefore it's best to try it out.
Yes   No

This Option will enable or disable the Attachment Posting Control Panel.

If set to yes, your Attachment Box will look like this:

Attachment Posting Control Panel
If you click on Add an Attachment, you will see the box for adding Attachments.
If you click on Posted Attachments, you will see a list of already attached Files and you are able to edit them.
If you want to Replace (Upload new Version) an Attachment, you have to click both links. Add the Attachment as you normally would do, thereafter don't click on Add Attachment, rather click on Upload New Version at the Attachment Entry you intend to update.
Options  

If set to no, your Attachment Box will look like this:

Add an Attachment
If you do not want to add an Attachment to your Post, please leave the Fields blank
Allowed Extensions and Sizes
Filename
File Comment
Posted Attachments
Filename acydamp.zip
File Comment
Options    



You are not able to use the FTP Upload Methods, because FTP Extensions are not compiled into your PHP Installation.

If you see this Note, you are unable to use the FTP Upload Methods.



Enable FTP Upload
Enable/Disable the FTP Upload option. If you set it to yes, you have to define the Attachment FTP Settings and the Upload Directory is no longer used.
Yes   No

This Option is for enabling FTP and FTP Remote Upload.



FTP Upload Server
Here you can enter the IP-Address or FTP-Hostname of the Server used for your uploaded files. If you leave this field empty, the Server on which your phpBB2 Board is installed will be used. Please note that it is not allowed to add ftp:// or something else to the address, just plain ftp.foo.com or, which is a lot faster, the plain IP Address.

This is for defining your FTP Upload Server. If you want to define a remote Server for uploading your Files through FTP, enter the IP Address of this Server. If you want to use the same Server your phpBB2 Board is installed, leave this field empty.
The default Port 21 is used for FTP Uploads.



FTP Path to your upload directory
The Directory where your Attachments will be stored. This Directory doesn't have to be chmodded. Please don't enter your IP or FTP-Address here, this input field is only for the FTP Path.
For example: /home/web/uploads

This Setting is for defining the FTP Upload Path, this seems to be the trickiest setting for users, since this path does not depend on your phpBB2 Path.
This Setting depends on your FTP Entry Point when connecting to your FTP Server. If you set a relative Path here, please keep this in mind.

Now some examples for better understanding:

If you connect to your FTP Server, the lowest path where you are is: public_html
Your phpBB2 Board is at: public_html/phpBB2
Your Upload Directory is at: public_html/uploads
Your complete home path at this Server is: /home/web/users/v92387 (most users do not know this path, they have to look up their Provider Information to find this one out)

A relative Path to your Upload Directory would be: public_html/uploads
An absolute Path to your Upload Directory would be: /home/web/users/v92387/public_html/uploads



Download Link to FTP Path
Enter the URL to your FTP Path, where your Attachments are stored.
If you are using a Remote FTP Server, please enter the complete url, for example http://www.mystorage.com/phpBB2/upload.
If you are using your Local Host to store your Files, you are able to enter the url path relative to your phpBB2 Directory, for example 'upload'.
A trailing slash will be removed. Leave this field empty, if the FTP Path is not accessible from the Internet. With this field empty you are unable to use the physical download method.

This Setting is relevant for downloading Attachments.
If you are not using a Remote FTP Server, you are able to enter the path relative to your phpBB2 Directory:

phpBB2 URL: http://www.mysite.com/phpBB2
Upload URL: http://www.mysite.com/phpBB2/uploads
Download Link to FTP Path: uploads

If you are using a Remote FTP Server, you have to enter a complete URL to your Upload Directory:

phpBB2 URL: http://www.mysite.com/phpBB2
Upload URL: http://www.storageplace.com/uploads
Download Link to FTP Path: http://www.storageplace.com/uploads

If you are unable to access your FTP Upload Directory directly from the web, you are able to leave this field blank.
But then you are unable to use the physical download method, but this one is used rarely. More about the download methods will be explained later.



Enable FTP Passive Mode
The PASV command requests that the remote server open a port for the data connection and return the address of that port. The remote server listens on that port and the client connects to it.
Yes   No

This is for using the FTP Passive Mode to Upload and Download Attachments, some FTP Server are configured the way to only allow Passive Mode connections.
If FTP Uploading does not work for you, try to enable/disable this Mode.



Your FTP Username

Here you have to enter the Username with which you are connecting to your FTP Server.



Your FTP Password

Here you have to enter the Password with which you are connecting to your FTP Server.



    

With the Submit button you are submitting your changes.
With the Reset button you are re-setting your changes.
With the Test Settings Button you are able to test your entered settings. For example, if you have chosen FTP Upload, the Attachment Mod is testing if all settings are correct and if the Mod is able to connect to the server and to upload a file.
With Test Settings you receive more accurate Errors on what you have missed or what is not working as in the posting Screen.


5.3 Quota Limits

Within this Panel you are able to define the Constants for your Quota Limits, you are able to add new Quota Limits, change existing ones and delete them.
The following is the default Quota Limit View

Manage Attachment Quota Limits
Description Filesize Add
Description Filesize Delete
View
View
View

At the Top you are able to add a new Quota Limit.
You can assign the listed Quota Limits to Users and Groups later. To assign a Quota Limit to a User, you have to go to Users->Management, select the User and you will see the Options at the bottom. To assign a Quota Limit to a Group, go to Groups->Management, select the Group to edit it, and you will see the Configuration Settings. If you want to see, which Users and Groups are assigned to a specific Quota Limit, click on 'View' at the left of the Quota Description.
Now let's have a look at the 'View' of the 'Medium' Limit

Medium

Assigned Users - Upload Quota
   
Assigned Groups - Upload Quota
   
Assigned Users - PM Quota
   
Assigned Groups - PM Quota

This View is only for informing you about the Groups and Users assigned to the Quota Limit.
To change this for Users and Groups, you have to go the the Groups Management Screen or the Users Management Screen.

More about Quota Limits and how they work is explained in four additional Sections:
The Quota System
How to set up Default quotas
How to set up User and Group quotas
How Quota Limit Changes will affect User and Group Quotas


5.4 Shadow Attachments

Within the Shadow Attachments Screen you can delete Attachments from Posts or Private Messages.
You are also able to delete Files no longer assigned to any Post or Private Message.

It is recommended to handle this Screen very carefully, view the Attachments before you delete them (if a link to the Attachment is provided). After you have deleted Attachments, Synchronize them (see next Section).


5.5 Synchronize Attachments

With this Link you are able to Synchronize your Attachments. The Attachment Mod goes to all topics and posts verifying if the Attachment Data is correct, since every topic and every Post with Attachments is marked, this mark has to be deleted if no Attachment exists. Normally this is dnne automatically, therefore it is advised to run this Sync only if you have problems viewing Attachments.

Next, Synchronization will detect if the Thumbnail Data on Attachments is correct, if no Thumbnail exists on Attachment (marked as having a Thumbnail) this Attachment will be reset and the Thumbnail Data deleted.

Here is a typical Output of this Synchronize (I have manually deleted Thumbnails to show you the Reset Information):

Sync Topics
.......................

Sync Thumbnails
.......


Attachment Syncronization Finished.

Thumbnail resetted for Attachment: acyd.jpg
Thumbnail resetted for Attachment: takeittux.JPG
Thumbnail resetted for Attachment: linux_chick1.jpg
Thumbnail resetted for Attachment: linux13_177.jpg
Thumbnail resetted for Attachment: linux_chick1_145.jpg
Thumbnail resetted for Attachment: linux13_131.jpg


6. The Extensions Administration Panels

6.1 Extension Control

Within this Panel, you are able to add and delete Extensions. Every Extension is assigned to an Extension Group, whether this Group is enabled or not. There is a special Extension Group for pending Extensions, it is called 'Not Assigned'. If a Extension Group gets deleted, the Extensions assigned to this Group are automatically unassigned, meaning they are pending status. These Extensions are of course not allowed to be attached to your Board.
You are able to enter an Explanation for your Extensions, the Explanation is only viewable to you within this Panel and is intended for you to better identify it.

The following is an example of this Panel, click a few DropDown-Boxes to see which Extension Groups I have set up on my test board.

Manage Extensions
 Explanation   Extension   Extension Group   Add 
 Explanation   Extension   Extension Group   Delete 
gif
png
jpeg
jpg
gtar
gz
tar
zip
rar
ace
txt
c
h
cpp
hpp
diz
xls
doc
dot
pdf
ai
ps
ppt
rm
wma
mp3
avi
wmv
swf
tif
tga

If you want to add an Extension, you have to click the little checkbox before you click the Add Extension Button, this is to prevent Users accidentally submitting changes they do not want.
To delete Extensions, just click the Checkbox beside an existing Extension.
To change the Extension Group of an Extension, just select it with the DropDown Box.
After you have made all changes you can click Submit to enter them into the Database.


6.2 Extension Groups Control

Ok, this Panel is for defining almost everything handling with Extensions. Since every Extension has to be in one Extension Group, the Extension Groups are the main Configuration Point you can set up.
Let us have a look at a Standard Panel for Extension Groups

Manage Extension Groups
 Extension Group   Special Category   Allowed   Download Mode   Upload Icon   Maximum Filesize   Allowed Forums   Add 
 
 
 Extension Group   Special Category   Allowed   Download Mode   Upload Icon   Maximum Filesize   Allowed Forums   Delete 
+
Group Permissions
+
Group Permissions
+
Group Permissions
+
Group Permissions
+
Group Permissions
+
Group Permissions
+
Group Permissions
+
Group Permissions

As you can see, there are a bunch of Options/Settings you are able to change. We are going through all of them step by step.
First, I will explain the Options you are able to choose from.
  • Special Category
You are able to assign a Special Category to Extension Groups, the same Special Category is allowed to be assigned to more than one Extension Group.
At the moment there are four Special Categories: none, Images, Stream Files and Flash Files.

You are able to define the Settings taking effect for the Special Category Images within the Special Categories Admin Panel (see Section 6.4 (Special Categories) for details).

Extensions (posted Files with the Extension) within Extension Groups assigned to the Special Category 'Stream Files' are automatically played within the Post/PM. The supported Types for streaming files highly depends on the User's Windows Media Player Plugin. These Extensions have been reported to be working:
aif, aifc, aiff, asf, asx, au, avi, ivf, m3u, mid, midi, mlv, mp2, mp3, mp2v, mpa, mpe, mpeg, mpg, mpv2, rmi, snd, wav, wax, wm, wma, wmx, wmv and wxv

Extensions (posted Files with the Extension) within Extension Groups assigned to the Special Category 'Flash Files' are automatically played within the Post/PM. Of course this Special Category is intended for Flash Files. ;)

The Setting 'none' is not a Special Category. If 'none' is selected the Attachment Mod displays a simple Download Link to the File, this is the normal way the Attachment Mod handles Files.

  • Allowed or not Allowed
There is a little Checkbox for letting you allow an Extension Group. Only if Extension Groups are allowed, the Users (and you) are able to attach Files with the Extension defined within the allowed Extension Group.

  • Download Mode
There are two possible Download Methods you are able to use: physical and logical.

The physical method:
This will point the attachment link to the original File. If you (or a user) click on an Attachment which Extension Group is set to physical download method, the browser will point directly to this file. Of course the download.php file is called to check Permissions and other things, but the delivery method consist of a simple Location Header (or Refresh if the Server does not Support this Header).
The downside of this method is that Users sometimes receive cryptic Filenames (with random Numbers at the end) and your Upload Directory has to be accessible from the Internet.
Therefore, this method should only be used for Extensions that need the File in complete. I only know of one: Real Media Files. Additionally, try this Download Method if you think your downloaded Files got garbled.

The logical method:
The Logical Download Method is the standard Method to use. It's for pointing the User to the correct Attachment and presenting them the correct Name for the Attachment, even if it's saved differently at your webspace. Even if the Upload Directory is not accessible from the Internet, the File gets downloaded correctly.

  • Upload Icon
This Setting is the same as within the Management Screen (Setting Name: 'Attachment Posting Icon'). You are able to define those Attachment Posting Icons individually for every Extension Group.
If an Upload Icon is empty, the one from the Management Panel will be used.

  • Maximum Filesize
You are able to define the Maximum allowed filesize for Attachments within Extension Groups, this is definable for every Extension Group.
If you change the Maximum allowed filesize within the Management Panel and you haven't changed the Filesizes for Extension Groups, the Extension Groups are getting updated to reflect this new Filesize.

  • Add an Extension Group
Manage Extension Groups
 Extension Group   Special Category   Allowed   Download Mode   Upload Icon   Maximum Filesize   Allowed Forums   Add 
 
 

To add an Extension Group, you have to enter a Name for the Extension Group and click the Add Checkbox. After you have clicked on Submit the Extension Group will be added. You are also able to define the additional Settings too, of course.
Newly added Extension Groups are empty by default, you have to assign Extensions to Extension Groups with the Extension Control Panel.

  • Viewing Extensions
You can have a look at the Extensions assigned to an particular Extension Group by clicking at the plus sign

 Extension Group   Special Category   Allowed   Download Mode   Upload Icon   Maximum Filesize   Allowed Forums   Delete 
-
Group Permissions
gif            
png            
jpeg            
jpg            



6.2.1 Extension Groups Forum Permissions

If you click the Group Permissions Link, you are able to choose the Forums where the User is able to Post Attachments with Extensions defined within the Extension Group.
For example, if I click on the Permissions Link for the Extension Group 'My Images'

Allowed Forums
 
 
Add Forums
   

The following is the Introduction Text for Group Permissions:
Here you are able to restrict the selected Extension Group to Forums of your choice (defined in the Allowed Forums Box). The Default is to allow Extension Groups to all Forums the User is able to Attach Files into (the normal way the Attachment Mod has since the beginning). Just add those Forums you want the Extension Group (the Extensions within this Group) to be allowed there, the default ALL FORUMS will disappear when you add Forums to the List. You are able to re-add ALL FORUMS at any given Time. If you add a Forum to your Board and the Permission is set to ALL FORUMS nothing will change. But if you have changed and restricted the access to certain Forums, you have to check back here to add your newly created Forum. It is easy to do this automatically, but this will force you to edit a bunch of Files, therefore I have chosen to keep it the way it is now. Keep in mind that all of your Forums will be listed here.


6.3 Forbidden Extensions

Within this Panel you are able to define Extensions forbidden to be attached.
There are three default Extensions you are not able to delete, because they will open a huge security leak into your Board.
Also, the Extensions defined here are unable to be added to the allowed Extensions, and Administrators are not able to attach them too. Within this Panel only the high security risk Extensions should be added, because the Mod is configured to only allow enabled Extensions to be attached there is no need to define all Extensions you want to not be attached here.


6.4 Special Categories

Within this Panel you are able to define Parameters and Settings for Extension Groups within Special Categories. At the moment only the Special Category Images are configurable here.
The Header is showing you to which Extension Group/Groups this changes will have effects on

Settings for Special Category: Images
Assigned Group: My Images

The Special Category is called 'Images' and the assigned Extension Group is 'My Images'.
Now to the settings you are able to make to the Special Category Images:



Display Images Inlined
Choose whether to display images directly within the post (yes) or to display images as a link ?
Yes   No

If this is set to yes, the posted Extensions within the Extension Group 'My Images' will be displayed as an image:

acyd_ava.gif
 Description:
This is my Avatar Image
 Filesize:  3.1 KB
 Viewed:  10 Time(s)

-> The Image will be displayed here <-



The Inline display can be restricted by the Image Link Dimensions (will be explained here too).



Create Thumbnail
Always create a Thumbnail. This feature overrides nearly all Settings within this Special Category, except of the Maximum Image Dimensions. With this Feature a Thumbnail will be displayed within the post, the User can click it to open the real Image.
Please Note that this feature requires Imagick to be installed, if it's not installed or if Safe-Mode is enabled the GD-Extension of PHP will be used. If the Image-Type is not supported by PHP, this Feature will be not used.
Yes   No

This Setting is for enabling the Creation of Thumbnails. The only Setting affecting this Option is the Image Link Dimensions Setting.
This Setting could be hidden from you if the Attachment Mod detect that you are unable to create Thumbnails.
Please refer to Section 7.6 on how to get Thumbnails working.



Minimum Thumbnail Filesize
If a Image is smaller than this defined Filesize, no Thumbnail will be created, because it's small enough.
Bytes

Somewhat self-explaining, but I want to add a little note here. If your server-config is broken or the filesize() function is not allowed, the Attachment Mod will identify all Attachments as having a filesize of 0 Bytes, meaning that a Thumbnail will never be created.
This Setting could be hidden from you if the Attachment Mod detect that you are unable to create Thumbnails.



Imagick Program (Complete Path)
Enter the Path to the convert program of imagick, normally /usr/bin/convert (on windows: c:/imagemagick/convert.exe).

Make sure the path to imagemagick does not contain Spaces. (for example 'program files' <- there is a space within the directory name, this will not work)
You are able to search for this Program with the Search Imagick Button.



Maximum Image Dimensions
Here you can define the maximum allowed Image Dimension to be attached (Width x Height in pixels).
If it is set to 0x0, this feature is disabled. With some Images this Feature will not work due to limitations in PHP.
x

This Setting is for defining the Maximum allowed Image Dimensions to be posted. This is to prevent you from screwing up your Board with too high Resolution Images or because you simply do not want to let Images greater than 1024x768 to be posted (for example).



Image Link Dimensions
If this defined Dimension of an Image is reached, the Image will be displayed as a Link, rather than displaying it inlined,
if Inline View is enabled (Width x Height in pixels).
If it is set to 0x0, this feature is disabled. With some Images this Feature will not work due to limitations in PHP.
x

This is for defining the border from Inline View to displaying an Link. If the Dimension you set here is exceeded, the Image is displayed as an Link.
This Setting overrides the Inline View (of course) and the Thumbnail Creation. If you want to create Thumbnails of all Images, the best is to set this Dimension to 0x0.



      

With the Search Imagick Button you are able to Search for the ImageMagick program.
With the Test Settings you are able to test the Thumbnail Settings, it is highly recommended to do this, because this procedure creates a directory under your Upload Directory with the name 'thumbs' for placing the Thumbnails into it.
If this Directory does not exist, the Attachment Mod is unable to create Thumbnails.


7. General Administrative Settings and Features (HowTo's)

7.1 How to set up Permissions for Attaching and Downloading

Yes, you are able to set Permissions on downloading and attaching files.
The Permissions are the same as the ones you know for Reading, Voting, Create Polls...

If you set Permissions for Downloading and Attaching, please be sure to use the Advanced Mode.

A little Example:
You want to create a Usergroup allowed to attach files, you want downloading to be restricted to Registered Users only.
These Permissions are for your Forum called 'Downloads' (only an example).

The Usergroup:
Create a new Usergroup, name it for Example: attach users
Open up the Forum Permissions Control Panel, select your Forum (here: Downloads) and go to the Advanced Mode.
Set the Permission to attach Files to PRIVATE (to be able to assign it to the Usergroup) and the Permission to Download Files to REG.
Now go to the Usergroups Permissions Panel and change the Permission for the Group 'attach users' to YES at the 'Downloads'-Forum.

As you can see, the two Permissions (Attaching and Downloading) acting like the other Permissions you are able to set/configure.


7.2 The Quota System

The Quota System is defined as limiting Users/Groups to a defined maximum Storage Limit.
This Limit is not set on a per file basis, it is a general setting, counting the Filesize of all attached Files by the User/Group.
Quota Limits are definable for Uploaded Files within Posts and for uploaded Files within Private Messages. Attachments included into Private Messages in your SENT Box are not counted.
There is one Setting (within the Management Screen) for defining a maximum Attachment Quota, this defined Filesize is the largest Storage Limit you are able to set, no Quota Limit is able to exceed this defined Limit, even the Administrator is not allowed to exceed this Limit.
The Group Quota is defined as a Quota Limit to each User of the Group, not the Group in whole.

If there are multiple quotas set for one user, only one quota will be used by AttachMod:

Group Quotas have the highest Priority, if more than one Group exists for the User, the Group with the largest (in Size) Quota will be given the highest Priority.
User Quotas have the lowest priority.

Example:
User A has a quota of 30 megabytes assigned to him/her. User A is in Group Alpha and Group Beta.
Group Alpha has a quota of 20 megabytes and Group Beta has no quota.

User A will be given a quota of 20 megabytes; not 30 megabytes because Group Alpha has the largest quota of the two groups and takes priority over user quotas.

Remember, no quota may be larger than the "Attachment Quota" setup in the "Management Screen". (See Section 5.2)


7.3 How to set up Default quotas

Default Quotas will be assigned to newly registered Users and Users with no Quota Setting.

You are able to define Default Quotas within the Attachments Management Screen. A value of 'No Quota Limit' disables the Assignment of Quotas to newly registered Users, they will have no Quota Limit.
If no Quota Limit is assigned, the System Parameters are used, this means every User is able to attach Files until the complete Attachment Quota is reached.


7.4 How to set up User and Group quotas

User Quotas will be assigned to Users.

You are able to directly assign a Quota Limit to a User by using the Users Management Administration Panel.
After you have chosen the User you want to edit, have a look at the 'Special admin-only fields'. You should see two new dropdown boxes:
Upload Quota and PM Quota. You are able to define the Quota Limit for any specific User now.

Group Quotas will be assigned to Groups.

You are able to assign a Quota Limit to an existing Group. If you want to create a new Group, you will not see the Quota Settings, you have to create the Group, then you have to edit the Group in order to set the Quota Limits in the same way as the User Quota Limits.


7.5 How Quota Limit Changes will affect User and Group Quotas

If you want to change the Filesize Limit for your Medium Storage Limit from 1 MB to 2 MB, you probably won't want to go through each user and group and set each quote individually. This method was implemented for that very reason.
With the Attachment Mod you are able to define Quota Constants, setting a descriptive word for your Limit.
For example: Medium -> 1 MB
Now you assign this constant (Medium) to two Groups and ten Users.
After a week you notice that the Quota is too low and you want to change it to 2 MB.
Now you only have to change the constant from 1 MB to 2 MB, the change will be directly assigned to your two Groups and ten Users.
If a Quota Constant is deleted, all Users/Groups with this defined Setting are automatically switched back to the Default/No Quota Setting.
You are able to see which Users/Groups are assigned to which Quota Setting too.
Please have a look at Section 5.3 (Quota Limits) in order to see how your are able to set/change/delete Quota Settings and how to view the current Quota Assignments.


7.6 How to get Thumbnails working

The ability to create Thumbnails are only given to the Special Category 'Images'.
Therefore you have to assign this Category to an Extension Group first.
After you have assigned the Special Category 'Images' to one (or more) Extension Groups within the Administration Panel -> Extension Groups Management Screen you have to go to Administration Panel -> Special Categories.
Enable the Option to Create Thumbnails. Additionally, set the Image Link Dimensions to 0x0 if you don't want to present Links to your Image if they are greater than the defined size you have entered there.

The last Step is to Test the Thumbnail Settings. The Test Process will create the necessary Directory too.
You should also search for the ImageMagick program if you are unable to recall the correct path to the program.
Please make sure the path to imagemagick does not contain Spaces. (for example 'program files' <- there is a space within the directory name, this will not work)

If you do not see the Options for Thumbnails the Attachment Mod detected that you are not able to create Thumbnails, therefore it was disabled.


8. How to use the Attachment Mod

8.1 Posting and Editing Attachments - Posts and Private Messages

In general you are able to post, edit and delete Attachments within Posts and Private Messages.
I will explain the procedure for Posts, since for Private Messages it is the same.
To open your board and post a message while reading this section will help you to understand what is explained here. To see something while reading, the explanation usually becomes more helpful.

While writing a new post, you will see the Attachment Posting Control Panel, either you will see two buttons to open the Add Attachments Box and the Posted Attachments Box or you will see both boxes at the beginning, this depends on how the Administrator (you) has set the view within the Attachment Management Screen.

Within the Add Attachment Box you will see a little link to the Attachment Rules, there you are able to see a little overview of what you are able to attach and which filesize restrictions are set. Within the Add Attachment Box you are able to enter a comment for your Attachment and you are able to add a file itself by clicking the Browse Button.
After you have chosen a file you want to attach (comment field is allowed to be left blank) you are able to click the Add Attachment Button to add the file. If you directly click submit the file will still be added with the Post.

Within the Posted Attachment Box you are able to edit your file comments or delete Attachments.
After you have changed an existing comment, you have to click the Update Comment button.
You are able to delete Attachments by clicking the Delete Attachment Button on the Attachment Entry you want to delete. The Administrator is able to delete Thumbnails from Posts. After deleting a Thumbnail the normal Image is displayed.
You are able to replace a file too (practical for uploading new versions of files). Select the file you want to upload (without clicking the Add Attachment button) and click the Upload New Version Button.


8.2 Additional Viewable Areas

8.2.1 User Profiles

The user itself is able to view his Upload Status and Quota Setting within his Profile. The Administrator is able to view it too.

Here is an example of this Status Field

0% 50% 100%
[Uploaded: 550.58 KB / Quota: 2 MB / 27% of total]
User Attachment Control Panel

As you can see, the user is able to see his current uploaded filesize and the complete Filesize he is able to Upload.
The Link to the User Attachment Control Panel will open the User Attachment Control Panel.


8.2.2 User Attachment Control Panel

Within this Panel, the user is able to see all of his uploaded Files and is able to delete them.

It will look like this:
User Attachment Control Panel :: testuser
Select sort method:   Order   
# Filename File Comment Extension Size (KB) Downloads Post Time Posted in Topic Delete
 1  linux13.jpg jpg 108.27 1 Sun Nov 17, 2002 8:56 pm fsgjiosd
 2  linux13.jpg jpg 108.27 1 Sun Nov 17, 2002 9:01 pm zrezerw
 3  linux13.jpg jpg 108.27 1 Sun Nov 17, 2002 9:02 pm Private Message
 4  linux_chick1.jpg jpg 53.29 1 Sun Nov 17, 2002 8:59 pm sdgsdag
 5  linux_chick1.jpg jpg 53.29 1 Sun Nov 17, 2002 9:01 pm zrezerw
 6  linux10.jpg jpg 48.04 2 Sun Nov 17, 2002 8:56 pm fsgjiosd
 7  acyd.jpg jpg 43.52 0 Sun Nov 17, 2002 8:59 pm sdgsdag
 8  takeittux.jpg jpg 21.46 0 Sun Nov 17, 2002 8:59 pm sdgsdag
 9  acyd_ava.gif gif 3.1 14 Sun Nov 17, 2002 8:55 pm fsgjiosd
 10  acyd_ava.gif gif 3.1 10 Sun Nov 17, 2002 9:01 pm zrezerw
Mark all :: Unmark all

As you can see, the user is able to do nearly the same as the Administrator is able to do within the Attachment Control Panel.

The Administrator is able to view the Control Panel for Anonymous/Guest Users too.
You are able to do so by calling the User Attachment Control Panel directly with the Anonymous User ID
http://www.yourdomain.com/phpBB2/uacp.php?u=-1


9. Common Problems attaching Files

9.1 Filesize too big / Post Mode not specified / Blank Page

If you get Error Messages saying the Filesize is too big after submitting your post, even if you are attaching Files below 1 Kbyte.

The most common reason for this error is that your provider has enabled File Uploading on the Server, but he probably have set the Maximum Filesize to 0 Byte.
Another reason could be that you are trying to attach a File bigger than the maximum allowed upload size defined by your Provider.
The Attachment Mod is unable to overwrite this value.

If you are trying to attach very big files the execution time limit may have been exceeded.

Here is a list of all PHP Variables interfering directly or indirectly with File Uploading:

max_execution_time
memory_limit
post_max_size
file_uploads
upload_max_filesize

Please refer to the PHP Documentation on how to configure this variables.

If you get the Error Message 'no Post Mode specified' after submitting your Post or a blank page.

The most common reason for this error is that your provider does not allow File Uploads at all.
Ask your provider or create a php-file with this content:

<?
phpinfo();
?>

Upload the File to your webspace, execute it and look for the variable 'file uploads', it have to be set to 1, if not, file uploading is not allowed.

Additional Informations for both problems:
new twist on "No post mode..." problem-Thread posted at Opentools.de.


9.2 Could not attach File, but Post has been stored / Filesize is 0 all over the time

If you get the Error Message 'Could not Attach File. Post has been stored' after submitting your Post.

Either your Provider does not allow the function filesize(), which is very bad, because nothing can be done to solve the problem, or your Temporary PHP Directory is not setup properly.

(Only for people hosting their own Website)

Every Attachment uploaded to the board will go into the PHP Temporary Upload Directory.
Please check the Permissions of this Directory and make sure PHP is allowed to write to it.
For users using Apache/IIS on Windows, you might want to check the following Settings:

(Thanks to SFGrimoire :: complete thread about this error)

The IUSR_hostname account needs to have read/write access to the system temp directory, otherwise you will receive the following access failure:

Event Type: Failure Audit
Event Source: Security
Event Category: Object Access
Event ID: 560
Date: 9/16/2002
Time: 12:05:52 PM
User: W2KNCHTNPC\IUSR_W2KNCHTNPC
Computer: W2KNCHTNPC
Description:
Object Open:
    Object Server: Security
    Object Type: File
    Object Name: C:\WINNT\Temp
    New Handle ID: -
    Operation ID: {0,450981}
    Process ID: 812
    Primary User Name: W2KNCHTNPC$
    Primary Domain: AFS
    Primary Logon ID: (0x0,0x3E7)
    Client User Name: IUSR_W2KNCHTNPC
    Client Domain: W2KNCHTNPC
    Client Logon ID: (0x0,0x61349)
    Accesses SYNCHRONIZE
            ReadData (or ListDirectory)

    Privileges -


The specific permissions required are:

hostname\IUSR_hostname:(OI)(CI)(special access:)
                                DELETE
                                READ_CONTROL
                                SYNCHRONIZE
                                FILE_READ_DATA
                                FILE_WRITE_DATA
                                FILE_APPEND_DATA
                                FILE_EXECUTE

Also, if you change the upload directory in php.ini the IUSR_hostname account needs the same permissions.


9.3 General Error: Could not Attach File

This Error is a default Message if something is not setup. To test the various things and give you an appropriate Error Message is too time intensive for a post page, therefore it was placed into the Administration Panel.

Go to Adminstration Panel -> Management and click on 'Test Settings', now you should receive a more detailed Error Message, explaining what you have to do in order for the Attachment Mod to work correctly.
In most cases you have forgotten to chmod the upload directory.


9.4 I am able to attach files in Private Messages, but with normal Posts i cannot Attach files

You may have made a mistake while editing your includes/auth.php file, please re-check this file.
The line to be added has to be placed AFTER the closing brace, and not Before it.

If this was not the error, please check if you have edited and uploaded your posting_body.tpl file.


9.5 No Attachments are displayed

Since the Attachment Mod Version 2.3.5 a check was integrated to bypass the different viewtopic.php versions users are magically using.
But please check if you have added the last line between ); and } within the viewtopic.php file.
The correct result for the last line to be added to the viewtopic.php file should look like this:


      'U_POST_ID' => $postrow[$i]['post_id'])
   );
   display_post_attachments($postrow[$i]['post_id'], $postrow[$i]['post_attachment']);



10. Copyright and Disclaimer

This is the February, 2003 revision of the Attachment Mod User Guide.

This Document is Copyright © 2003 Acyd Burn, All Rights Reserved.

Contributors:
Thanks to DareDevil for fixing many grammar and spelling errors.

Please send corrections, additions and new questions to Acyd Burn.