Shortcodes

Burst Statistics provides shortcodes to display analytics data on the frontend of your WordPress site.

`[burst_statistics]`

The main shortcode for displaying statistics. Supports multiple display types, date ranges, and output formats.

Basic usage:

[burst_statistics type="pageviews"]

Parameters

Parameter	Type	Default	Description
`type`	string	`pageviews`	The type of statistic to display. See Supported Types below.
`period`	string	`30days`	Predefined date period. Used when `start_date`/`end_date` are not set.
`post_id`	string	(empty)	Numeric post ID to filter stats for a specific post, or `current` to use the current post.
`page_url`	string	(empty)	Relative URL path to filter stats for a specific page. Takes precedence over `post_id`.
`object_type`	string	`post`	Object type context for the query.
`limit`	int	`5`	Maximum number of items for list-type results (`top_pages`, `top_referrers`, `device_breakdown`, `most_visited`).
`format`	string	`number`	Output format for single-value types. `number` renders the raw formatted number; `text` renders a label with the value.
`label`	string	(empty)	Optional custom label rendered above the statistic value.
`empty_message`	string	(empty)	Message to display when no data is found.
`cache_duration`	int	`3600`	Transient cache duration in seconds. Set to `0` to disable caching.
`start_date`	string	(empty)	Start of a custom date range. Format: `YYYY-MM-DD`.
`end_date`	string	(empty)	End of a custom date range. Format: `YYYY-MM-DD`.
`show_count`	bool	`false`	Whether to display the view count next to each item. Only applies to `most_visited` type.
`post_type`	string	`post`	WordPress post type to filter. Only applies to `most_visited` type. Must be a public post type.

Supported Types

Single-value types

These types render a single formatted number or text value.

`type` value	Description
`pageviews`	Total number of page views.
`visitors`	Total number of unique visitors.
`sessions`	Total number of sessions.
`bounce_rate`	Bounce rate as a percentage (e.g. `42.3%`).
`avg_time_on_page`	Average time on page, formatted as seconds (e.g. `34 seconds`).
`first_time_visitors`	Number of first-time visitors.
`conversions`	Total number of conversions.

List types

These types render a <ul> list of items.

`type` value	Description
`top_pages`	Most visited pages, showing page title and view count.
`top_referrers`	Top referral sources, showing referrer domain and view count.
`device_breakdown`	Breakdown of visits by device type (Desktop, Tablet, Mobile, Other), showing percentage share.
`most_visited`	Most visited posts. Supports `post_type` and `show_count` parameters.

Examples

Total pageviews for the last 30 days:

[burst_statistics type="pageviews"]

Visitors for the current post:

[burst_statistics type="visitors" post_id="current"]

Pageviews for a specific post:

[burst_statistics type="pageviews" post_id="42"]

Pageviews for a specific URL path:

[burst_statistics type="pageviews" page_url="/about/"]

Bounce rate with a custom label:

[burst_statistics type="bounce_rate" label="Bounce rate (last 30 days)"]

Pageviews in text format (shows metric name + value):

[burst_statistics type="pageviews" format="text"]

Custom date range:

[burst_statistics type="pageviews" start_date="2024-01-01" end_date="2024-01-31"]

Top 10 pages with a fallback message:

[burst_statistics type="top_pages" limit="10" empty_message="No data available yet."]

Top referrers:

[burst_statistics type="top_referrers" limit="5"]

Device breakdown:

[burst_statistics type="device_breakdown"]

Most visited posts (post type: page, show view count):

[burst_statistics type="most_visited" post_type="page" limit="5" show_count="true"]

Disable caching:

[burst_statistics type="pageviews" cache_duration="0"]

Output HTML

Single-value types render a <p> tag with type-specific CSS classes:

<!-- format="number" (default) -->
<p class="burst-statistics-number burst-statistics-pageviews">1,234</p>

<!-- format="text" -->
<p class="burst-statistics-text burst-statistics-pageviews">Page Views: 1,234</p>

<!-- With label="My label" -->
<p class="burst-statistics-custom-label">My label</p>
<p class="burst-statistics-number burst-statistics-pageviews">1,234</p>

List types render a <ul> with class burst-statistics-list and a type-specific modifier class:

<ul class="burst-statistics-list burst-statistics-top_pages">
  <li class="burst-statistics-item">
    <span class="burst-statistics-label">Homepage</span>
    <span class="burst-statistics-value">5,678</span>
  </li>
  ...
</ul>

When no results are found and empty_message is set:

<p class="burst-statistics-empty">No data available yet.</p>

`[burst-most-visited]` (deprecated)

caution

