В данной статье мы рассмотрим функции и шорткоды плагина 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 ); } } ); } );