Documentation

Requirements

BucketList requires:

• PHP5, and the cURL library (most PHP5 installations include cURL by default).
• ExpressionEngine 1.6 or later.
• FieldFrame 1.4 or later.
• jQuery 1.3.2 or later (using the built-in jQuery for the Control Panel extension).

Supported Browsers

BucketList requires a reasonably competent browser in order to do its thing.

Less capable browsers may get less slightly less sexiness, but BucketList has been fully tested, and works well, in the following browsers.

Operating System	Browser	Version*
Mac OS 10.6	Camino	2.0
Mac OS 10.6	Chrome	4.0
Mac OS 10.6	Firefox	3.5
Mac OS 10.6	Firefox	3.6
Mac OS 10.6	Opera	10.10
Mac OS 10.6	Safari	4.0
Windows XP, SP3	Chrome	3.0
Windows XP, SP3	Firefox	3.0
Windows XP, SP3	Firefox	3.5
Windows XP, SP3	Firefox	3.6
Windows XP, SP3	MS Internet Explorer	7.0†
Windows XP, SP3	MS Internet Explorer	8.0
Windows XP, SP3	Safari	4.0

* Indicates the most recent version of the specified branch. For example, Firefox 3.5.7.
† There are some known display issues in IE7 on the field settings form, when using BucketList inside a Matrix field.

Installation

1. Ensure FieldFrame 1.4 or later is installed.
2. Download the latest version of BucketList, either using the Download URL in your license email, or by entering your license key on the "Download" page.
3. Extract the ZIP file.
4. Copy the system/extensions/fieldtypes/bucketlist folder to your system/extensions/fieldtypes/ directory.
5. Copy the system/language/english/ft.bucketlist.php file to your system/language/english/ directory.
6. Enable BucketList in the FieldFrame Fieldtypes Manager.

Configuration

Site-wide settings

BucketList requires your Amazon S3 Access Key ID, and your Amazon Secret Access Key in order to work.

You can also specify the cache duration, and whether you'd like to use a custom URL.

Field-specific settings

As of BucketList 1.2, member group privileges can be set for each bucket on a per-field (or per-cell, when used with Matrix) basis. Privileges are controlled by enabling or disabling three icons.

Icon	Title	Description
	Show bucket	Controls the display of the bucket. Disabling this option also disables the other bucket options.
	Allow uploads	Controls which user groups can upload files to which buckets.
	Show all files	Controls which files a member will see. By default this option is enabled, meaning that the member will see all the files in the selected bucket, and its sub-folders. If this option is disabled, the member will only see those files he has previously uploaded to the bucket and its sub-folders using BucketList version 1.2 or above.

Template Tags

BucketList provides the following template tags for outputting information within the exp:weblog:entries tag.

The following examples assume that the short name of your BucketList field is myfile.

Default tag

By default, BucketList will return the URL of the chosen file.

{myfile}

:file_extension tag

Returns the extension of the chosen file.

{myfile:file_extension}

:file_name tag

Returns the name of the chosen file.

{myfile:file_name}

:file_size tag

Returns the size of the chosen file.

{myfile:file_size}

By default, BucketList intelligently formats the return value, based on the size of the file.

If the file is smaller than 1MB, the return value is formatted using KB, otherwise MB are used.

If the format parameter (see below) is not specified, BucketList appends the appropriate suffix to the return value ("KB", or "MB").

format tag parameter

Overrides the default :file_size formatting rules, using one of the following three values:

• bytes
• kilobytes
• megabytes

When the format parameter is specified, BucketList does not include the file size suffix.

Extension Hooks

BucketList 1.2 introduces a new extension hook: bucketlist_remote_upload_start.

The hook enables third-party extensions to process an uploaded file, prior to it being forwarded to Amazon. An extension may even create entirely new files (for example, a thumbnail of an uploaded image), and pass them back to BucketList for uploading.

Hook parameters

Your method should accept two parameters: $uploads, and $member_id.

