Filters and Actions of Iptanus File Upload Plugin

The Iptanus File Upload plugin exposes a set of filters so that developers can extend it and carry out advanced operations. Each one below shows what it receives and what it must return.

Filters

wfu_before_frontpage_scripts

Runs before any front-end scripts and styles are declared, and can control which of them load. It helps resolve jQuery conflicts with other plugins, such as NextGEN Gallery.

/*  This filter runs before the plugin registers frontpage scripts and styles, in  order to execute custom configuration.  In addition, through this filter, the user can enable some "hidden" plugin  settings to resolve incompatibilities and problems with other plugins or  themes. For the moment, settings are included for correcting incompatibilities  with JQuery UI css and NextGen Gallery plugin. In the future more settings  will be added.*/if (!function_exists('wfu_before_frontpage_scripts_handler')) {	/** Function syntax	 *  The function takes one parameter, $changable_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the following items:	 *    > correct_JQueryUI_incompatibility: if this item is set to "true",	 *      then adjustments will be performed in the plugin so that it does not	 *      cause incompatibilities with JQuery UI css.	 *    > correct_NextGenGallery_incompatibility: if this item is set to	 *      "true", then adjustments will be performed in the plugin so that it	 *      does not cause incompatibilities with NextGen Gallery plugin.	 *    > exclude_timepicker: if this item is set to "true", then timepicker	 *      element's css and js code will not be loaded	 *  If $changable_data contains the key 'return'value', then no plugin	 *  scripts and styles will be loaded.	 *  The function must return the final $changable_data. */	function wfu_before_frontpage_scripts_handler($changable_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_before_frontpage_scripts', 'wfu_before_frontpage_scripts_handler', 10, 1);}

wfu_before_admin_scripts

Runs before any back-end scripts and styles are declared. Like the filter above, it helps resolve jQuery conflicts with other plugins.

/*  This filter runs before the plugin registers and enqueues admin scripts and  styles, in order to execute custom configuration.  In addition, through this filter, the user can enable some "hidden" plugin  settings to resolve incompatibilities and problems with other plugins or  themes. For the moment, settings are included for correcting incompatibilities  with JQuery UI css and NextGen Gallery plugin. In the future more settings  will be added.*/if (!function_exists('wfu_before_admin_scripts_handler')) {	/** Function syntax	 *  The function takes one parameter, $changable_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the following items:	 *    > correct_JQueryUI_incompatibility: if this item is set to "true",	 *      then adjustments will be performed in the plugin so that it does not	 *      cause incompatibilities with JQuery UI css.	 *    > correct_NextGenGallery_incompatibility: if this item is set to	 *      "true", then adjustments will be performed in the plugin so that it	 *      does not cause incompatibilities with NextGen Gallery plugin.	 *    > exclude_codemirror: if this item is set to "true", then codemirror	 *      editor's css and js code will not be loaded	 *    > exclude_datepicker: if this item is set to "true", then datepicker	 *      element's js code will not be loaded	 *  If $changable_data contains the key 'return'value', then no plugin	 *  scripts and styles will be loaded.	 *  The function must return the final $changable_data. */	function wfu_before_admin_scripts_handler($changable_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_before_admin_scripts', 'wfu_before_admin_scripts_handler', 10, 1);}

wfu_before_upload

Runs before the upload starts, so you can carry out preliminary server-side actions and either let the upload begin or reject it.

/*  This filter runs before the upload starts, in order to perform any preliminary  custom server actions and allow the upload to start or reject it.  */if (!function_exists('wfu_before_upload_handler')) {	/** Function syntax	 *  The function takes two parameters, $changable_data and $additional_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the items:	 *    > error_message: initially it is set to an empty value, if the handler	 *      sets a non-empty value then upload will be cancelled showing this	 *      error message	 *    > js_script: javascript code to be executed on the client's browser	 *      right after the filter	 *  - $additional_data is an array with additional data to be used by the	 *    filter (but cannot be modified) as follows:	 *    > sid: this is the id of the plugin, as set using uploadid attribute;	 *      it can be used to apply this filter only to a specific instance of	 *      the plugin (if it is used in more than one pages or posts)	 *    > unique_id: this id is unique for each individual upload attempt	 *      and can be used to identify each separate upload	 *    > files: holds an array with data about the files that have been	 *      selected for upload; every item of the array is another array	 *      with the following items:	 *      >> filename: the filename of the file	 *      >> filesize: the size of the file	 *  The function must return the final $changable_data. */	function wfu_before_upload_handler($changable_data, $additional_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_before_upload', 'wfu_before_upload_handler', 10, 2);}

wfu_before_file_check

Runs before a file is uploaded and before the plugin’s own checks, so you can apply checks of your own or change basic upload parameters such as the filename or the user data.

/*  This filter runs before the uploaded file is sent to the server and before the  plugin executes file validity checks (filename, extension, size etc.). It can  be used to perform custom file checks and reject the file if checks fail, or  customize the upload file path (or filename) taking into account data from  user data fields.*/if (!function_exists('wfu_before_file_check_handler')) {	/** Function syntax	 *  The function takes two parameters, $changable_data and $additional_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the items:	 *    > file_path: the full path of the uploaded file	 *    > user_data: an array of user data values, if userdata are activated	 *    > error_message: initially it is set to an empty value, if the handler	 *        sets a non-empty value then upload of the file will be cancelled	 *        showing this error message	 *    > admin_message: initially it is set to an empty value, if the handler	 *        sets a non-empty value then this value will be shown to	 *        administrators if adminmessages attribute has been activated,	 *        provided that error_message is also set. You can use it to display	 *        more information about the error, visible only to admins.	 *  - $additional_data is an array with additional data to be used by the	 *    filter (but cannot be modified) as follows:	 *    > shortcode_id: this is the id of the plugin, as set using uploadid	 *        attribute; it can be used to apply this filter only to a specific	 *        instance of the plugin (if it is used in more than one pages or	 *        posts)	 *    > file_unique_id: this id is unique for each individual file upload	 *      and can be used to identify each separate upload	 *    > file_size: the size of the uploaded file	 *    > user_id: the id of the user that submitted the file for upload	 *    > page_id: the id of the page from where the upload was performed	 *        (because there may be upload plugins in more than one page)	 *  The function must return the final $changable_data. */	function wfu_before_file_check_handler($changable_data, $additional_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_before_file_check', 'wfu_before_file_check_handler', 10, 2); }

wfu_before_file_upload

Runs immediately before a file is uploaded, so you can change its name.

/*  This filter runs right before the uploaded file starts to be uploaded in order  to make modifications of its filename.*/if (!function_exists('wfu_before_file_upload_handler')) {	/** Function syntax	 *  The function takes two parameters, $file_path and $file_unique_id.	 *  - $file_path is the filename of the uploaded file (after all internal	 *    checks have been applied) and can be modified by the filter.	 *  - $file_unique_id is is unique for each individual file upload and can	 *    be used to identify each separate upload.	 *  The function must return the final $file_path.	 *  If additional data are required (such as user id or userdata) you can	 *  get them by implementing the previous filter wfu_before_file_check and	 *  link both filters by $file_unique_id parameter. Please note that no	 *  filename validity checks will be performed after the filter. The filter	 *  must ensure that filename is valid. */	function wfu_before_file_upload_handler($file_path, $file_unique_id) {		// Add code here...		return $file_path;	}	add_filter('wfu_before_file_upload', 'wfu_before_file_upload_handler', 10, 2);}

wfu_after_file_loaded

Runs once a file has fully loaded on the server, so you can inspect its contents and accept or reject it.

/*  This filter runs after every individual file has completely loaded on server.  It provides the opportunity to perform custom checks on its contents and  reject or accept it.  */if (!function_exists('wfu_after_file_loaded_handler')) {	/** Function syntax	 *  The function takes two parameters, $changable_data and $additional_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the items:	 *    > error_message: initially it is set to an empty value, if the handler	 *      sets a non-empty value then upload of the file will be cancelled	 *      showing this error message	 *    > admin_message: initially it is set to an empty value, if the handler	 *      sets a non-empty value then this value will be shown to	 *      administrators if adminmessages attribute has been activated,	 *      provided that error_message is also set. You can use it to display	 *      more information about the error, visible only to admins.	 *  - $additional_data is an array with additional data to be used by the	 *    filter (but cannot be modified) as follows:	 *    > file_unique_id: this id is unique for each individual file upload	 *      and can be used to identify each separate upload	 *    > file_path: the full path of the uploaded file	 *    > shortcode_id: this is the id of the plugin, as set using uploadid	 *      attribute; it can be used to apply this filter only to a specific	 *      instance of the plugin (if it is used in more than one pages or	 *      posts)	 *  The function must return the final $changable_data. */	function wfu_after_file_loaded_handler($changable_data, $additional_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_after_file_loaded', 'wfu_after_file_loaded_handler', 10, 2); }

wfu_before_email_notification

Runs before the notification email is sent, so you can check or modify it.

/*  This filter runs after file upload has finished and right before the  notification email is sent (if email notifications are enabled). It allows to  customize the email contents, taking also into account any user data.*/if (!function_exists('wfu_before_email_notification_handler')) {	/** Function syntax	 *  The function takes two parameters, $changable_data and $additional_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the items:	 *    > recipients: the list of recipients (before dynamic variables are	 *      applied)	 *    > subject: the email subject (before dynamic variables are applied)	 *    > message: the email body (before dynamic variables are applied)	 *    > headers: the email headers, if exist (before dynamic variables are	 *      applied)	 *    > user_data: an array of user data values, if userdata are activated	 *    > filename: a comma separated list of uploaded file names (only the	 *      file names)	 *    > filepath: a comma separated list of uploaded file paths (absolute	 *      full file paths)	 *    > error_message: initially it is set to an empty value, if the handler	 *      sets a non-empty value then email sending will be cancelled showing	 *      this error message (message will be shown only to administrators if	 *      adminmessages attribute has been activated)	 *  - $additional_data is an array with additional data to be used by the	 *    filter (but cannot be modified) as follows:	 *    > shortcode_id: this is the id of the plugin, as set using uploadid	 *      attribute; it can be used to apply this filter only to a specific	 *      instance of the plugin (if it is used in more than one pages or	 *      posts)	 *  The function must return the final $changable_data. */	function wfu_before_email_notification_handler($changable_data, $additional_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_before_email_notification', 'wfu_before_email_notification_handler', 10, 2); }

wfu_after_file_upload

Runs after each individual file has finished uploading, so you can carry out extra tasks and supply JavaScript to run in the visitor’s browser.

/*  This filter is executed after the upload process for each individual file has  finished, in order to allow additional tasks to be executed and define custom  javascript code to run in the client's browser. */if (!function_exists('wfu_after_file_upload_handler')) {	/** Function syntax	 *  The function takes two parameters, $changable_data and $additional_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the items:	 *    > ret_value: not used for the moment, it exists for future additions	 *    > js_script: javascript code to be executed on the client's browser	 *      after each file is uploaded	 *  - $additional_data is an array with additional data to be used by the	 *    filter (but cannot be modified) as follows:	 *    > shortcode_id: this is the id of the plugin, as set using uploadid	 *      attribute; it can be used to apply this filter only to a specific	 *      instance of the plugin (if it is used in more than one pages or	 *      posts)	 *    > file_unique_id: this id is unique for each individual file upload	 *      and can be used to identify each separate upload	 *    > upload_result: it is the result of the upload process, taking the	 *      following values:	 *        success: the upload was successful	 *        warning: the upload was successful but with warning messages	 *        error: the upload failed	 *    > error_message: contains warning or error messages generated during	 *      the upload process	 *    > admin_messages: contains detailed error messages for administrators	 *      generated during the upload process	 *  The function must return the final $changable_data. */	function wfu_after_file_upload_handler($changable_data, $additional_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_after_file_upload', 'wfu_after_file_upload_handler', 10, 2);}

wfu_after_upload

Runs once the whole upload has finished, for any final server-side actions.

/*  This filter runs after the upload completely finishes, in order to perform any  final custom server actions.  */if (!function_exists('wfu_after_upload_handler')) {	/** Function syntax	 *  The function takes two parameters, $changable_data and $additional_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the items:	 *    > js_script: javascript code to be executed on the client's browser	 *      right after the filter; the script can check upload_status variable	 *      for checking if upload has succeeded or not and mode variable for	 *      checking if it was an AJAX or classic upload.	 *  - $additional_data is an array with additional data to be used by the	 *    filter (but cannot be modified) as follows:	 *    > sid: this is the id of the plugin, as set using uploadid attribute;	 *      it can be used to apply this filter only to a specific instance of	 *      the plugin (if it is used in more than one pages or posts)	 *    > unique_id: this id is unique for each individual upload attempt	 *      and can be used to identify each separate upload	 *    > files: holds an array with final data about the files that have been	 *      uploaded (or failed); every item of the array is another array with	 *      the following items:	 *      >> file_unique_id: a unique id identifying every individual file	 *      >> original_filename: the original filename of the file	 *      >> filepath: the final path of the file (including the filename)	 *      >> filesize: the size of the file	 *      >> user_data: an array of user data values, if userdata are	 *         activated, having the following structure:	 *         >>> label: the label of the user data field	 *         >>> value: the value of the user data fields entered by user	 *      >> upload_result: it is the result of the upload process, taking	 *         the following values:	 *           success: the upload was successful	 *           warning: the upload was successful but with warning messages	 *           error: the upload failed	 *      >> error_message: contains warning or error messages generated	 *         during the upload process	 *      >> admin_messages: contains detailed error messages for	 *         administrators generated during the upload process	 *  The function must return the final $changable_data. */	function wfu_after_upload_handler($changable_data, $additional_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_after_upload', 'wfu_after_upload_handler', 10, 2);}

wfu_browser_check_file_action

Runs when a visitor tries to download or delete a file in the front-end file viewer, and decides whether the action is allowed.

/*  This filter runs when the user attempts to download or delete a file of the  front-end file viewer, in order to determine if the action will be accepted.  */if (!function_exists('wfu_browser_check_file_action_handler')) {	/** Function syntax	 *  The function takes two parameters, $changable_data and $additional_data.	 *  - $changable_data is an array that can be modified by the filter and	 *    contains the items:	 *    > error_message: initially it is set to an empty value, if the handler	 *      sets a non-empty value then the download or delete action of the	 *      user will be rejected showing this error message	 *  - $additional_data is an array with additional data to be used by the	 *    filter (but cannot be modified) as follows:	 *    > file_action: the action attempted by the user (download or delete)	 *    > filepath: the full path of the file	 *    > uploaduser: the ID of the user who uploaded the file	 *    > userdata: an array of user data values, if userdata are activated,	 *      having the following structure:	 *      >> label: the label of the user data field	 *      >> value: the value of the user data fields entered by user	 *  The function must return the final $changable_data. */	function wfu_browser_check_file_action_handler($changable_data, $additional_data) {		// Add code here...		return $changable_data;	}	add_filter('wfu_browser_check_file_action', 'wfu_browser_check_file_action_handler', 10, 2);}

wfu_file_browser_edit_column-{$column}

Runs before the front-end file viewer renders, so you can customise the contents of its columns. Replace {$column} in the filter name with the column you want to edit.

/*  This filter enables to edit the contents of the file viewer columns, so that  they can be fully customized. The {$column} variable in the filter name needs  to be replaced by the column name that is to be editted. The filter function  takes 3 parameters, the cell contents that are editable by the function, file  information and additional info.*/if (!function_exists('wfu_file_browser_edit_column_handler')) {	/** Function syntax	 *  The function takes three parameters, $cell, $file and $additional_data.	 *  - $cell is an array that can be modified by the filter and contains the	 *    items:	 *    > contents: the contents that the column cell will have for the	 *      specific file; initially it is takes the default value generated by	 *      the plugin	 *    > sort_value: this is the value that will be used to sort the column	 *      if it is sortable	 *  - $file is an array with information about the specific file; it	 *      contains the following properties:	 *    > name: the file name	 *    > fullpath: the full path of the file	 *    > size: the file size	 *    > mdate: the date of last modification of the file	 *    > filedata: the database object holding upload information about the	 *      file	 *    > deletable: a flag (true or false) determining whether the file can	 *      be deleted by the user who views the file viewer	 *  - $additional_data is an array with additional information; it contains	 *      the following properties:	 *    > bid: the ID if the specific file viewer	 *    > column_sortable: a flag (true or false) determining whether the	 *      column is sortable	 *    > params: an array holding the shortcode parameters of the file viewer	 *  The function must return the final $cell. */	function wfu_file_browser_edit_column_handler($cell, $file, $additional_data) {		// Add code here...		return $cell;	}	add_filter('wfu_file_browser_edit_column-{$column}', 'wfu_file_browser_edit_column_handler', 10, 3);}