Recommended Alternative¶

The file field class is not recommended for use in ExpressionEngine version 3. When creating a file upload in the control panel, use the CP/FilePicker Service.

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:

ee()->load->library('file_field');

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')

Parameters:	$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
Returns:	the HTML representation of the field
Return type:	String

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);

Parameters:	$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');

Parameters:	$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
Returns:	Associative array with a 'value' key with a value that’s uploaded file’s name
Return type:	Array

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);

Parameters:	$file_name (string) – the file name $directory_id (integer) – the directory id where the file is located
Returns:	the formatted field data (e.g. {filedir_1}filename.ext)
Return type:	String

Parsing the Formatted Data¶

File_field::parse_field($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:

ee()->file_field->parse_field($data);

Parameters:	$data (string) – the template to parse
Returns:	the template with {filedir_n} parsed out
Return type:	String

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. {filedir_n}):

ee()->file_field->parse_string($data);

Parameters:	$data (string) – The string to parse {filedir_n} in $parse_encoded (bool) – Set to TRUE to parse encoded (e.g. {) tags
Returns:	The original string with all {filedir_n}’s parsed
Return type:	String