# File Picker API

ee('treasury:FilePicker')->make()

The File Picker API lets you get a link or a URL to a file picker modal.

# make()

Takes one optional argument of the location handle you would like the File Picker to use and returns the Treasury FilePicker service. The FilePicker service has the following methods:

# setlocation()

Set the location handle for the location you would like to use (defaults to all).

# getUrl()

Gets the URL to the location modal.

# getLink()

Takes one optional argument of the text you would like to use for the <a> tag.

This method returns the Treasury FilePicker\Link service which you can use to build an HTML anchor link. The following methods are available from the FilePicker\Link service:

# setAttribute($key, $val)

Allows you to add attributes to the <a> tag.

$link = ee('treasury:FilePicker')->make('my-location')
    ->getLink('Click Me')
    ->setAttribute('class', 'my-button');

# addAttributes(array())

Allows you to add multiple attributes to the <a> tag at once.

$link = ee('treasury:FilePicker')->make('my-location')
    ->getLink('Click Me')
    ->addAttributes(array(
        'class' => 'my-button',
        'id' => 'my-id'
    ));

# setText('Click Me')

Set the text of the <a> tag.

$link = ee('treasury:FilePicker')->make('my-location')
    ->getLink()
    ->setText('Click Me');

# setHtml($html)

Set the HTML content of the <a> tag.

$link = ee('treasury:FilePicker')->make('my-location')
    ->getLink()
    ->setHtml('my html');

# render()

While the magic __toString() method will usually run the render method when needed, it may sometimes be necessary to manually run the render method to get your rendered HTML <a> tag. Here’s a full example:

$link = ee('treasury:FilePicker')->make('my-location')
    ->getLink('Click Me')
    ->setAttribute('class', 'my-button')
    ->render();

# The JavaSript Side

The button opens an EE modal and you can select a file, but you need to do something with it after it is selected. In order to do that, you need to set a callback on your button.

# $(‘.my-button-el’).TreasuryFilePicker()

Use the TreasuryFilePicker jQuery plugin to set a callback function to use for your button instance.

$('.my-button-el').TreasuryFilePicker({
    callback: function(file) {
        console.log(file);
    }
});

The first argument is an object with all the properties of the file, plus any of those properties that don’t match EE’s file object translated.

# Files API: Delete File By Path

# ee('treasury:FilesAPI')->deleteFileByPath('my-location', 'file-name.zip')

The deleteFileByPath() method takes a location handle and a filename and deletes that file.

$result = ee('treasury:FilesAPI')->deleteFileByPath('my-location', 'file-name.zip');

# Return Value

The deleteFileByPath() method returns a Treasury Validation Result Class.

# Files API: Delete Files By ID

# ee('treasury:FilesAPI')->deleteFilesById(array(2, 45))

The deleteFilesById() method takes and array of Treasury file IDs to delete.

$result = ee('treasury:FilesAPI')->deleteFilesById(array(2, 45));

# Return Value

The deleteFilesById() method returns a TreasuryValidation Result Class.

# Files API: File Exists

# ee('treasury:FilesAPI')->fileExists('my-location', 'file-name.png')

The fileExists() method takes a location handle and a filename and checks if the file exists.

$filesExists = ee('treasury:FilesAPI')->fileExists('my-location', 'file-name.zip');

# Return Value

The fileExists() method returns a boolean.

# Files API: Get Files

# ee('treasury:FilesAPI')->getFiles()

The getFiles() method acts as a factory for a Treasury Collection of Treasury Files models representing Treasury files.

$fileModelsCollection = ee('treasury:FilesAPI')->getFiles();

# Filtering

By default, the getFiles() method will get all files in the database ordered by upload date descending. But you can control what files are retrieved by filtering.

$filesAPI = ee('treasury:FilesAPI')
    ->filter('id', 'IN', array(38, 39))
    ->filter('location_id', 2)
    ->filter('site_id', 2) // defaults to current site
    ->filter('file_name', 'my-file.jpg')
    ->filter('uploaded_by_member_id', 4)
    ->filter('modified_by_member_id', 2)
    ->filter('width', '>', 200)
    ->filter('height', '<', 300)
    ->search('My Search Key Words') // Searches title, mime_type, file_name, and description
    ->limit(4)
    ->offset(8)
    ->order('modified_date', 'asc') // second arg optional. Defaults to upload_date desc
    // Order by values: upload_date|modified_date|title|file_name|mime_type

$file = $filesAPI->getFirst();
$files = $filesAPI->getFiles();
$total = $filesAPI->getCount();

# Files API: Update File

