Installing and using the add-on is pretty simple: just install the package and you are ready to go. There is really nothing more you need to do, that is it!
However, some technical users might be interested in the inner workings of this add-on. This documentation explains how this add-on works. Also, for more advanced users, this add-on provides a few configuration options and also the possibility to customize the obfuscation method for your needs. These are also explained in this documentation.
The following sections explain the obfuscation methods provided by this package by default.
The default HTML character references obfuscation method works as follows:
This method is probably the weakest one obfuscation wise but it makes the add-on accessible and usable even without JavaScript enabled in the browser.
If you want to use the rtl-obfuscation method you need to add the following to your application/config/app.php:
<?php return array( // ... some other configurations ... 'obfuscator' => array( 'method' => 'rtl', ), // ... some other configurations ... );
This method works as follows:
This method is stronger than the default HTML character references method but it is not as good accessibility wise without JavaScript. The addresses are visible normally also without JavaScript through the magic of CSS (direction property) but if someone copies the address by highlighting it, it will be reversed when they paste it somewhere. The JavaScript deobfuscator fixes this problem, though.
The Vigenère cipher obfuscation method is strong enough to fool any bots. Thanks to user mnakalay it is available also for the Automatic Email Obfuscator! He was also the first person to put the extendable obfuscation method architecture to the test.
More information about the encryption algorithm is available from Wikipedia.
This method does not work without JavaScript!
If you want to use the Vigenere cipher method you need to add the following to your application/config/app.php:
<?php return array( // ... some other configurations ... 'obfuscator' => array( 'method' => 'vigenere', ), // ... some other configurations ... );
This is by far the strongest of the obfuscation methods but also the weakest accessibility wise. If you are really worried about bots stealing email addresses from your site, use this method to sleep well at night.
Not pleased with the default obfuscation methods? You are welcome to easily write your own. It is done by writing your own email obfuscator class and overriding the 'automatic_email_obfuscator/obfuscator' service binding.
First, create your obfuscator class in the /application/src/EmailObfuscator folder. You can use one of the existing obfuscator classes (e.g. /packages/automatic_email_obfuscator/src/EmailObfuscator/HtmlObfuscator.php) as the basis for your own. Please note that you will need to change the namespace of the class when you copy it to the application folder. The class should look something like this:
>?php // Example for /application/src/EmailObfuscator/YourObfuscator.php namespace Application\Src\EmailObfuscator; use Concrete\Core\Asset\AssetList; use Concrete\Core\Http\ResponseAssetGroup; use Concrete\Package\AutomaticEmailObfuscator\Src\EmailObfuscator\AbstractObfuscator; class YourObfuscator extends AbstractObfuscator { public function registerViewAssets() { // If your obfuscator needs client side deobfuscation, use the following // example to provide the asset to the view. // Defining this method is optional, remove it if you do not need client // side deobfuscation. $al = AssetList::getInstance(); $al->register( 'javascript', 'automatic_email_obfuscator/your', 'js/email_deobfuscator_your.js' ); $r = ResponseAssetGroup::get(); $r->requireAsset('javascript', 'automatic_email_obfuscator/your'); } public function obfuscateMail($email) { // TODO: Write your obfuscation for the plain text emails return $email; } public function obfuscateMailtoLinkHref($href) { // TODO: Write your obfuscation for the <a> element's mailto-links return $href; } }
If you register any client side deobfuscator scripts in your code, use the following example snippet to define the actual deobfuscation script:
// Example for /application/js/email_deobfuscator_your.js (function($){ $(document).ready(function() { // All links with obfuscated mailto href-attributes can be fetched with the "obfuscated-link" class $("a.obfuscated-link").deobfuscateEmailLink(); // All plain text email addresses are wrapped within span elements with the class name "obfuscated-link-text" $("span.obfuscated-link-text").deobfuscateEmailLink(); }); $.fn.deobfuscateEmailLink = function() { $(this).each(function() { // TODO: Write your deobfuscation method here // You can check example from the deobfuscator scripts included in the package. }); }; })(jQuery);
Once all this is done, all you need to do is to is to override the service binding for the 'automatic_email_obfuscator/obfuscator' service. This can be done in /application/bootstrap/app.php and the code you need to use in order to achieve this, is something like in the following example:
Core::bind('automatic_email_obfuscator/obfuscator', function() { return new \Application\Src\EmailObfuscator\YourObfuscator(); });