Dynamic Content Gallery Configuration Guide

Installation

This Configuration Guide assumes that you have installed the plugin and activated it in Dashboard>Plugins. Full installation instructions are available here.

If you have upgraded from an older version

You probably don’t need to read the rest of this Guide! Your existing Settings should have been preserved during the upgrade process, therefore you can continue to use the plugin as before. Of course, if you want to take advantage of some of the new features, or get a better understanding of how the key configuration Settings work – read on!

Answer 3 key questions

Before you start the configuration, make a mental note of your answers to the following questions. Your answers to these help determine the choices you will make when configuring the plugin’s Settings page:

1. Which posts or pages do I want to display in the gallery?
2. How do I like to store/organise my images on my server?
3. Where do I want the gallery to appear on my site?

Keep in mind your answers to these questions when working through the following sections.

This section is all about selecting the appropriate Gallery Method.

Screenshot: Gallery Method Settings

The plugin provides 3 Gallery Methods to populate the gallery, and the following scenarios will help you determine which of these 3 Methods is the best for you.

I want to feature my latest X number of posts from my “featured” or “blog” or some other special category

Choose the One Category Gallery Method in the Gallery Method Settings box, then select the category and the number of posts to display in the One Category settings.

I want to feature Pages rather than Posts

Choose the Pages Gallery Method and select the Pages to be displayed in the Pages settings.

I want to show posts from more than one category

Choose the Multi-Option Gallery Method and select the categories and posts to display in the Multi-Option settings.

I want to show Posts and Pages

Sorry, you can’t mix Posts and Pages in the gallery.

The plugin’s Image File Management settings determine the form of the image URL that you must enter in the Image URL field in the Write Post/Page DCG Metabox. This section should help you select the Image File Management settings which is most appropriate to your workflow and the organisation of images on your server.

Click image to see full-size version

The Image File Management settings box in the plugin’s Settings page gives you two options:

• Full URL
• Partial URL

together with an input field URL to Custom Field images folder which must be completed if you select the Partial URL option.

Generally speaking, my advice to new users of this plugin is to select Full URL, as it is easy to use in conjunction with the WordPress Media Uploader, which makes the process of entering the Image URL in the DCG Metabox a whole lot quicker. The Partial URL option is primarily for those who are upgrading from an earlier version of the plugin (because that’s how the earlier DCG versions were designed), or for those who organise images on their server in a non-standard (in WP terms) way.

The most important thing to understand about the Image File Management setting is that it determines the form of the URL you enter in the Write Post/Page DCG Metabox in your Posts or Pages. So, let’s take a closer look at what Full URL and Partial URL actually mean…

Understanding the difference between FULL and PARTIAL URL

Here are some examples to explain the difference between these two options.

Full URL

Here’s the actual URL for our example image:

Enter this in the DCG Metabox Image URL field:

http://yourdomain.com/wp-content/uploads/2009/09/myimage.jpg

Enter this in the URL to Custom Field images folder input box:

Leave it blank. This setting is ignored when Full URL is selected.

That’s why this Image File Management setting is called “Full URL” – because when you select this DCG Settings option, you must use the full image URL in the the DCG Metabox Image URL field.

Partial URL

Here’s the actual URL for our example image:

Enter this in the DCG Metabox Image URL field:

top-level-folder/sub-folder/sub-sub-folder/myimage.jpg

Enter this in the URL to Custom Field images folder input box:

http://yourdomain.com/

Alternatively, you could enter it like this:

Enter this in the DCG Metabox Image URL field:

sub-folder/sub-sub-folder/myimage.jpg

Enter this in the URL to Custom Field images folder input box:

http://yourdomain.com/top-level-folder/

Or, you could enter it like this:

Enter this in the DCG Metabox Image URL field:

sub-sub-folder/myimage.jpg

Enter this in the URL to Custom Field images folder input box:

http://yourdomain.com/top-level-folder/sub-folder/

As you can see when using Partial URL, you split the actual image URL between the URL to Custom Field images folder input box and the DCG Metabox Image URL field. Obviously, this means that the part of the URL you enter in the URL to Custom Field images folder input box must be common to ALL your gallery images. You then only need to enter the relative URL to the image itself in the DCG Metabox Image URL field, relative to the URL entered in the URL to Custom Field images folder input box.

