Qdig-WP Plugin

Qdig-WP is a WordPress plugin that integrates Qdig (Quick Digital Image Gallery) into WordPress. The current version is 0.5 and was released on September 1, 2005. It is designed for WordPress 1.5. The plugin has not been tested on WP 1.2 or WP 2.0.

Qdig-WP should be considered beta software and should not yet be used in any mission-critical situations. If your website can’t suffer any possible bugs, you might want to wait until the plugin has been tested better by the community-at-large.

Comments, bug reports, and other issues can be discussed on my forums. However, this plugin is provided as-is, with no promise of support.

Downloads

Two separate downloads are required to install Qdig-WP: the Qdig-WP plugin and Qdig itself.

Qdig-WP
[ source ] [ .tar.gz ] [ .zip ]

Qdig
[ .tar.gz ] [ .zip ]

Requirements

Qdig-WP requires WordPress 1.5 and Qdig 1.2.6 or later (or Qdig devel 20050325 or later). I have no idea if it’ll work with WordPress 2.0 or later, as I haven’t tested it yet.

Installation

Since Qdig is integrating an external program into WordPress, installation and customization requires a few steps.

  1. Download the Qdig-WP plugin (see “Downloads” above) and place the qdig.php file in your plugins directory.
  2. Download the Qdig package (see “Downloads” above). It should contain a folder named either “qdig” or “qdig-devel”. Rename this folder to “qdig” if necessary and place it in your plugins directory.
  3. Create a folder somewhere on your web server that will contain your images. This could be the same directory that you use for WordPress’s built-in image uploading, but it doesn’t have to be.
  4. Customize the Qdig’s index.php file as indicated in the “The Qdig File” section below. The Qdig script is not only very flexible and customizable, but also very well documented to make changing it easy.
  5. Enable the plugin!

A gallery is inserted in a post or page by using a special Qdig tag. See the section entitled “The Tag” below for instructions.

The Qdig File

If you installed properly, the Qdig gallery code will be located at plugins/qdig/index.php. As mentioned above, Qdig is highly customizeable by editting the qdig index.php file, which is very well documented. You have a lot of options for customizing your gallery just as you’d like it. Some suggested settings to change for optimal integration with WordPress (at least in my experience) are as follows.

$header['force_disa'] = TRUE;
Setting this will ensure that Qdig doesn’t output its own header and footer information.
$dir_nav['enable'] = FALSE;
If you’re embedding different galleries on different pages and intend to use the “src” attribute in the embedded tag, then you probably want to disable directory navigation.
$url_base_path = '/img/';
This must be set to the images directory you intend to put your directories of images in. It should be the path a web browser would use. If you intend to have your images in

http://example.com/random/imgdir

then you should set the variable as

$url_base_path = '/random/imgdir/';

In older versions of Qdig, this variable was called “$abs_url_path”.

$fs_base_path = '/path/to/img/';
This must be set to the images directory you intend to put your directories of images in. It should be the filesystem path used by the webserver. If you are putting your images in (assuming a Linux or similar filesystem)

/home/myuser/web/random/imgdir/

then you would want to set the variable as

$fs_base_path = '/home/myuser/web/random/imgdir/';

In older versions of Qdig, this variable was called “$abs_fs_path”.

$qdig_url = './';
This variable should point to the URL where you are viewing the gallery, which will be the post or page on which you are using the Qdig plugin. (It should not point to the location of Qdig on your server.) Since you are likely to be using the Qdig in various posts/page that will have a variety of different URLs, you can’t normally set this to a static location or your links will be wrong. Using “./” tells Qdig to make all links relative to the current location.
$anchor = '#qdig';
This will anchor all of Qdig’s links to the gallery section of the page. If your blog has a large header, or if there will be a lot of text above the gallery, you might consider using this.
$keep_params = TRUE;
If you are using mod_rewrite for your permalinks, leave this as FALSE. If you are not using mod_rewrite, then you must set this to TRUE. When enabled, it will make sure Qdig generates links that point to the current post using the proper querystring paramaters.

Further Customization for Kubrick

If you’re using the default Kubrick theme, then you might want to make some further customizations to make the integration much more seamless. Fortunately, Ian Cheung has written a guide that details the changes necessary to make that happen. I suspect the information would also be useful to people using other themes.

Check it out: How to Integrate Qdig with Wordpress

The Tag

After enabling the plugin, galleries are created by using a special tag. The tag will be similar to

[qdig path=dirname size=L links=thumbs alt="Gallery"]