# ee('treasury:FilesAPI')->updateFile()

This method lets you update the title and description of a file.

$result = ee('treasury:FilesAPI')->updateFile(
    15, // Required. ID of the file to update
    'title', // Required. File title
    'description' // Optional. Description.
);

# Return Value

The updateFile() method returns a Treasury Validation Result Class.

# Locations API: Get All Locations

# ee('treasury:LocationsAPI')->getAllLocations()

The getAllLocations() method returns a Treasury collection of Treasury Locations models representing Treasury Locations. An argument can be passed in to control the order and sorting of locations.

$locationsCollection = ee('treasury:LocationsAPI')->getAllLocations('name:desc');

# Locations API: Get Location By Handle

# ee('treasury:LocationsAPI')->getLocationByHandle()

The getLocationByHandle() method returns a Treasury Locations model representing the Treasury Location.

$locationModel = ee('treasury:LocationsAPI')->getLocationByHandle('my-location');

# Locations API: Remove Location

# ee('treasury:LocationsAPI')->removeLocation()

Removes a location.

$locationModel = ee('treasury:LocationsAPI')->removeLocation('my-location');

# Return Value

The removeLocation() method returns a TreasuryValidation Result Class.

# Locations API: Save Location

# ee('treasury:LocationsAPI')->saveLocation()

This method allows you to save a new location or update an existing location.

The following example adds a new location.

$saveData = array(
    'name' => 'My Location',
    'handle' => 'my_location',
    'type' => 'amazon_s3',
    'settings' => array(
        'access_key_id' => 'xxx',
        'secret_access_key' => 'xxx',
        'bucket' => 'mybucket',
        'subfolder' => 'mysubfolder', // optional
        'url' => 'http://s3.amazonaws.com/mybucketname',
        'allowed_file_types' => 'images_only'
    )
);

$result = ee('treasury:LocationsAPI')->saveLocation($saveData);

To update an existing location, provide the original location handle as the second argument.

$result = ee('treasury:LocationsAPI')->saveLocation($saveData, 'my_old_location');

# Return Value

The saveLocation() method returns a TreasuryValidation Result Class.

# Locations API: Save Location

# ee('treasury:UploadAPI')->addFile()

The addFile() method will upload the provided file and add it to the Treasury file manager and database.

Before you can call the addFile method, you must set:

• locationHandle
• filePath
• fileName

You can optionally set:

• title
• description

$result = ee('treasury:UploadAPI')
    ->locationHandle('my-location')
    ->filePath('/path/to/file/on/disk.jpg')
    ->fileName('nameYouWantUploadedFileTohave.png')
    ->title('Optional Title')
    ->description('Optional Description')
    ->addFile();

# Return Value

The addFile() method returns a TreasuryValidation Result Class.

# Upload API: Upload File

# ee('treasury:UploadAPI')->uploadFile()

The uploadFile() method uploads a file to the provided location, but it is not added to the Treasury File Manager or database. You are responsible for knowing about the file and keeping track of it. Basically, Treasury is acting as a conduit to get your file to it’s selected location. You can use the Locations API to get the Locations Model and get the URL to the location for future display or retrieval of the file.

Before you can call the uploadFile method, you must set:

• locationHandle
• filePath
• fileName

$result = ee('treasury:UploadAPI')
    ->locationHandle('my-location')
    ->filePath('/path/to/file/on/disk.jpg')
    ->fileName('nameYouWantUploadedFileTohave.png')
    ->uploadFile();

# Return Value

The uploadFile() method returns a TreasuryValidation Result Class.

# Validation Result Class

The Validation Result Class is returned by Treasury whenever applicable. It has two properties:

• (bool) hasErrors
• (array) errors

Here’s an example of how Treasury uses this internally:

// Run the upload
$result = ee('treasury:UploadAPI')
    ->locationHandle($this->locationModel->handle)
    ->filePath($this->saveData['filePath'])
    ->fileName($this->saveData['fileName'])
    ->title($this->saveData['title'])
    ->description($this->saveData['description'])
    ->addFile();

// Check if validation has errors
if ($result->hasErrors) {
    // Concatenate the errors
    $errors = '<ul><li>' . implode('</li><li>', $result->errors) . '</li></ul>';

    // Set errors
    ee('CP/Alert')->makeInline('upload_errors')
        ->asIssue()
        ->canClose()
        ->withTitle(lang('upload_errors'))
        ->addToBody($errors)
        ->defer();

    // Redirect and show error
    ee()->functions->redirect(
        ee('CP/URL', "addons/settings/treasury/upload/{$this->locationId}")
    );
}