WordPress.org

Ready to get started?Download WordPress

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, seen below:

[dg [fancy=<true/false>] [attachment_pg=<true/false>]
[category/custom_taxon_name=<**comma-separated list of taxon values**> [relation=<AND/OR>]]
[descriptions=<true/false>] [ids=<**comma-separated list of ID #s**>]
[images=<true/false>] [localpost=<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

By default, document gallery will use no descriptions, orderby menu_order , ASC order, no attachment_pg links, and no images from the local post if you do not specify otherwise. These defaults 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 rective 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.

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 (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.

NOTE: By default, the most universally-supported option for generating thumbnails, Google Drive Viewer is disabled by default in order to protect your privacy, since using it requires sending your documents to Google's servers. If you're not working with confidential documents, you are encouraged to enable this for optimum performance.

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.

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.

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, the order, orderby, images and other attributes which generally determine which attachments to include or how to order them will be ignored. Order is defined by the order the ids are provided.

Localpost Option (New in Version 1.4)

By default a document gallery only looks at attachments of the page/post where the [dg] shortcode is used. If you would like to search beyond that local scope, you must set localpost=false.

This option would probably be useful especially when querying with the category or taxonomy option, though it can be used with any options you chose.

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). Additionally, this option is only effective in WordPress installs version 3.1 or higher. Older versions cannot use this value and will ignore it.

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

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.

Example

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

Developers

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

Filter .document-icon Content

Document Gallery provides a filter allowing developers to customize the HTML returned. Specifically, the div.document-icon content, including the div itself, the URL to the attachment, the attachment icon, and the attachment title. Hooking into the dg_doc_icon filter will allow you to modify any of this content before it reaches your users.

Any function using this filter will receive two parameters, the content to be filtered and the ID number of the file represented by the icon in question. If you are implementing something to override the plugin default functionality, it may be useful to be able to query various attributes of the attachment with this value.

One example use for this filter, which I have personally used in a project I am working on, will add a query parameter to the end of each attachment URL. This parameter, rid, specifies the referring page and allows the page receiving the URL to dynamically detect which page ID the link came from.

function dg_doc_icon( $icon, $id ){
   $ptn = '/(.* href=")([^"]+)(".*)/s';

   if( !preg_match( $ptn, $icon, $matches ) || count( $matches ) !== 4 )
      return $icon;

   if( strpos( $matches[2], '?' ) !== false )
      return "{$matches[1]}{$matches[2]}&rid=".get_the_ID().$matches[3];

   return "{$matches[1]}{$matches[2]}?rid=".get_the_ID().$matches[3];
}
add_filter( 'dg_doc_icon', 'dg_doc_icon', null, 2 );

Obviously this is just one very specific example, but anything that requires modifying the image tag, the anchor tag, or the title can be handled with this filter. Note that this function does not use the $id value it receives, which is perfectly alright.

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';
          break;
       case 'image/png':
          $ext = 'png';
          break;
    }

    $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'])) {
       fclose($fp);
       return false;
    }

    fclose($fp);

    return $temp_file;
}

Requires: 3.6 or higher
Compatible up to: 3.9.2
Last Updated: 2014-6-4
Downloads: 31,561

Ratings

4 stars
4.9 out of 5 stars

Support

7 of 15 support threads in the last two months have been resolved.

Got something to say? Need help?

Compatibility

+
=
Not enough data

1 person says it works.
0 people say it's broken.

100,1,1 100,2,2
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
50,2,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,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,3,3
100,1,1