Shortcodes
Print BotBlocker numbers and blocks on any page of your site.
BotBlocker builds its own Dashboard and Reports screens from shortcodes, and you can place the same blocks on a normal post or page. Use them for a public "site activity" page, a private monitoring page for your team, or a custom landing page that shows how much traffic the site turns away.
A shortcode is a tag in square brackets, for example [bbcs_top_countries]. The block editor has a Shortcode block for it. In the classic editor you type the tag where you want the block to appear. In a template you can call it with echo do_shortcode( '[bbcs_top_countries]' );.
The blocks print the numbers that BotBlocker already collected, so they follow the same rules as the Dashboard and Reports: the Report Period:, the Statistics Display Mode, and the retention period. See Reports and statistics.
Traffic and statistics
| Shortcode | Attributes | What it prints |
|---|---|---|
[bbcs_top_ips] |
limit (5), days (7) |
List of the busiest IP addresses in the period |
[bbcs_top_countries] |
limit (5), days (7) |
Countries with flags and hit counts |
[bbcs_top_devices] |
limit (5), days (7) |
Device types, such as PC, phone, tablet |
[bbcs_top_browsers] |
limit (5), days (7) |
Browser names and hit counts |
[bbcs_latest_hits] |
none | Table of the latest visits with time, IP, country, language, device and system |
[bbcs_counters_grid] |
none | Cards with today's and total hits and blocks, search engine visits, and the blocked share |
[bbcs_blocked_today] |
none | A single number: addresses blocked today |
[bbcs_blocked_total] |
none | A single number: addresses blocked since installation |
[bbcs_database_update] |
none | How many new malicious addresses the BotBlocker cloud learned today |
[bbcs_database_total] |
none | How many malicious addresses the BotBlocker cloud knows |
[bbcs_botblocker_news] |
count (5) |
Latest BotBlocker news, linked |
The two cloud database numbers come from the BotBlocker server, not from your site. BotBlocker caches them, so a busy page does not contact the server on every visit.
Health and rules
| Shortcode | Attributes | What it prints |
|---|---|---|
[botblocker_generateSiteHealthList] |
none | The security checklist with a check or a cross for each item |
[bbcs_health_full] |
cols (3, from 1 to 8) |
The same checklist in several columns |
[bbcs_recommendations] |
none | Actionable suggestions, such as enabling 2FA or Redis |
[botblocker_rules_stats] |
show_chart (yes), chart_height (200) |
Counts of your rules: IPv4, IPv6, paths, trusted bots, general rules |
These print finished HTML, so they work on any page.
Parts of the BotBlocker interface
Some shortcodes print a container that a BotBlocker script fills in. The scripts load on the BotBlocker screens, so on a normal page the container stays empty and the block shows nothing useful.
| Shortcode | Attributes | What it prints |
|---|---|---|
[bbcs_health_gauge] |
value, max (100), label, decimals, symbol (%) |
A circular gauge for a score you supply |
[bbcs_statistics_chart] |
type (pie, donut), data (ip_hits_hosts, cookie_hits_hosts, device_types, browsers, operating_systems), period (today), width, height |
One chart of the chosen data |
[bbcs_daily_hits_chart] |
width, height |
Hits per hour for today |
[bbcs_hits_and_uniques_chart] |
days (7, from 1 to 31), width, height |
Hits and unique visitors per day |
[bbcs_visitors_jsvectormap] |
days (30, from 1 to 365), width, height |
World map with unique visitors per country |
[bbcs_cron_tasks] |
none | The task bell that BotBlocker shows in its own header |
[bbcs_lang_options] |
none | A list of the languages that ship with BotBlocker |
Use them inside BotBlocker screens. For a public page, use the blocks above that print finished HTML. The gauge does not calculate anything either: pass the score yourself, for example [bbcs_health_gauge value="85"]. The label follows the score: Secure from 85, Strong from 70, Moderate from 50, Weak from 25, and Critical below that.
Site and system
| Shortcode | Attributes | What it prints |
|---|---|---|
[bbcs_system_status] |
none | Server and software versions, and PHP limits |
[bbcs_plugins_themes] |
none | Every installed plugin and theme, with version and status |
[bbcs_system_status] checks your permission first. A visitor who cannot manage the site gets a short message instead of the versions, so it is safe on a public page.
[bbcs_plugins_themes] is different. It lists what you have installed, with versions. That is useful on a private maintenance page and a gift to an attacker on a public one. Keep the page private, or leave this shortcode out.
Form CAPTCHA
[bbcs_form_captcha] comes from the Form CAPTCHA add-on. It places a visitor check inside any front-end form and has its own page, including the type, theme and class attributes.
Caching
The Interface cache setting on BotBlocker → Settings → System → UI Settings covers most of these blocks. While the cache is on, a number can lag by the cache duration. Turn the cache off when you need a block to show the freshest value, for example during an attack.
Some blocks are never cached: the blocked counters, the system status and the plugins list. The cloud database numbers and the news list use their own short cache.
Before you publish
- A public page shows your traffic to everyone. IP addresses, user agents and country lists are visitor data. Read Privacy and data before you publish a block with details.
- Numbers need history. A block stays empty when the retention period already deleted the days it counts. See Reports and statistics.
- Blocks follow your logging switches. If a request type is not logged, the block cannot count it. See Traffic and audit logs.
When something is missing
- The block is empty? Check the logging switches, the retention period, and the interface cache. The chart blocks also need traffic that falls inside the chart period.
- A chart shows an empty box? The chart scripts load with the BotBlocker admin screens. Open the same chart on the Dashboard or on BotBlocker → Reports to confirm that the data exists.
- The plugins list is empty for visitors? That is expected when the shortcode is inside a block that only administrators can see, or when a page cache serves a stripped copy. Check the page as a logged-out visitor.