Plugin Directory

Document Gallery

This plugin generates thumbnails for documents and displays them in a gallery-like format for easy sharing.

  1. Upload document-gallery to the /wp-content/plugins/ directory
  2. Activate the plugin through the 'Plugins' menu in WordPress
  3. Place [dg] in any posts or pages you want a document gallery included. See below for additional display options.

Document Gallery Options

In order to include all compatible documents from a given page or post, you must include the following shortcode in the post: [dg].

In addition to the default behavior, the plugin provides many options to customize behavior with various attributes, some of which are shown below:

[dg [fancy=<true/false>] [attachment_pg=<true/false>] [descriptions=<true/false>] [order=<ASC/DESC>] [orderby=<**see below**>]]

Though the shortcode above may seem far from "short," none of the attributes are required and most users will find that the plugin meets your needs "out of the box" without any added attributes.

Default Values

Default document gallery behavior can be configured in your dashboard under Settings -> Document Gallery.

Attachment Page Option (New in Version 1.1)

This option determines whether each document icon will link to the actual file or to its attachment page. If you want the user to be able to click on the icon and directly receive the option to download then use attachment_pg=false (the default). If you have information on the attachment page that you want the link to go to, use attachment_pg=true.

Categories/Custom Taxonomy Option (New in Version 1.4)

With the categories option you are able to select attachments based on their assigned category or any other custom taxon. Categories or any custom taxon can be referenced simply by including category=category_value or taxon_name=taxon_value. Multiple values for a single taxon may be separated by commas. Note that if a taxon value contains spaces then the entire comma- delimited list must be quoted.

Columns Option (New in Version 3.0)

The columns option does what it sounds like -- sets how many columns to use in rendering your gallery. With columns=-1, you will get an infinite number of columns. In other words, only 1 row with all icons.

Descriptions Option

If true, each document will take its own line with the description displayed alongside it.

Note: this will use the description field, not the caption. Be careful when entering your document data.

Fancy Option (New in Version 2.0)

If true, we will try to generate a thumbnail for each document in the gallery. The success in generating thumbs will depend mostly on what your server supports. To fine-tune how thumbnails are generated, visit Settings -> Document Gallery in your site's dashboard.

ID Option (New in Version 3.0)

This option indicates from which parent post/page to retrieve attachments. If not explicitly set, the default will be the post/page where the shortcode is being used.

If you do not wish to filter by parent, id=-1 will match all attachments.

IDs Option (New in Version 1.2)

This is an advanced option intended for experienced WordPress users. If this option is used, the plugin will ignore attached documents, instead including all attachments defined by the ids attribute (e.g.: ids=10,2,4,42).

Note: If this attribute is used, order defaults to the order of IDs given rather than menu_order unless order is explicitly stated.

Images Option (New in Version 1.2)

This option will tell the plugin to include all images attached to to a page or post in addition to all documents.

Include/Exclude Options (New in Version 3.0)

As the name suggests, these options allow for explicitly adding or removing matched attachments in your gallery. Like with the IDs options above, these options take a comma-delimited list of attachment IDs.

Limit Option (New in Version 2.3)

As the name suggests, this value will limit how many results are returned in the gallery. If set to -1, the limit is infinite.

MIME Types Option (New in Version 3.0)

This is a comma-delimited list of all MIME types to be included in the gallery. Most users will not need to modify this value.

One example use-case would be to include images in your gallery (which are not included by default). To do this, you would simply set


, where "image" is the only difference from the default value. You could also create a gallery which only includes PDFs by setting mime_types=application/pdf.

New Window Option (New in Version 3.2)

If true, clicking one of the documents in your gallery will open the target link in a new window/tab.

Order Option

This option works alongside the orderby option to determine whether the documents are displayed in ascending or descending order.

Orderby Option

  • menu_order - This is probably the one you want to use. Menu order is the order that icons appear when seen in the Insert / Upload Media Gallery dialog. To change this order, you simply drag the icons around until they are where you want them. In earlier versions of WordPress, menu_order was modified by the integer fields in the Insert / Upload Media Gallery dialog. These fields no longer exist in recent releases.
  • title - Order by title.
  • date - Order by upload date.
  • modified - Order by last modified date.
  • rand - Random order.
  • ID - Order by post id.
  • author - Order by author.
  • name - Order by attachment slug.
  • parent - Order by post/page parent id. (Only useful in conjunction with localpost=false option.)
  • comment_count - Order by number of comments (available with WP >= 2.9).
  • none - No order (available with Version 2.8).
  • post__in - Preserve post ID order given in the post__in array.

