Функции и шорткоды для показа рекламы в плагине AdContent

Функции и шорткоды

Для взаимодействия с плагином предусмотрены следующие функции и шорткоды.

• Шорткод [adcontent].
• HTML-шорткод <div class="adcontent-ajax"></div>.
• PHP-функции get_ads() и the_ads().
• JavaScript функция adcontent_ajax().

В плагине также реализован генератор шорткодов, который позволяет в считанные секунды получить код для вставки объявлений на сайт, используя удобный интерфейс.

Вы можете самостоятельно модифицировать полученный код. используя предоставленную ниже информацию.

Список параметров

• id (string|array) – идентификаторы рекламных блоков через запятую или в виде массива.
• num (integer) – количество рекламных блоков.
• format (string|array) – идентификаторы форматов объявлений через запятую или в виде массива.
• group (string|array) – идентификаторы групп объявлений через запятую или в виде массива.
• post_id (integer) – идентификатор записи для которой нужно получить объявления.
• term_id (integer) – идентификатор термина таксономии для которого нужно получить объявления.
• page (string|array) – типы страниц через запятую или в виде массива. Поддерживаются значения:
  • front_page — главная страница;
  • page – статические страницы;
  • single – страницы постов и пользовательских типов записей;
  • term – страницы рубрик, меток и пользовательских таксономий;
  • search – страница с результатами поиска;
  • attachment – страницы вложений;
  • 404 – страница ошибки 404;
  • post_type_archive – архивные страницы типов записей;
  • author – архивные страницы авторов;
  • date – архивные страницы дат;
• device (string|array) – типы устройств через запятую или в виде массива. Поддерживаются значения:
  • mobile – смартфоны;
  • desktop – настольные компьютеры;
  • tablet – планшеты;
• location (string|array) – коды стран Alpha-2 ISO 3166-1 в верхнем регистре через запятую или в виде массива. Пример: RU, UA, DE, NL, US.
• orderby (string) – тип сортировки рекламных блоков. Поддерживаются значения:
  • priority – по приоритету;
  • post__in – по переданным ID;
  • rand – в случайном порядке;
  • date – по дате создания;
  • modified – по дате изменения;
• order (string) – порядок сортировки. Поддерживаются значения:
  • ASC – в обычном порядке;
  • DESK – в обратном порядке;
• not (string|array) – идентификаторы рекламных блоков через запятую или в виде массива, которые необходимо исключить из запроса.
• default (string|array) – идентификаторы рекламных блоков через запятую или в виде массива, которые будут показаны по умолчанию, если для страницы не удалось подобрать релевантные объявления.
• class (string) – CSS классы через пробел, которые будут использованы для контейнера с объявлениями.
• timeout (integer) – задержка показа рекламных блоков в миллисекундах. Параметр актуален только для обычных и HTML-шорткодов, загружаемых с помощью Ajax.
• ajax (integer) – статус Ajax. Используется только для шорткодов [adcontent]. Если указать 1, то шорткод вернет HTML шорткод для загрузки рекламных блоков с помощью Ajax.
• return (string) – тип возвращаемых данных. Может принимать значение string или array. Параметр актуален только для JavaScript функции adcontent_ajax().

Массивы поддерживают только PHP-функции get_ads() и the_ads(). Для работы с другими функциями и шорткодами используйте строковое представление данных.

Следует отметить, что параметры post_id, term_id, page, device и location определяются автоматически, если вы не указали их вручную или передали в качестве значения NULL. Вы можете отключить любой из параметров, несмотря на его статус в настройках плагина, указав в качестве значения 0 или false.

То есть, если на сайте включено, например, автоматическое определение местоположения пользователя, но в параметре location вы укажете 0, то плагин выведет рекламные блоки без учета данного параметра. Или же вы можете указать собственное значение и при подборе рекламных блоков плагин будет использовать только его. Модуль автоматического определения местоположения пользователя при этом задействован не будет.

Шорткод [adcontent]

