1. Document Library Pro
  2. Developer Documentation

Actions and Filters

There are a number of filters provided in Document Library Pro which allow you to customize the behavior of the plugin.

Please note that this article is aimed at developers. If you don't know how to use this code then you should ask your developer.

Need professional assistance?
We've partnered with Codeable to provide our customers with expert help if required.

Filters

Language filters

There are various filters provided for manipulating text strings and messages used in the plugin. Please refer to this article for filters to override the text strings.

document_library_pro_minimum_search_term_length

Set the minimum search term length allowed in the main search box. Defaults to 3 characters.

add_filter( 'document_library_pro__minimum_search_term_length', function( $length ) { 
    return 5; 
} );

document_library_pro_search_filter_get_terms_args

Filters the args passed to get_terms() when building the search filters.

add_filter( 'document_library_pro_search_filter_get_terms_args', function( $args, $taxonomy, Document_Library_Args $table_args ) { 
   // Do something with args, e.g:
   $args['orderby'] = 'menu_order';
   return $args;
}, 10, 3 );

document_library_pro_search_filter_terms_<taxonomy>

Filters the terms to use in the search filter dropdown list. The filter name is dynamic - replace <taxonomy> with the relevant taxonomy slug.

add_filter( 'document_library_pro_search_filter_terms_category', function( $terms, $taxonomy,Document_Library_Args $table_args ) { 
    // Do something with terms
    return $terms;
}, 10, 3 );

document_library_pro_data_filters

Filter all the search filters at once. Returns an array of arrays, with the column used as the top-level array key.

add_filter( 'document_library_pro_data_filters', function( $filters, Document_Library_Args $table_args ) { 
    // Do something with the filters, e.g:
    $filters['categories']['heading'] = 'Choose a category';
    return $filters;
}, 10, 2 );

document_library_pro_data_config

Filters which allows you to override the inline table configuration used when the DataTables script is initialised. You can use this filter, for example, to disable or enable certain table features. The following example disables the ordering/sorting feature in all tables:

// Disable column sorting
add_filter( 'document_library_pro_data_config', function( $config, Document_Library_Args $table_args) {
    $config['ordering'] = false;
    return $config;
}, 10, 2 );

document_library_pro_open_posts_in_new_tab

Product tables contain various links to the product details page. For example, the name column will (by default) include a link to the product page.

These will open in the same tab or window by default. To open them in a new tab use the document_library_pro_open_posts_in_new_tab filter. For example:

add_filter( 'document_library_pro_open_posts_in_new_tab', '__return_true' );

document_library_pro_process_shortcodes

By default, Document Library Pro will strip shortcodes from the post content so any content that would appear inside these shortcodes will not appear in the table. You can enable shortcodes on a per-table basis using the shortcodes option, but if you want to enable them globally, return true from this filter as follows:

add_filter( 'posts_table_process_shortcodes', '__return_true' );

Whether to run the document library shortcode on the search results page. Defaults to false. Normally, you would want to prevent the shortcode running within the search results, as only a snippet or excerpt of each document is shown in the search results. However, if you want to enable tables in the search results, set this filter to return true:

add_filter( 'document_library_pro_run_in_search', '__return_true' );

document_library_pro_data_<column>

There is a data filter available for each column in the table, in the form document_library_pro_data_<column>. These allow you to modify the HTML for each data cell before it is added to the table.

Each filter takes 2 arguments: the data to be added to the table (e.g. the image) and the current WP_Post object.

For example, to filter data for the image column you would use filter document_library_pro_data_image.

add_filter( 'document_library_pro_data_image', function( $image, $post ) {
    // Do something with $image
    return '<div class="foo">' . $image . '</div>';
}, 10, 2 );

The full list of data filters:

  • ID: document_library_pro_data_id
  • Title: document_library_pro_data_title
  • Categories: document_library_pro_data_categories
  • Tags: document_library_pro_data_tags
  • File type: document_library_pro_data_file_type
  • File size: document_library_pro_data_file_size
  • Author: document_library_pro_data_author
  • Date: document_library_pro_data_date
  • Modified date: document_library_pro_data_date_modified
  • Image: document_library_pro_data_image
  • Content: document_library_pro_data_content
  • Excerpt: document_library_pro_data_excerpt
  • Status: document_library_pro_data_status
  • Link: document_library_pro_data_link
  • Button column: document_library_pro_data_button