An advantage of choosing Full URL is the ease with which the WordPress Media Uploader can be used to get the image URL for DCG Metabox Image URL field. Here’s how:

Screenshot: Using the Media Uploader to get the Full URL to the image

When you add a Post (or Page) and you want to feature it in the gallery, use the Media Uploader to load your image.

• With the Media Uploader open, browse to your chosen image on your local computer and upload it.
• When the Media Uploader has finished “crunching”, simply select and copy the “File URL” (highlighted in the screenshot), close the Uploader (without inserting the image into the Post – unless you want to, of course), and paste the File URL into the DCG Metabox Image URL field.

Simple, eh? You should notice that the URL you have pasted is the “full” URL to the image, ie it includes the http:// code and your domain name. Therefore, you can see how easy it is to use the Full URL Image File Management setting – no messing about, just a simple copy and paste. Job done.

If you don’t use the Media Uploader

If you prefer to FTP your images rather than use the Media Uploader, the choice of Full URL or Partial URL is entirely up to you. All you need to remember is that whichever setting you choose determines what you enter in the DCG Metabox Image URL field. If you select Partial URL you must also enter a URL to the top-level folder which contains your sub-folders and images in the Image File Management settings. (Not needed if you selected Full URL).

This section is all about placing this code – which is needed for the plugin to work – in the appropriate theme template file:

The choice of template file depends on (a) where you want to show the gallery on your site and (b) the structure of your theme templates. Firstly, make sure you have a basic understanding of the WordPress Template Hierarchy so that you know which template file is used by WordPress to display the various types of page (home page, category archive, single posts, etc).

How to display the DCG on the home page

Generally speaking, most people will want to display the DCG on their home page. In “magazine style” themes, the home page is often generated by home.php and, if this is the case, the answer is simple – place the code in an appropriate place in home.php.

For those themes that do not use a home.php template, in all likelihood your homepage is generated by index.php. However, if index.php is also used to display other pages on your site (refer to the Template Hierarchy to see in which circumstances it is used for non-homepage pages), you will need to find a way to restrict the DCG so that it only appears when the user is visiting your home page. Luckily, there are a couple of techniques we can use to deal with this…

Create a home.php

This is the simplest way. Make a copy of your existing index.php and rename the copy home.php. Add the DCG code to your new home.php file like this:

Use Conditional Tags in index.php

Alternatively, if for some reason you don’t want to make a home.php, add the DCG code to index.php and use Conditional Tags to display the DCG only when the home page is being viewed, like so:

But I’m using a Static Front Page!

If you have configured your Dashboard>Settings>Reading options to use a Static Front Page for your home page, use Conditional Tags in your page.php as follows:

But I’m using a Static Front Page based on a Page Template!

If your Page Template is only used for this Static Front Page, insert the DCG code in the appropriate place in your Static Front page’s Page Template file.

If this Page Template is used for your Static Front Page AND some other pages on your site, and you only want to show the DCG on your Front Page, add the DCG code to your Page Template using Conditional Tags like so:

I want to display the DCG on a specific Page (not the home page)

Assuming the Page concerned uses the default page template page.php, you will have to use Conditional Tags to restrict the DCG to the specific Page, using the Page name, the Page slug or the Page ID, like so:

If your specific Page uses a Page Template, ie not the default page.php, you will need to do one of the following:

The Page Template is only used for this specific Page

The Page Template is used for more than one Page

I want to display the DCG on my archive pages

Archive pages include your category archives, tag archives, monthly archives, author archives etc. Refer to the Template Hierarchy to see which templates your theme uses for displaying the various types of archives. This isn’t an exhaustive list, but the following are typically found in most themes:

• archive.php
• category.php
• tag.php
• date.php
• etc, etc…

If you want to restrict the DCG to display only when certain posts are displayed on your archive pages, you will have to use the DCG code within suitable Conditional Tags.

The purpose of this Setting is to only load the scripts into your web page if the gallery is displayed on that web page. This has performance benefits, as it stop the scripts being loaded unnecessarily on other pages on your site which don’t display the gallery.

Settings: Restrict Scripts loading

