Function reference: su_get_gallery_slides()

su_get_gallery_slides( array $args )

Creates an array of slides for a gallery (image gallery, slider/carousel, etc.), based on a simple and readable query string. This function is being used by the Image Carousel shortcode and can be utilized in custom shortcodes, created in the Shortcode Creator add-on.

Table of contents

1. Parameters
2. Settings
   1. source
   2. link
   3. limit
   4. random
   5. prefer_caption
3. Return
4. Source
5. Examples
   1. Getting the slides data
   2. Displaying the images

Parameters

The function accepts a single argument, which must contain an array with settings.

$atts
(array)(Required) An array with settings

Settings

source

The query string to be used to query posts from the DB.

Possible values:

• media: 1, 2, 3 (where 1, 2, 3 are attachment IDs)
• media: recent
• posts: 1, 2, 3 (where 1, 2, 3 are post IDs)
• posts: recent
• taxonomy: books/1, 2, 3 (where books is the taxonomy slug, and 1, 2, 3 are term IDs)

link

This setting determines which link will be created for a slide.

Possible values are:

• none – no link needed, default
• image – the original full-size image URL
• custom – custom links can be set by editing an attachment, learn more
• attachment – attachment page URL
• post – the original post permalink

limit

This setting sets max number of posts that will be queried. It can be used with the following source values: posts: recent, media: recent, and taxonomy: books/1, 2, 3.

random

Set the value to yes to shuffle the slides order. Possible values: yes and no.

prefer_caption

Set the value to yes to use image captions instead of image titles as a slide caption. Possible values: yes and no.

Return

The function returns an array with slides data on success, false otherwise.

Example:

[
	[
		'post_id': 1,
		'attachment_id': 1,
		'caption': 'Image caption',
		'link': 'https://example.com/post-1/',
	],
]

Source

The most actual version of the source code can be found in the includes/functions-galleries.php file.

Examples

Getting the slides data

Media Library

The code below will create slides data based on the Media Library attachments with IDs 1, 2, and 3.

$slides = su_get_gallery_slides( [ 'source' => 'media: 1, 2, 3' ] );

The code below will create slides data out of the 10 last uploaded attachments.

$slides = su_get_gallery_slides(
	[
		'source' => 'media: recent',
		'limit' => 10,
	]
);

Posts

The code below will get posts with IDs 2 and 3, and create slides data based on their featured images:

$slides = su_get_gallery_slides( [ 'source' => 'posts: 2, 3' ] );

The code below will get 10 latest posts, and create slides data based on their featured images:

$slides = su_get_gallery_slides(
	[
		'source' => 'posts: recent',
		'limit' => 10,
	]
);

Taxonomy terms

The code below will get 2 latest posts from the category with ID 1 and generate slides data based on their featured images:

$slides = su_get_gallery_slides(
	[
		'source' => 'taxonomy: category/1',
		'limit' => 2,
	]
);

The code below will get 2 latest posts from the terms with IDs 2 and 3 in the books taxonomy, and generate slides data from their featured images:

$slides = su_get_gallery_slides(
	[
		'source' => 'taxonomy: books/2,3',
		'limit' => 2,
	]
);

Displaying the images

// Get the slides data
$slides = su_get_gallery_slides( [ ... ] );

// Loop the received slides
foreach ( $slides as $slide ) {

	// Display an <img> tag by the slide's attachment_id
	echo wp_get_attachment_image(
		$slide['attachment_id'],
		'post-thumbnail'
	);

	// Display the slide caption
	echo $slide['caption'];

	// Display the slide link
	echo $slide['link'];

}