Functions and shortcodes

Functions and shortcodes

You can use the following functions and shortcodes to interact with the plugin:

• WordPress shortcode [adcontent];
• HTML shortcode <div class="adcontent-ajax"></div>
• PHP functions get_ads() and the_ads()
• JavaScript function adcontent_ajax()

To get the code, use the Code Generator.

Parameters

Functions and shortcodes support the following parameters:

• id (integer|string|array)– Ad ID, comma-separated list of IDs or an array of IDs.
• num (integer|string) – Total number of ads to retrieve. Accepts -1 for all. Default 0.
• format (integer|string|array) – Ad format ID, comma-separated list of IDs or an array of IDs.
• group (integer|string|array) – Ad group ID, comma-separated list of IDs or an array of IDs.
• post_id (integer|string) – ID of the post for which you want to receive relevant ads.
• term_id (integer|string) – ID of the taxonomy term for which you want to receive relevant ads.
• page (string|array) – A page type, a comma-separated list of page types or an array of page types. Supported values:
  • front_page — homepage.
  • page – static pages.
  • single – posts and custom post types.
  • term – taxonomy pages.
  • search – search results.
  • attachment – attachment pages.
  • 404 – error pages.
  • post_type_archive – post type archives.
  • author – author archives.
  • date – date archives.
• device (string|array) – A device type, a comma-separated list of device types or an array of device types. Supported values:
  • mobile – mobile devices.
  • desktop – desktop computers.
  • tablet – tablets.
• location (string|array) – Alpha-2 ISO 3166-1 country code, a comma-separated list of country codes or an array of country codes. Example: US, UK, NL.
• orderby (string) – Sort order of ads. Supported values:
  • priority – sort by priority.
  • post__in – sort by included IDs.
  • rand – sort randomly.
  • date – sort by creation date.
  • modified – sort by date modified.
• order (string) – Sorting direction. Supported values:
  • ASC – sort ascending.
  • DESK – sort descending.
• not (integer|string|array) – Ad ID, comma-separated list of IDs or an array of IDs. Specify ads to exclude from the query.
• default (integer|string|array) – Ad ID, comma-separated list of IDs or an array of IDs. Specify the ads that will be received by default if the plugin does not find relevant ads for the current page and visitor.
• class (string) – CSS class or comma-separated list of CSS classes. Specify CSS classes for the container of ads.
• role (string) – A user role or a comma-separated list of user roles. Specify user roles to display ads only to users with specific roles.
• timeout (integer|string) – Delay time (mc) for loading ads using Ajax. This parameter is valid only for shortcodes.
• ajax (bool|integer) – Ajax status. Allows you to load ads using Ajax. This parameter is valid only for the [adcontent] shortcode.
• return (string) – The type of data returned. This parameter is valid only for the adcontent_ajax() function. Supported values:
  • string – The code of ads will be returned as a string.
  • array – The code of ads will be returned as an index array.

Arrays only support the get_ads() and the_ads() PHP functions. To work with other functions and shortcodes, use a string representation of the data.

It should be noted that the parameters post_id, term_id, page, device and location are determined automatically if you did not specify these parameters manually or passed them NULL values. You can disable any of these parameters, despite its status in the plugin settings, specifying 0 or false as the value.

For example, if geolocation is enabled, but you specify 0 in the location parameter, then the plugin will display ads without taking into account the user’s current location. If you specify your own value, the plugin will use it when searching for relevant ads instead of the user’s actual location.

WordPress shortcode

By default, shortcodes can be used in post content. To do this, paste the shortcode anywhere in the post/page content.

Exmaple:

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

You can also use shortcodes in text and HTML widgets. If your shortcodes are displayed as plain text, activate the “Widget Shortcodes” option in the plugin settings.

If you want to use the shortcode in a theme or plugin, use the do_shortcode function.

Example:

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

HTML shortcode

HTML shortcodes can be used anywhere on the site. To do this, simply add HTML code anywhere on the page.

Example:

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

HTML shortcodes load ads using Ajax, so they require the “Scripts” and “Ajax” options to be enabled.

PHP function get_ads()

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

Retrieves ads as a string or array. You can use this function in the theme and plugins.

Return

An index array or a string, depending on the value of the $return parameter. false or empty string "" if ads could not be received.

Parameters

• $args (array) – arguments to retrieve ads.
• $return (string) – the type of data returned. Supported Values:
  • string – the code of ads will be returned as a string.
  • array – the code of ads will be returned as an index array.

Example:

<?php $ads = get_ads(array(
    'num' => '10',
    'orderby' => 'rand'
), 'string'); ?>

PHP function the_ads()

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

Displays the code of ads. You can use this function in the theme and plugins.

Parameters

• $args (array) – arguments to retrieve ads.
• $before (string) – the text or HTML code to be added before the ads.
• $after (string) – the text or HTML code to be added after the ads.
• $default (string) – the text or HTML code that will be displayed by default if relevant ads are not found.

Example:

<?php the_ads( array(
    'num' => '10',
    'orderby' => 'rand',
), '<div class="ads">', '</div>' ); ?>

JavaScript function adcontent_ajax()

adcontent_ajax( args, callback );

Retrieves ads as a string or array using Ajax. You can use this function in the theme and plugins.

Return

If successful, the ads will be passed to the callback function as an index array or string. Otherwise, false. The type of returned data is set via the args['return'] parameter, which can take the value string or array.

Example:

<script>
    jQuery( document ).ready( function() {
        jQuery( window ).on( "adcontent_globals_init", function() {
            adcontent_ajax( {
                'num' : '10',
                '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 );
                }
            } );
        } );
    } );
</script>