This shortcode was deprecated in version 1.5.0. Use [burst_statistics type="most_visited"] instead. The shortcode remains registered for backward compatibility but will trigger a deprecation notice in the WordPress admin for users with manage_options capability.

Old usage:

[burst-most-visited count="5" post_type="post" show_count="false"]

Equivalent new usage:

[burst_statistics type="most_visited" limit="5" post_type="post" show_count="false"]

Parameter mapping

Old parameter	New parameter	Notes
`count`	`limit`	Number of posts to display.
`post_type`	`post_type`	WordPress post type.
`show_count`	`show_count`	Whether to display the view count.

Filters and Hooks

`burst_statistics_shortcode_custom_type`

Allows registering a custom type value not handled by the built-in switch. Return an HTML string to use as the shortcode output; return false to fall through to the default invalid-type error.

Parameters:

Parameter	Type	Description
`$output`	`false`	Always `false` on input; return an HTML string to provide custom output.
`$atts`	`array`	Full sanitized shortcode attributes.
`$start`	`string`	Resolved query start date.
`$end`	`string`	Resolved query end date.

Example:

add_filter( 'burst_statistics_shortcode_custom_type', function( $output, $atts, $start, $end ) {
    if ( $atts['type'] !== 'my_custom_stat' ) {
        return $output; // Return false to let Burst handle it.
    }

    // Build and return your own HTML output.
    return '<p>My custom stat output</p>';
}, 10, 4 );

`burst_statistics_shortcode_query_args`

Allows modifying the query arguments before the database query is executed. Use this to adjust select, filters, group_by, order_by, or limit for any built-in type.

Parameters:

Parameter	Type	Description
`$query_args`	`array`	Array with keys `select`, `filters`, `group_by`, `order_by`, `limit`.
`$atts`	`array`	Full sanitized shortcode attributes.

Example:

add_filter( 'burst_statistics_shortcode_query_args', function( $query_args, $atts ) {
    // Cap the limit for top_pages to 3.
    if ( $atts['type'] === 'top_pages' ) {
        $query_args['limit'] = min( $query_args['limit'], 3 );
    }

    return $query_args;
}, 10, 2 );

`burst_statistics_shortcode_output`

Allows modifying the final HTML output of the shortcode before it is cached and returned. The filtered value is passed through wp_kses_post().

Parameters:

Parameter	Type	Description
`$output`	`string`	The rendered HTML output.
`$result`	`array\|null`	Raw query result row for single-value types; `null` for list types.
`$atts`	`array`	Full sanitized shortcode attributes.

Example:

add_filter( 'burst_statistics_shortcode_output', function( $output, $result, $atts ) {
    if ( $atts['type'] === 'pageviews' ) {
        $output = '<div class="my-wrapper">' . $output . '</div>';
    }

    return $output;
}, 10, 3 );

`burst_most_visited_count`

Filters the view count displayed next to each post in the most_visited list when show_count="true".

Parameters:

Parameter	Type	Description
`$count`	`int`	The raw view count for the post.
`$post`	`WP_Post`	The post object.

Example:

add_filter( 'burst_most_visited_count', function( $count, $post ) {
    return $count . ' views';
}, 10, 2 );

Caching

Shortcode output is cached using WordPress transients. The cache key is derived from a hash of all shortcode attributes, the resolved date range, and the plugin version, so each unique combination of parameters has its own cache entry.

Default cache duration: 3600 seconds (1 hour).
Set cache_duration="0" to disable caching entirely.
Caching is automatically bypassed when WP_DEBUG is true.
Cache is automatically invalidated when the plugin version changes.

Stylesheet

The shortcode stylesheet (assets/css/shortcodes.css) is registered on wp_enqueue_scripts but only enqueued when a post's content contains a [burst_statistics] or [burst-most-visited] shortcode. It is not loaded on pages that do not use these shortcodes.

[burst_statistics]​

Parameters​

Supported Types​

Single-value types​

List types​

Examples​

Output HTML​

[burst-most-visited] (deprecated)​

Parameter mapping​

Filters and Hooks​

burst_statistics_shortcode_custom_type​

burst_statistics_shortcode_query_args​

burst_statistics_shortcode_output​

burst_most_visited_count​

Caching​

Stylesheet​

`[burst_statistics]`

Parameters

Supported Types

Single-value types

List types

Examples

Output HTML

`[burst-most-visited]` (deprecated)

Parameter mapping

Filters and Hooks

`burst_statistics_shortcode_custom_type`

`burst_statistics_shortcode_query_args`

`burst_statistics_shortcode_output`

`burst_most_visited_count`

Caching

Stylesheet