ExpressionEngine® 3 User Guide

Legacy Documentation

You are using the documentation for version 3.5.17. Go here for the latest version or check here for your available upgrades to the latest version.

File Field Class

Calling the File Field Class

class File_field

ExpressionEngine uses the File Field class whenever a file field and file browser is needed. To use the file browser in your add-on, you’ll need to load the File Field library:


Creating a File Field

File_field::field($field_name[, $data = ''[, $allowed_file_dirs = 'all'[, $content_type = 'all']]])

Before you can use the file browser, you need a field that the file browser knows how to work with. To create that field, you’ll use the field method:

ee()->file_field->field($field_name, $data = '', $allowed_file_dirs = 'all', $content_type = 'all')
  • $field_name (string) – the name of the field being created
  • $data (string) – the data that already exists for this field
  • $allowed_file_dirs (string) – 'all' for all directories, or the ID of a particular directory
  • $content_types (string) – 'all' for all content types, or 'image' for images only

the HTML representation of the field

Return type:


Initializing a File Browser

File_field::browser($config = array()[, $endpoint_url = 'C=content_publish&M=filemanager_actions'])

What you need to do is initialize the file browser by optionally passing it two parameters:

ee()->file_field->browser($config, $endpoint_url);
  • $config (array) – Associative array containing configuration options (see below)
  • $endpoint_url (string) – the URL the file browser will hit

The $config parameter is technically optional, but if you don’t pass it, the library will assume you’re on the Publish page and working with standard file fields and textareas. The $config parameter is an associative array that can handle five different key- value pairs:

  • publish (optional): If set to TRUE, it will setup the file browsers as if you were on the publish page. If no $config parameter exists, this will be assumed. If this is set, all other key-value pairs are ignored.

  • trigger: The selector representing the choose file button that will be passed to jQuery to establish an event handler.

  • field_name (optional): The input field’s name that you want the results to go to. If undefined, it will assume the name is userfile

  • settings (optional): JSON object defining the content type and directory ID:

    {"content_type": "all/image", "directory": "all/<directory_id>"}
  • callback: Javascript function that will be called when an image is selected. There are two parameters available to the callback: file is an object of the selected file’s data, and field is a jQuery object representing the field from the field_name given:

    function (file, field) {
        console.log(file, field);
You will need to add CSS and JavaScript to achieve a fully functioning file browser.

Validating the data from the File Field

File_field::validate($data, $field_name[, $required = 'n'])

When using the File Field library’s field() method to generate the file field for you, it creates two fields: one that facilitates uploading using the file browser, and one that works when Javascript is disabled. If Javascript is disabled, it will then upload the file. Either way, the validate() method will return the name of the file in an array:

ee()->file_field->validate($data, $field_name, $required = 'n');
  • $data (string) – the data to validate
  • $field_name (string) – the name of the field being validated
  • $required (string) – 'n' if the field isn’t required, 'y' if it is

Associative array with a 'value' key with a value that’s uploaded file’s name

Return type:


Formatting the data

File_field::format_data($file_name[, $directory_id = 0])

After you’ve validated the data, you now have to format the data for use in templates:

ee()->file_field->format_data($file_name, $directory_id = 0);
  • $file_name (string) – the file name
  • $directory_id (integer) – the directory id where the file is located

the formatted field data (e.g. {filedir_1}filename.ext)

Return type:


Parsing the Formatted Data


This method is of more use to ExpressionEngine than anyone else, but it’s here if you need it. When you have template content that has {filedir_n}’s all over the place, you need to parse them, so the {filedir_n} tag is replaced with the actual URL:

  • $data (string) – the template to parse

the template with {filedir_n} parsed out

Return type:


Parsing {filedir_n} Variables

File_field::parse_string($data[, $parse_encoded = FALSE])

This method parses all {filedir_n} variables within a given string ($data) and can optionally look for already encoded {filedir_n} tags (e.g. &#123;filedir_n&#125;):

  • $data (string) – The string to parse {filedir_n} in
  • $parse_encoded (bool) – Set to TRUE to parse encoded (e.g. &#123;) tags

The original string with all {filedir_n}’s parsed

Return type: