How to Add Custom Links to Gallery Images in WordPress

6 hours ago, WordPress Plugin, Views

Understanding the Need for Custom Links in WordPress Galleries

WordPress’s built-in gallery feature is a simple and effective way to display images. However, it lacks the crucial functionality of allowing individual gallery images to link to different URLs. By default, images in a gallery either link to the attachment page (a separate page for the image with comments and descriptions) or expand into a lightbox (a full-screen view). This limited linking capability can be a significant problem for many users who need more control over where visitors are directed when clicking on gallery images.

For example, an e-commerce website might want gallery images of products to link directly to the product pages. A portfolio website might want gallery images to link to the corresponding project pages. A travel blog could use custom links to direct readers to specific locations on a map or booking pages. Without custom links, these users are forced to rely on workarounds or plugins, which adds complexity and potential performance overhead to their sites. Adding custom link functionality expands the potential uses for image galleries, enabling more dynamic and engaging content.

Methods for Adding Custom Links to Gallery Images

Several methods can be used to add custom links to gallery images in WordPress. These range from manual coding approaches to using plugins designed specifically for this purpose. Each method has its advantages and disadvantages, depending on the user’s technical skill, desired level of customization, and the complexity of their website.

Manual Coding with the `post_gallery` Filter

This approach involves using WordPress’s `post_gallery` filter to modify the HTML output of the default gallery shortcode. This method offers the most control over the final output but requires some familiarity with PHP and HTML.

Understanding the `post_gallery` Filter: The `post_gallery` filter allows developers to intercept the default gallery output and modify it before it’s displayed on the page. This filter passes several arguments, including the gallery attributes (e.g., image IDs, number of columns) and the order of the images.
Writing the Code: The following code snippet demonstrates how to add custom links to gallery images using the `post_gallery` filter.
“`php
function custom_gallery_links( $output, $attr ) {
global $post;

static $instance = 0;
$instance++;

$atts = shortcode_atts( array(
‘order’ => ‘ASC’,
‘orderby’ => ‘menu_order ID’,
‘id’ => $post->ID,
‘columns’ => 3,
‘size’ => ‘thumbnail’,
‘include’ => ”,
‘exclude’ => ”
), $attr, ‘gallery’ );

$id = intval( $atts[‘id’] );

if ( ! empty( $atts[‘include’] ) ) {
$_attachments = get_posts( array( ‘include’ => $atts[‘include’], ‘post_status’ => ‘inherit’, ‘post_type’ => ‘attachment’, ‘post_mime_type’ => ‘image’, ‘orderby’ => $atts[‘orderby’], ‘order’ => $atts[‘order’] ) );

$attachments = array();
foreach ( $_attachments as $key => $val ) {
$attachments[$val->ID] = $_attachments[$key];
}
} elseif ( ! empty( $atts[‘exclude’] ) ) {
$attachments = get_children( array( ‘post_parent’ => $id, ‘exclude’ => $atts[‘exclude’], ‘post_status’ => ‘inherit’, ‘post_type’ => ‘attachment’, ‘post_mime_type’ => ‘image’, ‘orderby’ => $atts[‘orderby’], ‘order’ => $atts[‘order’] ) );
} else {
$attachments = get_children( array( ‘post_parent’ => $id, ‘post_status’ => ‘inherit’, ‘post_type’ => ‘attachment’, ‘post_mime_type’ => ‘image’, ‘orderby’ => $atts[‘orderby’], ‘order’ => $atts[‘order’] ) );
}

if ( empty( $attachments ) ) {
return ”;
}

if ( is_feed() ) {
$output = “n”;
foreach ( $attachments as $att_id => $attachment )
$output .= wp_get_attachment_link( $att_id, $atts[‘size’], true ) . “n”;
return $output;
}

$columns = intval( $atts[‘columns’] );
$selector = “gallery-{$instance}”;

$output = “

“;

$i = 0;
foreach ( $attachments as $id => $attachment ) {
// Get the custom link for the attachment
$custom_link = get_post_meta( $id, ‘_custom_link_url’, true );
if ( empty( $custom_link ) ) {
$custom_link = wp_get_attachment_url( $id ); // or attachment page, or leave empty for no link
}

$image_output = wp_get_attachment_image( $id, $atts[‘size’], false, array( ‘class’ => ‘attachment-‘ . $atts[‘size’] ) );

$output .= “

“;
$output .= ”

$image_output
“;
$output .= “

“;

if ( ++$i % $columns == 0 )
$output .= ‘
‘;
}

$output .= ”

n”;

return $output;
}
add_filter( ‘post_gallery’, ‘custom_gallery_links’, 10, 2 );
“`
Explanation of the Code:
- The code defines a function `custom_gallery_links` that takes the gallery output and attributes as arguments.
- It retrieves the gallery attributes, such as image IDs, columns, and size.
- It fetches the attachments (images) associated with the gallery.
- For each attachment (image), it retrieves the custom link URL from the post meta using `get_post_meta`. The meta key `_custom_link_url` is used to store the custom link.
- If a custom link is found, it uses it in the `` tag. If no custom link is found, it defaults to the attachment URL. You can modify this to link to the attachment page (`get_permalink( $id )`) or to have no link at all.
- It constructs the HTML output for each image, including the `` tag with the custom link and the image itself.

Adding the Custom Field: The code relies on a custom field named `_custom_link_url` to store the custom link for each image. You need to add a metabox to the attachment edit screen to allow users to enter the custom link. This can be done with a plugin like Advanced Custom Fields (ACF) or by manually adding a metabox.

“`php
function add_custom_link_metabox() {
add_meta_box(
‘custom_link_metabox’, // ID of the meta box
‘Custom Link URL’, // Title of the meta box
‘custom_link_metabox_callback’, // Callback function to display the meta box
‘attachment’, // Post type to display the meta box on (attachment)
‘normal’, // Context (normal, advanced, side)
‘default’ // Priority (high, core, default, low)
);
}
add_action( ‘add_meta_boxes_attachment’, ‘add_custom_link_metabox’ );

function custom_link_metabox_callback( $post ) {
// Add a nonce field so we can check for unauthorized access later.
wp_nonce_field( ‘custom_link_nonce’, ‘custom_link_nonce’ );

// Get the value of the custom field if it exists.
$custom_link_url = get_post_meta( $post->ID, ‘_custom_link_url’, true );

// Output the HTML for the meta box.
echo ‘Custom Link URL:
‘;
echo ‘‘;
}

function save_custom_link_meta( $post_id ) {
// Check if our nonce is set.
if ( ! isset( $_POST[‘custom_link_nonce’] ) ) {
return;
}

// Verify that the nonce is valid.
if ( ! wp_verify_nonce( $_POST[‘custom_link_nonce’], ‘custom_link_nonce’ ) ) {
return;
}

// If this is an autosave, our form has not been submitted, so we don’t want to do anything.
if ( defined( ‘DOING_AUTOSAVE’ ) && DOING_AUTOSAVE ) {
return;
}

// Check the user’s permissions.
if ( ! current_user_can( ‘edit_post’, $post_id ) ) {
return;
}

// Sanitize user input.
$custom_link_url = sanitize_text_field( $_POST[‘custom_link_url’] );

// Update the meta field in the database.
update_post_meta( $post_id, ‘_custom_link_url’, $custom_link_url );
}
add_action( ‘save_post_attachment’, ‘save_custom_link_meta’ );
“`

This code creates a metabox on the attachment edit screen where you can enter the custom URL.

Adding the Code to WordPress: The code needs to be added to your theme’s `functions.php` file or a custom plugin. It’s recommended to use a child theme to avoid losing the changes when the theme is updated.

Using Plugins

Several plugins are available that simplify the process of adding custom links to gallery images. These plugins typically provide a user-friendly interface for adding links directly within the WordPress media library or gallery settings.

Benefits of Using Plugins:
- Ease of Use: Plugins generally offer a more intuitive interface than manual coding, making it easier for non-developers to add custom links.
- Reduced Risk of Errors: Plugins handle the complexities of modifying the gallery output, reducing the risk of introducing errors into your website’s code.
- Regular Updates and Support: Reputable plugins are typically maintained and updated regularly, ensuring compatibility with the latest versions of WordPress and providing ongoing support.
Popular Plugins:
- FooGallery: A popular gallery plugin that offers various features, including custom links, different layouts, and responsive design.
- NextGEN Gallery: A widely used gallery plugin known for its advanced features and options, including custom link support.
- Meow Gallery: A lightweight gallery plugin with a focus on performance and ease of use, also offering custom link functionality.
- Custom Gallery Links A plugin dedicated soley to adding custom gallery links to your default wordpress galleries.
Example Usage with FooGallery: Many of these plugins work similarly. With FooGallery, after installing and activating the plugin:
- Create a new FooGallery or edit an existing one.
- Add images to the gallery.
- For each image, you’ll find a field where you can enter the custom link URL.
- Save the gallery, and the images will now link to the specified URLs.

Using Advanced Custom Fields (ACF)

Advanced Custom Fields (ACF) is a powerful plugin that allows you to add custom fields to various parts of your WordPress site, including attachments. This method provides a flexible and customizable way to manage custom links for gallery images.

Installing and Configuring ACF: Install and activate the Advanced Custom Fields (ACF) plugin. The free version is sufficient for adding custom links.

Creating a Custom Field Group:

Go to “Custom Fields” in the WordPress admin menu and click “Add New.”
Give the field group a name (e.g., “Gallery Image Links”).
Click “Add Field” to create a new field.
Set the “Field Type” to “URL.”
Give the field a “Field Label” (e.g., “Custom Link URL”) and a “Field Name” (e.g., `custom_link_url`). The Field Name is important for accessing the field in your code.
Under “Location,” choose “Attachment” to display the field on the attachment edit screen.
Save the field group.