Relation Option (New in Version 1.4)

The relation option should only be used when also using the category or custom taxonomy option (see above).

When using multiple taxa this option allows you to decide whether the attachments returned must match all of the different taxa specified (AND) or a minimum of one taxa match (OR).

NOTE: This has no bearing on the relationship between different terms for a single taxon (eg: [dg category=x,y,z relation=AND] will return any attachments where the category is x, y, OR z). If you wish to return only attachments with all 3 categories, you will instead need to use the following syntax: [dg category=x,y,z category_relation=AND]. This syntax of *taxon_relation will work for any taxon, not just "category."*

Customize Appearance

The Default Document gallery will often fit quite well with whatever theme you are using. But, if you want to change things, Document Gallery makes that easy. Just navigate to Settings -> Document Gallery and put any custom CSS in the provided text box.

See style.css for all of the ids and classes being used in a Document Gallery.


Say I would like to include a border for the right and bottom of the document icon, but only when descriptions are shown (to delineate the icon from the description text). To do this, I would need to use the following CSS:

.document-icon-wrapper.descriptions .document-icon{
   border-right: 1px solid #37824A;
   border-bottom: 1px solid #37824A;

Now, if I wanted to modify that code to instead add the same border to all of the document-icons, regardless of whether they have a description or not, I would just change the first line, removing the descriptions class like so:

.document-icon-wrapper .document-icon


For those unfamiliar with content filters, here is some documentation that you should read before continuing.

Filter HTML Output

In Documnet Gallery version 2.2, we've released a more powerful HTML templating framework, making all generated output filterable, and thus configurable, by developers wishing to control the gallery output. Three different filters are provided in order to access the various segments of a gallery: dg_gallery_template, dg_row_template, and dg_icon_template. These filtered templates are used when dynamically generating output for each gallery.

NOTE: The dg_doc_icon has been deprecated with the release and is scheduled to be removed in a future release. If you are using this filter, you are encouraged to replace its usages with dg_icon_template.

Each of the following filters provides an bool argument which indicates whither the gallery being generated will display descriptions, which allows you to handle galleries with and without descriptions differently.

If you wish to wrap your galleries in some additional content, the dg_gallery_template is the tool for the job. With it you can include content prior to or following your document galleries. The filter exposes 1 special tag which is replaced during gallery generation with data specific to that gallery. The tag is described below:

  • %rows%: This tag is replaced by all of the document gallery rows. Everything before this string will be rendered before the gallery and everything after this string will be rendered following the gallery.

If you wish to modify how gallery rows are generated, dg_row_template, is provided for this purpose. This filter gives you control at the row level for how a gallery will be generated. The filter exposes 2 special tags which are replaced during gallery generation with row-specific data. These tags are as follows:

  • %class%: The class attribute value for this row.
  • %icons%: The icon data for this row.

If you wish to modify the HTML that wraps individual icons, the dg_icon_template filter is what you will use. The filter is passed two arguments which may be used to gain additional information about the document that will be used in generating this icon. The first argument is a bool value which indicates whether descriptions will be used along with the icon and the second value is an integer WordPress attachment ID which may be used to lookup any relevant information you need specific to that document. The filter exposes 5 special tags which are replaced during gallery generation with document-specific data. These tags are as follows:

  • %link%: The URL that will be loaded when the user clicks the icon.
  • %target%: The target attribute for the anchor tag (e.g.: _blank, _self).
  • %img%: The URL pointing the the image that will be displayed.
  • %title%: The human-readable title of the attachment.
  • %title_attribute%: The escaped title (above), safe for using HTML tag attributes.
  • %description%: The attachment description (only present when rendering descriptions).
  • %extension%: The document file extension.
  • %size%: The human-readable file size formatted by size_format.
  • %path%: The system path pointing to the document.

Filter Thumbnail Generation Methods

Document Gallery provides the dg_thumbers filter, which allows developers to add, remove, or even re-order which methods are used to generate a thumbnail for a given attachment.

The value being filtered is an associative array with keys equal to a regular expression matching all file extensions supported by the generator and values equal to callables which take an attachment ID and a file page number as arguments.

The callable given should return false if thumbnail generation fails or a system path to a temporary copy of the generated image if generation succeeds. The caller will manipulate the file at the returned path so do not pass in a file path to the original copy of anything as it will be destroyed. Also, do not worry about any image resizing or giving the file a sensible name as the caller of your method will resize and rename the file before returning.

The following is an example taken from the Document Gallery source (with a few modifications for ease of readability), where we add thumbnail generation for all Audio/Video filetypes supported by WordPress:

function dg_filter_thumbers($thumbers) {
    $av_file_types = array_merge(wp_get_audio_extensions(), wp_get_video_extensions());
    $exts = implode('|', $av_file_types);
    $thumbers[$exts] = 'dg_get_audio_video_thumbnail';
add_filter('dg_thumbers', 'dg_filter_thumbers', 10);

function dg_get_audio_video_thumbnail($ID, $pg) {
    include_once ABSPATH . 'wp-admin/includes/media.php';

    $attachment = get_post($ID);
    $doc_path = get_attached_file($ID);

    // get the file metadata
    if (preg_match('#^video/#', get_post_mime_type($attachment))) {
       $metadata = wp_read_video_metadata($doc_path);
    elseif (preg_match('#^audio/#', get_post_mime_type($attachment))) {
       $metadata = wp_read_audio_metadata($doc_path);

    // unsupported mime type || no embedded image present
    if(!isset($metadata) || empty($metadata['image']['data'])) {
       return false;

    $ext = 'jpg';
    switch ($metadata['image']['mime']) {
       case 'image/gif':
          $ext = 'gif';
       case 'image/png':
          $ext = 'png';

    $tmp_dir = untrailingslashit(get_temp_dir());
    $temp_file = $tmp_dir . DIRECTORY_SEPARATOR . wp_unique_filename($tmp_dir, md5(time()) . ".$ext");

    if (!$fp = @fopen($temp_file, 'wb')) {
       return false;

    if (!@fwrite($fp, $metadata['image']['data'])) {
       return false;


    return $temp_file;

Filter Inclusion of Default Document Gallery CSS

If you wish to completely replace Document Gallery styling with your own CSS, you can prevent any any CSS being loaded by returning false in dg_use_default_gallery_style filter, like so:

add_filter('dg_use_default_gallery_style', '__return_false');

*NOTE: By design, this will NOT disable inclusion of any custom CSS set at

Dashboard -> Settings -> Document Gallery


Requires: 4.1 or higher
Compatible up to: 4.3.1
Last Updated: 2015-9-20
Active Installs: 10,000+


4.9 out of 5 stars


5 of 14 support threads in the last two months have been resolved.

Got something to say? Need help?


Not enough data

2 people say it works.
0 people say it's broken.

100,1,1 100,2,2
0,1,0 100,1,1 100,1,1 100,1,1 100,1,1 0,1,0 100,1,1
100,1,1 0,1,0 80,5,4
100,1,1 100,1,1 100,1,1
100,1,1 100,1,1
100,1,1 100,2,2
100,1,1 50,2,1 100,2,2 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1
100,2,2 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1
100,2,2 100,1,1 100,1,1 100,1,1
100,1,1 100,1,1 100,1,1
100,3,3 100,2,2 100,3,3 100,1,1 100,2,2 100,2,2 100,2,2 100,1,1 100,2,2 100,2,2 100,1,1 100,1,1
100,2,2 100,3,3 100,1,1 100,1,1 100,1,1
100,1,1 100,1,1
100,1,1 100,1,1
100,1,1 100,1,1
100,1,1 100,1,1
100,2,2 67,3,2 100,2,2 100,1,1
100,1,1 0,1,0 100,4,4
100,1,1 100,3,3 100,4,4 100,1,1 100,3,3
100,1,1 100,1,1 100,1,1
100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,2,2 100,1,1 100,1,1
100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1
100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,3,3 100,2,2 100,2,2
100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,1,1 100,2,2