The correct option to choose depends on the template file that contains the DCG code. If you have read through the previous section of this Guide, you should now know which template file you are using to display the DCG, and therefore can configure the Restrict Script loading Settings accordingly.

The gallery is only displayed on the home page

Choose Home page in the Restrict script loading Setting. This is probably going to be the most common usage and is the plugin’s default setting.

Use this Setting if you use home.php, or index.php with Conditional tags as described in the previous section of this Guide.

This Setting is also the correct one to use if you use a Static Front Page (regardless of whether the Static Front Page is generated by the default template or a Page Template).

The gallery is displayed on a Page which uses a Page Template

In this case, we’re talking about a Page Template which is NOT used to display a Static Front Page. Choose Specific Page Template, and enter the filename of the relevant Page Template in the box in the Restrict script loading Settings. For example, if you have placed the DCG code in a Page Template called page_blog.php, enter page_blog.php in the input box in the Restrict Scripts loading Settings.

None of the above

Choose Other in the Restrict script loading Settings.

A key feature of this plugin is its automatic use of default images in the event you have forgotten to enter an Image URL in the Write Post/Page DCG Metabox for one or more of your Posts/Pages. This is a useful fallback because missing images can prevent the gallery from loading properly. Therefore, it is recommended, though not compulsory, that you set up default images as described below.

The naming and location of these images on your server is important, and depends on the Gallery Method Setting you are using.

Default images – One Category and Multi Option Gallery Methods

These Gallery Methods use Posts and Categories to populate the gallery. In the event that a DCG Metabox Image URL is missing from a Post, the plugin will display a default image determined by the Category ID for that Post.

The plugin’s code assumes that:

• Default images are named xx.jpg, where xx is the Category ID.
• ALL default images are stored in one folder on your server.

Follow this tutorial:

• Create a default image for each of the Categories specified in the Multi Option Settings, or the Category specified in the One Category Settings, depending on which Gallery Method you have selected.
• The default image for each Category must be named as follows: XX.jpg, where XX is the Category ID. For example, the default image that will be displayed for a Post in Category ID=8 must be named 8.jpg.
• Once you have created your default images, one for each category, and named them as per these instructions, create a folder in your wp-content/uploads/ directory called, for example, dfcgimages.
• Upload ALL the default images to this wp-content/uploads/dfcgimages folder.
• Go to the DCG Settings Page and locate the Multi Option Settings or One Category Settings (depending on which Gallery Method you are using), and enter the full URL to your default images folder in the URL to default “Category” images folder input box. In this example it will be: http://youdomain.com/wp-content/uploads/dfcgimages/

Default images – Pages Gallery Method

These Gallery Method uses Pages to populate the gallery. In the event that the DCG Metabox Image URL is missing from a Page, the plugin will display a default image instead.

In contrast to the naming and location rules for the default images used by the Multi Option and One Category Gallery Methods, the Pages Gallery Method only requires ONE default image, named as you choose – and you have complete freedom to store it anywhere on your server.

• Create a default image (it can be any recognised MIME-type, eg JPEG, GIF, PNG etc), and name it as you wish.
• Upload the default image to somewhere on your server (within the wp-content folder is a good idea).
• Go to the DCG Settings Page and locate the Pages Settings, and enter the full URL to your default image in the Specify a default image input box. For example: http://www.yourdomain.com/somefolder/anotherfolder/mydefaultimage.jpg

By default, each image in the gallery is automatically linked to its Post or Page. However, if you wish to link a gallery image to a different resource, eg another page on your site or an external site, enter the link in the External Link field in the DCG Metabox in the relevant Posts or Pages.

Since version 3.2 you can now specifiy the order of gallery images when using the Pages Method of populating the gallery.

Open up the relevant Page (Write Page screen) and enter a number in the Sort Order field in the DCG Metabox. This works in much the same way as WordPress lets you change the order of Pages in menus.

The plugin’s detailed documentation can be found on the Dynamic Content Gallery Documentation page.

For troubleshooting and other tips, refer to the Dynamic Content Gallery v3 FAQ.

For help understanding the plugin’s error messages, refer to the Dynamic Content Gallery Error Messages.

Users of earlier versions of the plugin should consult this FAQ.

If you have read the above resources and still can’t resolve your issue, post a question in the Support Forum.