All attributes are optional. A minimal tag would be

[qdig]

If the path, size, or links attributes are specified, then they override any settings that Qdig might generated in the URL — provided the overriden value is recognized by the plugin as valid, of course.

For path, any string not containing spaces is valid. This setting will override the Qwd querystring variable, which controls which gallery to display. It should be the valid name of a subdirectory in your images directory (as set in qdig/index.php).

Please note that path should point to the name of a subdirectory in your images directory and should not contain the name of the images directory itself. For example, let’s say you have defined your images directory with these two settings in qdig/index.php:

$abs_url_path = '/wp-content/images/';
$abs_fs_path = '/public_html/wp-content/images/';

Also, let’s say you have two directories you with photos that you want to make into galleries, located at:

/public_html/wp-content/images/alpha/
/public_html/wp-content/images/beta/

Your qdig should have path attributes as follows:

[qdig path=alpha]
[qdig path=beta]

However, the following will not work:

[qdig path=images/alpha]
[qdig path=images/beta]

By including “images/” in the path attribute, you are pointing to /wp-content/images/images/alpha/ instead of /wp-content/images/alpha/.

For size, only ‘S’, ‘M’, ‘L’, ‘XL’, and ‘FS’ are valid. This setting will override the Qis querystring variable, which controls what size image to display.

For links, only ‘thumb’, ‘name’, ‘num’, and ‘none’ are valid. This setting will override the Qiv querystring variable, which controls what kind of links are provided.

For alt, any string not containing spaces OR any string that begins and ends with single or double quotes is valid. For example, these are all valid:

[qdig alt=Example]
[qdig alt='Another Example']
[qdig alt="Yet another example."]

The alt setting controls what text is shown in the archives or in search results instead of the gallery text. The default is “Visit Gallery”.

There is also another tag that you can use that will disable Qdig-WP for the current post or page:

[qdig-disable]

If you use the qdig-disable tag, it must be typed exactly as indicated above. The first instance of [qdig-disable] on your page will be removed and the rest of the [qdig] and [qdig-disable] tags will be untouched. This is useful if you happen to have the plugin installed but also want to talk about the tags without them becoming galleries. :) Most people, however, will probably have no use for this.

Qdig-WP will only allow one gallery per page or post. If you use multiple qdig tags, only the first one will be converted to a gallery. The rest will be left as is. Supporting multiple galleries in a single page is not possible because the multiple instances of Qdig would have to share the same querystring, causing conflicts and undesired behavior.

Demos

Here are a couple of galleries that show Qdig-WP in action.

If you have a gallery that would be nice as a demo, please let me know.

For a list of demo galleries using Qdig as a stand-alone script (not the Qdig-WP plugin), see the demo galleries page on the Qdig website. Depending on your needs, using Qdig as a stand-alone script may be a better option for you.

Credits

I want to make it perfectly clear that the overwhelming majority of this plugin’s functionality lies with Qdig, written by Hagan Fox. All this plugin does is wrap around his code, making it integrate with WordPress a bit easier. I also appreciate that Hagan implemented some requested changes to Qdig that made it easier to integrate into WordPress. Qdig is an excellent gallery script both inside and outside of WordPress.

Thank you to Andreas for pointing out that the documentation regarding $qdig_url was unclear, and also for providing a better fix to the problems that can occur with that variable.

Thank you to Clint for pointing out the validation problem with the permalink link, as well as the fix for it.

Thank you to Ian Cheung for putting together an awesome demo site and integration guide.

Version History and Changelog

0.5 - 2005-09-01 [ source | .tar.gz | .zip ]
Fixed validation error with the permalink link. (Thanks to Clint for this fix.)
0.4 - 2005-03-24 [ source | .tar.gz | .zip ]
Made $post global within the function to allow the plugin to work when mod_rewrite is not being used.
0.3 - 2005-03-11 [ source | .tar.gz | .zip ]
The [qdig-disable] tag was added.
Bug fix: The globals list was statically created, which made the plugin incompatible with future releases of Qdig. The plugin now determines the globals dynamically using Scrape PHP Globals.
0.2 - 2005-03-01 [ source | .tar.gz | .zip ]
The plugin name has been changed from “Qdig Photo Gallery” to “Qdig-WP”.
Bug fix: Size erroneously accepted “O” as an option, but not “FS”. I disabled “O” and added “FS” to match what Qdig expects.
0.1 - 2005-03-01 [ source | .tar.gz | .zip ]
Initial release.