Шорткоды позволяют выводить рекламные блоки непосредственно в тексте записей, а также в текстовых и HTML-виджетах, если включена соответствующая функция в настройках плагина. Для вывода рекламных блоков достаточно прописать шорткод [adcontent] и передать в него соответствующие параметры.

В качестве примера выведем три случайных рекламных блока в контейнере с классом ads.

[adcontent num="3" orderby="rand" class="ads"]

Чтобы получить код рекламных блоков в шаблоне сайта, используйте WordPress функцию do_shortcode().

<?php $ads = do_shortcode( '[adcontent num="3" orderby="rand" class="ads"]' ); ?>

HTML-шорткод

Использование HTML-шорткодов позволяет быстро и легко загружать рекламные блоки в любом месте сайта с помощью Ajax без каких-либо манипуляций с JavaScript кодом. Для этого достаточно создать элемент с классом adcontent-ajax и передать в него соответствующие параметры с помощью атрибутов data-*.

В качестве примера получим 5 случайных рекламных блоков.

<span class="adcontent-ajax" data-num="5" data-orderby="rand"></span>

После загрузки страницы данный код будет заменен рекламными блоками или удален, если релевантные объявления не будут найдены или же возникнет какая-либо ошибка при их получении.

PHP-функция get_ads()

Получает код рекламных блоков в виде массива или строки.

Возвращает

Индексный массив (array) или строку (string), в зависимости от значения параметра $return. false или пустую строку, если рекламные блоки получить не удалось.

Использование

<?php $ads = get_ads( $args, $return ); ?>

• • $args (array) – массив аргументов для получения рекламных блоков.
  • $return (string) – тип возвращаемых данных. Поддерживаемые значения:
    • array – функция вернет индексный массив с кодом рекламных блоков.
    • string – функция вернет строку, содержащую рекламные блоки вместе с контейнером.

Пример:

Получение 10 рекламных блоков с сортировкой по приоритету.

$ads = get_ads( array(
    'num' => 10,
    'orderby' => 'priority'
) );

PHP-функция the_ads()

Выводит рекламные блоки на экран. Является оберткой для функции get_ads().

Использование

<?php the_ads( $args, $before, $after, $default ); ?>

• $args (array) — массив аргументов для получения рекламных блоков.
• $before (string) – текст или HTML-код, который будет добавлен перед рекламными блоками.
• $after (string) – текст или HTML-код, который будет добавлен после рекламных блоков.
• $default(string) – текст или HTML-код, который будет выведен на экран по умолчанию, например, если релевантные рекламные блоки не будут найдены или в процессе их получения возникнет какая-то ошибка.

Пример:

Вывод 5 случайных рекламных блоков в контейнере с классом widget.

the_ads( array(
    'num' => 5,
    'orderby' => 'rand'
), '<div class="widget">', '</div>' );

JavaScript-функция adcontent_ajax()

Данная JavaScript функция позволяет получать рекламные блоки с помощью Ajax. Для максимальной эффективности ее следует использовать после инициализации Ajax переменных. Чтобы это сделать, необходимо привязать функцию к событию adcontent_ajax_globals_init.

Использование

adcontent_ajax( args, callback );

• args (object) – объект с аргументами для получения рекламных блоков.
• callback (function) – функция, в которую будут переданы результаты запроса.

Возвращает

В случае успеха в функцию callback будет передан индексный массив или строка с кодом рекламных блоков. В противном случае — false. Тип возвращаемых данных задается через параметр args['return'], который может принимать значение string или array.

Пример использования

В качестве примера получим один рекламный блок, обернем его в HTML-код виджета и добавим в сайдбар.

jQuery( window ).on( 'adcontent_ajax_globals_init', function() {
    adcontent_ajax( { 'num' : 1, 'return' : 'string' }, function( data ) {
        if ( jQuery.type( data ) === 'string' ) {
            var ads = '<div class="widget">' + data + '</div>';
            ads = jQuery( '<div/>' ).html( ads ).contents();
            jQuery( '#sidebar' ).append( ads );
        }
    } );
} );