Support»Embedding Qdig Galleries

Embedding Qdig Galleries

Qdig is designed so you can embed galleries within other web pages.

This page has simple, standard, and advanced installation examples that use PHP's include() function to embed galleries. Qdig galleries have been successfully integrated into sites using frames and other methods as well.

Related Qdig Features

The features that are most important for embedding galleries are

  • HTML header and footer suppression,
  • Qdig-specific CSS style rules,
  • Chroot Directory capability, and
  • external settings capability.

See also: The separate Joomla page and the separately maintained Qdig-WP plugin for WordPress.

HTML Header and Footer Suppression

When you use PHP's include() function to embed a gallery, the HTML header and footer will usually be suppressed automatically. (If not, there's a setting to force them to be suppressed.)

Without the stand-alone gallery's HTML header the gallery will take on the look and feel of your site. This is because most of Qdig's CSS style attributes come from rules in the <style> tag of the HTML header.

Qdig-Specific CSS Style Rules

The demo pages linked here are not very beautiful. Let's just say they're more colorful than they need to be. No doubt your web page will look much better.

To help with that, here are some example CSS rules you can use to adjust the look and feel of your embedded Qdig galleries:

/* General */
#qdig { font-family:Arial, Helvetica, Geneva, sans-serif; }
.qdig-grayout { color:#cccccc; }
/* Links */
#qdig a { color:navy; font-weight:bold; text-decoration: none; }
#qdig a:visited { color:blue; font-weight:bold; text-decoration:none; }
#qdig a:hover { text-decoration:underline; }
/* Images */
img.qdig-image { background-color:#eeeeee; border:1px solid #cccccc; }
img.qdig-thumb { background-color:#eeeeee; border:1px solid #cccccc; }
img#qdig-thumb-current { border:1px solid #f9f99f; }
/* Captions */
div.qdig-caption { font-family:Verdana, Arial, Helvetica, sans-serif; }

These Qdig-specific rules will not affect any other part of your site. They can either be slipped into your HTML header using a <style> tag. (Use your browser to view the source of a stand-alone Qdig gallery page for an example), or you can insert them into your external CSS stylesheet file.

Chroot Directory

You can use the Chroot Directory setting to make any gallery directory the topmost directory of the gallery tree (that is, change the root directory). This is important, otherwise the top directory is the working directory of your other script.

External Qdig Settings

New in Qdig 1.2.6, you can pass settings to Qdig by including a qdig_settings() function in your PHP script.

The Chroot Directory feature combines well with the qdig_settings() function. Together they allow you to make one copy of Qdig and one gallery tree appear as many different individual galleries or gallery trees. The same set of images can be presented in a variety of ways on different pages of your site.


Simple Installation (No Captions or Converted Images

For this read-only gallery example we'll assume your directory structure looks like this: /var/www/html/ `-- gallery |-- Cats `-- Dogs

Your web page is in /var/www/html/ and your photos are in subdirectories of the /var/www/html/gallery/ directory.

Easy enough.

Now install Qdig.

  1. Unpack the Qdig distribution archive.
  2. Rename index.php to qdig.php.
  3. Edit qdig.php and set $chroot_dir. Example:
    $chroot_dir = 'gallery/';
  4. Copy qdig.php to your site's directory (/var/www/html/ in this example)

Now include Qdig into your PHP web page by inserting this line:

  <?php include('qdig.php'); ?>

That's it. You can visit your gallery or your web page and surf through your photos.

Standard Installation (With Captions and/or Converted Images)

This example includes steps to create the writable tree and set up admin.php for editing captions.

Starting with the same directory structure,

  1. Unpack the Qdig distribution archive.
  2. Rename index.php to qdig.php.
  3. Edit qdig.php and set $chroot_dir. Examples:
    $chroot_dir = 'gallery/';
    $chroot_dir = 'gallery/Cats/';
    $chroot_dir = 'gallery/Dogs/';
  4. Edit admin.php and put in a username / password pair.
  5. Copy qdig.php, admin.php, and qdig-admin.ico to /var/www/html/
  6. Set up the writable tree:
    Create a qdig-files/ directory to hold the writable tree.
    Set "2777" permissions on the directory.
    Visit qdig.php to initialize the writable tree.
    Set "755" permissions on the writable tree.

That's it. You can visit your gallery directly or your web page withe the embedded gallery. Of course you'll want to add some style to your pages with Qdig-specific lines in your CSS stylesheet file.

The directory structure for our example looks like this:

|-- gallery
|   |-- Cats
|   `-- Dogs
`-- qdig-files
    |-- captions
    |   `-- gallery
    |       |-- Cats
    |       `-- Dogs
    `-- converted-images
        `-- gallery
            |-- Cats
            `-- Dogs

Advanced Installation

Starting with Qdig 1.2.6 we can embed Qdig settings into the web page's script. This makes upgrading a matter of dropping a new copy of Qdig into the directory (assuming no settings' names change, which they could.)

Instead of just adding the <?php include('qdig.php'); ?> line in the script, we'll add a function that will include any non-default settings we want to use. Example:

function qdig_settings($version)
global $site_lnk_title, $site_lnk_url, $chroot_dir, $qdig_files,
    $cnvrt_thmb, $header, $diag_messages, $copyright,

    $site_lnk_title = 'Embedding Qdig Page';
    $site_lnk_url   =
    $chroot_dir            = "gallery/";
    $qdig_files            = 'qdig-files';
    //$header['force_disa'] = TRUE;
    $sidebar_table_bg_clr  = 'blue';
    $cnvrt_thmb['size']    = 45;
    $cnvrt_thmb['prefix']  = "thm{$cnvrt_thmb['size']}_";
    $copyright['txt']      =
        'Images copyright &copy; 2004, 2005 Hagan Fox.
        All rights reserved.';


Note that any setting you use must be declared global or it won't be passed to the Qdig script.

That's it. You can visit your web page with the embedded gallery. Again, be sure to add some style to your pages using some Qdig-specific lines in your CSS stylesheet file so your page doesn't look as, well, "colorful" a these demos.

The Qdig script used for all of these examples is a single, unmodified copy (See?). All of the Qdig gallery links are to scripts that use the qdig_settings() function and include the unmodified qdig.php script. Replacing the one copy of the script will update them all.

Another Advanced Method

This example also takes advantage of passing settings to Qdig using the qdig_settings() function. Visit the web page with the embedded gallery.

The gallery for this example uses a different qdig-files/ directory than the others. For some people this method will be easier to understand because there is only Qdig (gallery/index.php) and the web page's script, with no third wrapper script.

Comments? Suggestions? Use the Qdig Open Discussion forum. Use the Qdig Help forum for support.