Функция gallery_shortcode() в WordPress: описание и примеры использования

## GALLERY_SHORTCODE() │ WP 2.5.0

Функция для создания вывода шорткода галереи.

Эта функция реализует функциональность шорткода галереи для отображения изображений WordPress в посте.

### ХУКИ ФУНКЦИИ

- post_gallery  
- use_default_gallery_style  
- gallery_style  

### ВОЗВРАТ

Строка. HTML-контент для от��бражения галереи.

### ИСПОЛЬЗОВАНИЕ

```php
gallery_shortcode( $attr );

• $attr(array) (обязательный) — Атрибуты шорткода галереи.

  • order(string) — Порядок отображения изображений в галерее. Принимает значения 'ASC' (по возрастанию) или 'DESC' (по убыванию).
    По умолчанию: 'ASC'

  • orderby(string) — Поле, по которому будет происходить сортировка изображений. Принимает любое допустимое SQL выражение ORDERBY.
    По умолчанию: 'menu_order ID'

  • id(int) — ID поста.

  • itemtag(string) — HTML-тег, используемый для каждого изображения в галерее.
    По умолчанию: 'dl', или 'figure', если тема поддерживает HTML5 галереи

  • icontag(string) — HTML-тег, используемый для иконки каждого изображения.
    По умолчанию: 'dt', или 'div', если тема поддерживает HTML5 галереи

  • captiontag(string) — HTML-тег, используемый для подписи каждого изображения.
    По умолчанию: 'dd', или 'figcaption', если тема поддерживает HTML5 галереи

  • columns(int) — Количество колонок для отображения изображений.
    По умолчанию: 3

  • size(string|int[]) — Размер изображений для отображения. Принимает любое зарегистрированное имя размера изображения или массив значений ширины и высоты в пикселях (в указанном порядке).
    По умолчанию: 'thumbnail'

  • ids(string) — Список ID вложений, разделённых запятыми, для отображения.
    По умолчанию: ''

  • include(string) — Список ID вложений, которые нужно включить.
    По умолчанию: ''

  • exclude(string) — Список ID вложений, которые нужно исключить.
    По умолчанию: ''

  • link(string) — На что будет ссылаться каждое изображение. Принимает значения 'file' (файл) или 'none' (нет).
    По умолчанию: пустая строка (ссылка на страницу вложения)

ПРИМЕРЫ

1. ОТКЛЮЧЕНИЕ СТИЛЕЙ CSS ЗАЯВЛЕНИЙ

С помощью хука use_default_gallery_style мы можем удалить стандартные стили галереи и стилизовать вывод галереи по своему усмотрению в файле стилей темы. Код должен быть добавлен в файл functions.php вашей темы:

// отключить стили галереи
add_filter( 'use_default_gallery_style', '__return_false' );

Обратите внимание, как выглядят стили после отключения:

2. УДАЛЕНИЕ РАМКИ С ИЗОБРАЖЕНИЙ

Вы можете и��пользовать фильтр gallery_style, чтобы изменить добавленные стили. Например, давайте удалим рамку у изображений:

add_filter( 'gallery_style', function( $str ) {
    return str_replace( 'border: 2px solid #cfcfcf;', '', $str );
} );

3. ПОЛНОСТЬЮ ЗАМЕНИТЕ ФУНКЦИЮ GALLERY_SHORTCODE()

С использованием хука post_gallery в файл шаблона или в плагин, мы можем полностью заменить gallery_shortcode() в начале:

/* 
 * Изменение вывода галереи через шорткод
 * Смотрите функцию gallery_shortcode в http://wp-kama.ru/filecode/wp-includes/media.php
 * $output = apply_filters( 'post_gallery', '', $attr );
 */
add_filter('post_gallery', 'my_gallery_output', 10, 2);
function my_gallery_output( $output, $attr ) {
    $ids_arr = explode(',', $attr['ids']);
    $ids_arr = array_map('trim', $ids_arr );

    $pictures = get_posts( array(
        'posts_per_page' => -1,
        'post__in'       => $ids_arr,
        'post_type'      => 'attachment',
        'orderby'        => 'post__in',
    ) );

    if( ! $pictures ) return 'Запрос вернул пустой результат.';

    // Заключение
    $out = '
';

    // Отображение каждой картинки в галерее
    foreach( $pictures as $pic ) {
        $src = $pic->guid;
        $t = esc_attr( $pic->post_title );
        $title = ( $t && false === strpos($src, $t) ) ? $t : '';

        $caption = ( $pic->post_excerpt != '' ? $pic->post_excerpt : $title );

        $out .= '
        

            '. 
            ( $caption ? "$caption" : '' ) .
        '
';
    }

    $out .= '
';

    return $out;
}

ИСТОРИЯ ИЗМЕНЕНИЙ

• С 2.5.0 — Введена функция.
• С 2.8.0 — Добавлен параметр $attr для установки вывода шорткода. Новый атрибут включён: size, itemtag, icontag, captiontag и columns.
• С 3.5.0 — Использование get_post() вместо глобальной переменной $post.
• С 3.6.0 — Добавлена проверка для тегов, используемых в шорткоде галереи.

СВЯЗАННЫЕ ФУНКЦИИ

• get_post_galleries()
• get_post_gallery()
• add_shortcode()
• do_shortcode()