Plugin Planet

Blackhole Pro includes makes it easy to choose the Warning Message that’s displayed to bad bots. And you can go even further and create a custom message that’s dialed in to something perfect. This tutorial explains how it’s done..

Message Types

Blackhole Pro displays two messages. The “Warning Message” is displayed when a bad bot visits the blackhole trigger link. The “Blocked Message” is displayed when a bad bot is blocked from your site. This tutorial is for customizing the Warning Message. To customize the Blocked Message, visit the plugin Settings and click on the “Help” tab in the upper-right corner of the screen for complete infos.

Step 1: Choose your option

To choose the Warning Message, visit the setting “Warning Message”. There you can choose from the following options:

• Default – Displays some basic info and a whois lookup on a red background
• Custom – Displays basic info on a light background
• Simple – Displays some basic info and a whois lookup with minimal styles
• Basic – Displays a custom template (see step 2)

Your choice for this option determines the type of Warning Message displayed to bad bots (when they visit the blackhole link). To use one of the provided Warning Messages, choose your option, click save, and done. Or, to customize the Warning Message, proceed to step 2..

Step 2: Create a custom template

After selecting “Custom” for the setting “Warning Message”, you can create a custom template by following these steps:

1. Copy the file warning-custom.php from the plugin’s /templates/ directory
2. Paste the file into your theme, for example: /wp-content/my-theme/warning-custom.php
3. Customize any of the markup between “BEGIN TEMPLATE” and “END TEMPLATE”
4. Upload to the server and done

Once the custom template is in place in your theme, you can modify it however you wish. Make sure to NOT change anything outside of the “BEGIN TEMPLATE” and “END TEMPLATE” markers, unless you really know what you are doing.

Within the editable part of the template, you have access to a wide variety of variables. These variables represent different types of bot data:

Variable            Example
========            =======

$whois         =>   [ complete whois lookup data ]
$ip_address    =>   123.456.789.000
$request_uri   =>   http://example.com/?blackhole=1234567890
$remote_host   =>   123.456.789.000.example.com
$user_agent    =>   Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_3) ...
$referrer      =>   http://example.com/?blackhole=1234567890
$protocol      =>   HTTP/1.1
$method        =>   GET
$date          =>   2017/03/08 @ 01:56:29 pm
$code          =>   US
$country       =>   United States
$region        =>   Some State
$city          =>   Some City
$zip           =>   Some Zip
$hits          =>   3
$latest        =>   2017/03/08 @ 01:55:48 pm

You can display any of these variables by echoing them to the page, for example to display the whois lookup:

<?php echo $whois; ?>

As you get familiar with the contents of the default template, you will see several of the template variables used to display specific bot infos.

Accessing the Warning Message

To access the Warning Message on the front-end of your site, follow the blackhole trigger link. You can find the trigger by viewing the source code of any of your WordPress-powered pages, and then locating the following code (when using the default trigger):

<a rel="nofollow" style="display:none;" href="https://example.com/?blackhole=1234567890" title="Do NOT follow this link or you will be banned from the site!">Name of Your Website</a>

The URL for that link will take you to the Warning Message. Depending on the plugin’s “Threshold” setting, you may need to remove your IP from the Bad Bots Log to revisit the link (without getting blocked).

Bonus: Change the template file name

Notice the name of the custom template that is added to your theme (from step 2). By default it is named warning-custom.php. That probably is fine for most cases, but there are situations where you may want to change it. To do so, add the following snippet to your theme’s functions.php file:

function blackhole_custom_template_name($name) {
	return 'whatever-you-want'; // note: default name is 'warning-custom'
}
add_filter('blackhole_template_filename', 'blackhole_custom_template_name');

Once in place, the name of the template file will be whatever-you-want (change to whatever you want). Then, just make sure that the actual file name matches this value. Note that the file extension .php is added automatically.