$uploads is an array containing information about the uploaded file, and the target destination, structured as follows:

array(
	array(
		'bucket'	=> 'my_lovely_bucket',
		'path'		=> 'path/to/file',
		'file'		=> array(
			'name'		=> 'my_file.txt',
			'type'		=> 'text/plain',
			'tmp_name'	=> '/tmp/php/12345',	// The temporary location of the uploaded file. Server-specific.
			'error'		=> UPLOAD_ERR_OK,
			'size'		=> 123			// The file size, in bytes.
		)
	)
)

$member_id is a string containing the ID of the member who uploaded the file.

Hook return data

Your method must return an array containing 1 or more elements. Each element must be in the following format:

array(
	'bucket'	=> 'my_lovely_bucket',
	'path'		=> 'path/to/file',
	'file'		=> array(
		'name'		=> 'my_file.txt',
		'type'		=> 'text/plain',
		'tmp_name'	=> '/tmp/php/12345',
		'error'		=> UPLOAD_ERR_OK,
		'size'		=> 123
	)
)

Stand-Alone Entry Forms

Simply follow the standard instructions for using FieldFrame in a SAEF.

BucketList requires that you import jQuery, using the instructions on the aforelinked page.

Changelog

1.2.2 (released 15th June, 2010)

• Fixed upload issue affecting buckets containing uppercase characters. According to Amazon’s documentation, bucket names cannot contain uppercase characters; apparently some clever souls have managed to circumvent this constraint.

1.2.1 (released 26th May, 2010)

• Fixed bug which could cause uploads to fail in newly-created Matrix fields.

1.2.0 (released 19th May, 2010)

• Implemented member group specific field and cell settings.
• Implemented “restrict to own uploads” functionality.
• Implemented automatic selection of files after upload (where no current selection exists).
• Implemented bucketlist_remote_upload_start hook.
• Implemented :file_extension template tag.
• Implemented support for Matrix 2.
• Fixed “DB Engine” engine bug affecting MySQL 4 installations.
• Fixed minor CSS bug affecting .tiff files.

1.1.4 (released 25th March, 2010)

• Fixed somewhat obscure bug affecting empty buckets that had previously contained items.

1.1.3 (released 8th March, 2010)

• Fixed installation bug affected databases using the MyISAM engine.

1.1.2 (released 7th March, 2010)

• Finally fixed horribly intractable bug which would very rarely result in duplicated bucket items.
• Fixed JavaScript closure bug introduced in version 1.0.3, with the cunning application of a JavaScript closure.

1.1.1 (released 3rd March, 2010)

• Fixed display bug in field settings code.

1.1.0 (released 3rd March, 2010)

• Implemented the option to specify which buckets are available for each field or FF Matrix cell.
• Implemented “maximum height” for BucketList fields.

1.0.3 (released 26th February, 2010)

• Fixed problems with jQuery.noConflict.
• Fixed scope issue caused by use of jQuery ‘live’ event listeners.
• Added conditional to prevent accidentally overwriting data from other add-ons also using the ‘sl’ cache namespace.
• Added classes for a few additional file types.

1.0.2 (released 26th January, 2010)

• Fixed bug affecting Multiple Site Manager installations.
• Changed AJAX requests to use POST instead of GET.
• Implemented hidden “demo” mode (sshhh).

1.0.1 (released 19th January, 2010)

• Fixed a bug whereby opening extremely populous buckets, containing in excess of 14,000 items, could cause a max_allowed_packet MySQL error.
• Changed default value for “Use Custom URLs” to “No.”
• Implemented alphabetical ordering of buckets.
• Added BucketList folder in root of ZIP file. Unzipping straight to the system folder was causing occasional confusion.

1.0.0 (released 6th January, 2010)

• Initial public release.

On this page

• Requirements
• Supported Browsers
• Installation
• Configuration
• Template Tags
• Extension Hooks
• Stand-Alone Entry Forms
• Changelog