Modifying the Gallery Output: You’ll need to modify the gallery output using the `post_gallery` filter, similar to the manual coding method described earlier. However, instead of looking for a meta key directly, you’ll use ACF’s `get_field()` function.
“`php
function custom_gallery_links_acf( $output, $attr ) {
global $post;

static $instance = 0;
$instance++;

$atts = shortcode_atts( array(
‘order’ => ‘ASC’,
‘orderby’ => ‘menu_order ID’,
‘id’ => $post->ID,
‘columns’ => 3,
‘size’ => ‘thumbnail’,
‘include’ => ”,
‘exclude’ => ”
), $attr, ‘gallery’ );

$id = intval( $atts[‘id’] );

if ( ! empty( $atts[‘include’] ) ) {
$_attachments = get_posts( array( ‘include’ => $atts[‘include’], ‘post_status’ => ‘inherit’, ‘post_type’ => ‘attachment’, ‘post_mime_type’ => ‘image’, ‘orderby’ => $atts[‘orderby’], ‘order’ => $atts[‘order’] ) );

$attachments = array();
foreach ( $_attachments as $key => $val ) {
$attachments[$val->ID] = $_attachments[$key];
}
} elseif ( ! empty( $atts[‘exclude’] ) ) {
$attachments = get_children( array( ‘post_parent’ => $id, ‘exclude’ => $atts[‘exclude’], ‘post_status’ => ‘inherit’, ‘post_type’ => ‘attachment’, ‘post_mime_type’ => ‘image’, ‘orderby’ => $atts[‘orderby’], ‘order’ => $atts[‘order’] ) );
} else {
$attachments = get_children( array( ‘post_parent’ => $id, ‘post_status’ => ‘inherit’, ‘post_type’ => ‘attachment’, ‘post_mime_type’ => ‘image’, ‘orderby’ => $atts[‘orderby’], ‘order’ => $atts[‘order’] ) );
}

if ( empty( $attachments ) ) {
return ”;
}

if ( is_feed() ) {
$output = “n”;
foreach ( $attachments as $att_id => $attachment )
$output .= wp_get_attachment_link( $att_id, $atts[‘size’], true ) . “n”;
return $output;
}

$columns = intval( $atts[‘columns’] );
$selector = “gallery-{$instance}”;

$output = “

“;

$i = 0;
foreach ( $attachments as $id => $attachment ) {
// Get the custom link for the attachment using ACF
$custom_link = get_field( ‘custom_link_url’, $id ); // Replace ‘custom_link_url’ with your ACF field name
if ( empty( $custom_link ) ) {
$custom_link = wp_get_attachment_url( $id ); // or attachment page, or leave empty for no link
}

$image_output = wp_get_attachment_image( $id, $atts[‘size’], false, array( ‘class’ => ‘attachment-‘ . $atts[‘size’] ) );

$output .= “

“;
$output .= ”

$image_output
“;
$output .= “

“;

if ( ++$i % $columns == 0 )
$output .= ‘
‘;
}

$output .= ”

n”;

return $output;
}
add_filter( ‘post_gallery’, ‘custom_gallery_links_acf’, 10, 2 );
“`
Explanation of the Changes: The key difference is the line `$custom_link = get_field( ‘custom_link_url’, $id );`. This uses the `get_field()` function from ACF to retrieve the value of the custom field named `custom_link_url` for the current attachment `$id`. The rest of the code remains largely the same, handling the gallery attributes and constructing the HTML output.
Adding the Code to WordPress: Add this code to your theme’s `functions.php` file or a custom plugin.

Considerations for Implementation

Regardless of the chosen method, several considerations should be taken into account to ensure a smooth and effective implementation.

Theme Compatibility: Ensure that the chosen method is compatible with your WordPress theme. Some themes may have custom gallery implementations that could conflict with the code or plugin you’re using. Test thoroughly to avoid any unexpected issues.
Responsive Design: Ensure that the gallery with custom links remains responsive and displays correctly on different devices and screen sizes. Pay attention to how the links affect the layout and appearance of the gallery on mobile devices.
Performance: Adding custom code or using plugins can potentially impact website performance. Choose lightweight plugins and optimize your code to minimize any performance overhead. Test your website’s loading speed after implementing the changes.
User Experience: Consider the user experience when implementing custom links. Make sure the links are clear and intuitive, and that users understand where they will be directed when clicking on an image. Avoid using overly aggressive or confusing link behavior.
Accessibility: Ensure that the gallery and custom links are accessible to users with disabilities. Use appropriate HTML attributes (e.g., `alt` text for images, descriptive link text) to improve accessibility.
Security: When using custom fields to store links, sanitize and validate the input to prevent potential security vulnerabilities. Use WordPress’s built-in sanitization functions (e.g., `esc_url`, `sanitize_text_field`) to protect against malicious code injection.

#ezw_tco-2 .ez-toc-widget-container ul.ez-toc-list li.active::before { background-color: #ededed; } aa