Note: custom taxonomy and custom field columns use a slightly different format. See the following sections for details.

document_library_pro_data_custom_taxonomy_<taxonomy>

Filter which allows you to modify the value of the data in a custom taxonomy column. Accepts 2 arguments - the $terms as a comma-separated string, and the current post object. For example, if we want to override the data for taxonomy column tax:sector, we would use:

add_filter( 'document_library_pro_data_custom_taxonomy_sector', function( $terms, $post ) {
    // do something with $terms
    return $terms;
}, 10, 2 );

document_library_pro_data_custom_field

Filter which allows you to override the value of all custom fields in the table. It accepts 3 arguments – the custom field value, the custom field name and the current post object.

// Override the 'extra_notes' custom field
add_filter( 'document_library_pro_data_custom_field', function( $value, $field, $post ) {
    if ( 'extra_notes' === $field ) {
       // do something with $value
    }
    return $value;
}, 10, 3 );

document_library_pro_data_custom_field_<field>

Similar to the document_library_pro_data_custom_field filter, but specific to a custom field. The <field> portion of the filter is replaced by the field name. It accepts 2 arguments - the field value and the current post object.

// Override the 'extra_notes' custom field
add_filter( 'document_library_pro_data_custom_field_extra_notes', function( $value, $post ) {
    // do something with $value
    return $value;
}, 10, 2 );

Use this filter to override the URL used for a URL-based custom field. Note: this filter is only applied when the custom field value is a URL (i.e. begins with https:// or https://).

add_filter( 'document_library_pro_url_custom_field_link', function( $url, $field, $post ) { 
    return $link;
}, 10, 3 );

document_library_pro_url_custom_field_text

Use this filter to override the text used for a URL-based custom field. Defaults to the URL without the leading https://. Note: this filter is only applied when the custom field value is a URL (i.e. begins with https:// or https://).

add_filter( 'document_library_pro_url_custom_field_text', function( $text, $field, $post ) { 
   // do something with $text 
    return $text;
}, 10, 3 );

posts_table_custom_field_stored_date_format

If you are using date-based custom fields in your table, you may find that your dates are sometimes incorrectly sorted or formatted. The most likely cause of this is the date conversion functions used by the plugin which are built into PHP.

For example, dates such as “12/04/2018” are assumed to be in U.S. format with the month first. So this example date would be December 4th, 2018.

If the date is separated by dash (-), dot (.) or other symbol, it’s assumed to be a European/Australian date with the day before the month. If you’re using dates separated by a forward slash but in this format: d/m/Y, the plugin will not be able to sort these correctly, or format them if you’re using the date_format option. To fix this, you will need to set this filter.

Note: this is not related to how the custom field is actually displayed in the table - see the date_format option for controlling the date output.

add_filter( 'document_library_pro_custom_field_stored_date_format', function( $format, $field ) { 
    if ( 'despatch_date' === $field ) {
        return 'd/m/Y';
    }
    return ''; 
}, 10, 2 );

document_library_pro_custom_field_is_eu_au_date

Use this filter to specify that a custom field in your table should be treated as a date in EU/AU format (i.e. day before month). This is an alternative to the above filter - document_library_pro_custom_field_stored_date_format - which requires you specify the exact format your date is stored in. This filter instead requires a boolean true or false to indicate whether to treat the field as an EU/AU date.

The can be applied globally to all date-based custom fields, as follows:

​add_filter( 'document_library_pro_custom_field_is_eu_au_date', '__return_true' );

Or you can use it for individual custom fields:

​add_filter( 'document_library_pro_custom_field_is_eu_au_date', function( $is_eu_date, $field ) {
    if ( 'event_date' === $field ) {
        return true;
    }
    return false;
}, 10, 2 );

document_library_pro_taxonomy_is_eu_au_date

Use this filter to specify that a custom taxonomy column in your table should be treated as a date in EU/AU format (i.e. day before month). This can be applied globally to all date-based taxonomies as follows:

add_filter( 'document_library_pro_taxonomy_is_eu_au_date', '__return_true' );

Or you can use it for individual taxonomies:

​add_filter( 'document_library_pro_taxonomy_is_eu_au_date', function( $is_eu_date, $tax ) {
    if ( 'event_date' === $tax ) {
        return true;
    }
    return false;
}, 10, 2 );

document_library_pro_acf_value

Filters which allows you to override the custom field values returned from Advanced Custom Fields. It accepts 3 arguments – the custom field value, the ACF field object and the current post ID.

add_filter( 'document_library_pro_acf_value', function( $value, $field_obj, $post_id ) {
    if ( 'file' === $field_obj['type'] ) {
       // do something with $value
    }
    return $value;
}, 10, 3 );

document_library_pro_button_column_button_text

Filter the text used for the button element when using the button column in the table. The text is set via the Plugin Settings page or the button_text shortcode option. You can use this filter to add more complex formatting around the text.

add_filter( 'document_library_pro_button_column_button_text', function( $text ) { 
    return '<span>' . $text . '</span>';
} );

document_library_pro_button_column_button_class

Filter the CSS class for the button element when using the button column in the table. Defaults to: button btn posts-table-button

add_filter( 'document_library_pro_button_column_button_class', function( $class ) { 
    return $class . ' custom-btn';
} );

document_library_pro_more_content_text

Filter which controls the text/HTML appended when data in the content or excerpt columns is truncated. Defaults to  &hellip;.

add_filter( 'document_library_pro_more_content_text', function( $more_text ) {
    return ' [...]';
} );

document_library_pro_separator_<type>

Filter which allows you to change the separator used between categories, tags, terms and custom fields. For example, a post can have multiple categories, each separated by a comma. This filter allows you to change the comma for a different character, line breaks, or other custom HTML.

The filter must include the relevant type. Possible values for type are: categories, tags, terms, custom_field, and custom_field_row.

For example, to change the separator between categories in the table, add this filter:

add_filter( 'document_library_pro_separator_categories', function( $sep ) {
    return '<br/>';
} );

document_library_pro_custom_class

Use this filter to add additional CSS classes to the table's <table> element. Type: string

add_filter( 'document_library_pro_custom_class', function( $class ) {
    return 'feature-table';
} );

document_library_pro_row_class

Use this filter to add extra CSS classes to each row in the table, or selectively based on the current post. Type: array

add_filter( 'document_library_pro_row_class', function( $class, WP_Post $post ) {
    if ( 23 === $post->ID ) {
        $class[] = 'featured';
    }
    return $class;
}, 10, 2 );

document_library_pro_row_attributes

Use this filter to add extra attributes (e.g. data attributes) to the <tr> element in the table. Should return an array of attribute pairs in the format key => value.

add_filter( 'document_library_pro_row_attributes', function( $attributes, $post ) {
    $attributes['data-foo'] = 'bar';
    return $attributes;
}, 10, 2 );

document_library_pro_column_class_<column>

This filter allows you to add additional CSS classes to columns (i.e. the <td> cells) in the table. Replace <column> with the column that you want to add the class to. You may add additional classes, but do not remove any from the list passed in, as it may affect the operation of the table.

add_filter( 'document_library_pro_column_class_title', function( $classes ) {
    $classes[] = 'highlight';
    return $classes;
} );

document_library_pro_column_heading_<column>

Filter which allows you to override a column heading for all tables on your site. If a custom heading is specified within the shortcode itself (in the columns option), then it will take priority over the value returned from this filter.

add_filter( 'document_library_pro_column_heading_title', function( $heading ) {
    return 'My Title';
} );

document_library_pro_column_priority_<column>

Filter which allows you to override a column priority for all tables on your site. If a priority is specified within the shortcode itself (using the priorities option), then it will take priority over the value returned from this filter.

add_filter( 'document_library_pro_column_priority_date', function( $priority ) {
    return 10;
} );

document_library_pro_column_width_<column>

Filter which allows you to override a column width for all tables on your site. If a width is specified within the shortcode itself (using the widths option), then it will take priority over the value returned from this filter.

add_filter( 'document_library_pro_column_width_author', function( $width ) {
    return '100px';
} );

document_library_pro_column_searchable_<column>

This filter allows you to set whether or not a column is “searchable” in the table. If a column is searchable, it means that the column will be used when the user types something into the search box above the table.

By default, the plugin includes all columns for searching, except for the image column (unless you're using the lazy load option, in which case only the title and content columns are searchable). To override this behavior when you're not using lazy load, use this filter with the appropriate column name added to the filter.

E.g. to exclude the title column from the table search:

add_filter( 'document_library_pro_column_searchable_title', '__return_false' );

If you wish to disable searching for a custom field or taxonomy, use the column name without the cf: or tax: prefix:

add_filter( 'document_library_pro_column_searchable_my_custom_field', '__return_false );

document_library_pro_column_sortable_<column>

This filter allows you to set whether or not a column is “sortable” in the table. If a column is sortable, the table can be re-ordered by that column using the up/down arrows that appear in the column heading.

If you’re using lazy load, the sorting is restricted to certain columns only. If you’re not using lazy load, then sorting is enabled for all columns except image.

E.g. to prevent the table being sorted by title:

add_filter( 'document_library_pro_column_sortable_title', '__return_false' );

See the note above about using this filter for custom field or taxonomy columns.

document_library_pro_max_posts_limit

Filter which allows you to override the maximum posts limit (500 posts) set in Document Library Pro. Note that this option only applies when you are not using the lazy_load option.

add_filter( 'document_library_pro_max_posts_limit', function( $limit, $posts_table ) {
    return 1000;
}, 10, 2 );

document_library_pro_data_cache_expiry

Filter which allows you to set the expiry time (in seconds) for the table data cache. The default cache expiry time is 6 hours, and is configured via the plugin settings.

add_filter( 'document_library_pro_data_cache_expiry', function( $expiry, Document_Library_Pro_Cache $cache) {
    return 3 * DAY_IN_SECONDS;
}, 10, 2 );

document_library_pro_use_data_cache

Filter whether to use data caching globally across all tables. Should return true or false.

document_library_pro_query_args

Filter which allows you to override the query args passed to WP_Query prior to retrieving posts from the database. See WP_Query documentation for details.

add_filter( 'document_library_pro_query_args', function( $args, $posts_table ) {
    // do something with $args
    return $args;
}, 10, 2 );

document_library_pro_optimize_table_query

Use this filter to disable the database query optimisations applied by Document Library Pro. Use this if you need to directly access the post_content or post_excerpt database fields, even when the content and excerpt columns are not displayed in your table.

add_filter( 'document_library_pro_optimize_table_query', '__return_false' );

document_library_pro_shortcode_output

Allows you to modify the HTML returned by the [posts_table] shortcode. Takes two parameters: the HTML and the Posts_Data_Table instance.

add_filter( 'document_library_pro_shortcode_output', function( $html, $table ) {
    // do something with HTML
    return $html;
}, 10, 2 );

document_library_pro_load_frontend_scripts

Filter to disable the loading of the frontend scripts and styles used in Document Library Pro. Only use this if you want to load the scripts yourself (e.g. on specific pages).

add_filter( 'document_library_pro_load_frontend_scripts', '__return_false' );

document_library_pro_use_fitvids

Filter to disable the use of FitVids script used in Document Library Pro. FitVids is used to ensure videos are sized correctly at smaller screen sizes.

add_filter( 'document_library_pro_use_fitvids', '__return_false' );

document_library_pro_enable_select2

Filter whether to enable or disable the Select2 Javascript library. This library adds enhancements to the search filters and page length dropdown menus above and below the table. It is enabled by default. To disable it, use:

add_filter( 'document_library_pro_enable_select2', '__return_false' );

document_library_pro_show_details_in_single_content

Filter to disable the output of the documen details in the single document content

add_filter( 'document_library_pro_show_details_in_single_content', '__return_false' );

document_library_pro_csv_importer_batch_size

Filter which allows you to override the CSV import batch size (default: 30).

add_filter( 'document_library_pro_csv_importer_batch_size', function( $batch_size ) {
    return 10;
}, 10, 1 );

document_library_pro_csv_importer_default_time_limit

Filter which allows you to override the time limit to process a batch in the CSV importer. This is set at 20 seconds by default because a timeout limit of 30 seconds is common on shared hosting.

add_filter( 'document_library_pro_csv_importer_default_time_limit', function( $time_limit ) {
    return 50;
}, 10, 1 );

document_library_pro_csv_importer_time_exceeded

Filter to bypass the batch time exceeded check in the CSV importer.

add_filter( 'document_library_pro_csv_importer_time_exceeded', '__return_false' );

document_library_pro_csv_importer_memory_exceeded

Filter which allows you to bypass the memory limit check.

add_filter( 'document_library_pro_importer_memory_exceeded', '__return_false' );

document_library_pro_csv_importer_check_import_file_path

Filter which allows you to bypass checking for the CSV import file path.

add_filter( 'document_library_pro_csv_importer_check_import_file_path', '__return_false' );

document_library_pro_csv_importer_valid_filetypes

Filter which allows you to add additional valid file import types (default: CSV and TXT).

add_filter( 'document_library_pro_csv_importer_valid_filetypes', function( $file_types ) {
    return array_merge( $file_types, [ 'TSV' => 'text/tsv' ] );
}, 10, 1 );

document_library_pro_csv_importer_mapping_default_columns

Filter which allows you to add additional column mapping for the CSV importer.

add_filter( 'document_library_pro_csv_importer_mapping_default_columns', function( $default_columns, $raw_headers ) {
    return array_merge( $default_columns, [ 'Column Name' => 'column_key' ] );
}, 10, 2 );

document_library_pro_csv_importer_mapping_special_columns

Filter which allows you to add additional specia multi-column lmapping for the CSV importer.

add_filter( 'document_library_pro_csv_importer_mapping_special_columns', function( $special_columns, $raw_headers ) {
    return array_merge( $special_columns, [ 'Column Name' => 'column_prefix:' ] );
}, 10, 2 );

document_library_pro_csv_importer_mapped_columns

Filter which allows you to change any column mappings right before retrieval.

document_library_pro_csv_importer_formatting_callbacks

Filter which allows you to change or add any column formatting callbacks.

document_library_pro_csv_importer_parsed_data

Filter which allows you to modify the parsed CSV data.

document_library_pro_csv_importer_pre_expand_data

Filter which allows you to modify the CSV data before it is expanded.

document_library_pro_csv_importer_process_item_data

Filter which allows you to modify individual item data from the CSV before it is added as a document post.

add_filter( 'document_library_pro_csv_importer_process_item_data', function( $data ) {
    // do something with $data
    return $data;
}, 10, 1 );

document_library_pro_plupload_options

Filter which allows you to modify the initialization options for plupload in the drag and drop importer.

add_filter( 'document_library_pro_plupload_options', function( $options ) {
    // do something with $options
    return $options;
}, 10, 1 );

Actions

document_library_pro_parse_args

Fired when the table arguments have been parsed and set. Takes one argument – the Barn2\Plugin\Document_Library_Pro\Posts_Table_Pro\Table_Args instance.

document_library_pro_args_updated

Fired when the table args are updated. This happens, for example, when the table is filtered by category or a search term is entered. Takes one argument - the Barn2\Plugin\Document_Library_Pro\Posts_Table object.

document_library_pro_before_get_table

Fired once before the table is created, before the attributes and headings are added to the table. Takes one argument – the Barn2\Plugin\Document_Library_Pro\Posts_Table_Pro\Posts_Table object.

document_library_pro_after_get_table

Fired once after each the table is fully created and (for standard loading) the data has been added. Takes one argument – the Barn2\Plugin\Document_Library_Pro\Posts_Table_Pro\Posts_Table object.

document_library_pro_before_get_data

Fired once before the data is fetched and added to the table. Takes one argument – the Barn2\Plugin\Document_Library_Pro\Posts_Table_Pro\Posts_Table object.

document_library_pro_after_get_data

Fired once after the data is added to the table. Takes one argument – the Barn2\Plugin\Document_Library_Pro\Posts_Table_Pro\Posts_Table object.

document_library_pro_single_document_details_list_before

Fired before the single document details list is output. The global $post object is a available here.

document_library_pro_single_document_details_list_after

Fired after the single document details list is output. The global $post object is a available here.

Related Articles

Still need help?
If searching the knowledge base hasn't answered your question, please contact support.