DansGuardian Documentation Wiki

You are here: Main Index » template_customization


Wiki Information

Customizing the Block Page Template

The HTML Template File is the most common way of delivering a blocked page message to a user. It delivers a blocked page message quickly and cleanly to all web browsers, and does almost nothing else. It's just regular HTML; there's no special syntax. You can edit it with any text editor.

When you install DansGuardian you should at minimum modify the Block Page Template a little bit to include your own contact information. That way your users will know who and how to call if they have a problem. The rest of this document focuses on making more than just the minimum modifications to the Block Page Template.

(If you're very interested in Using Blocked Message Delivery for Other Purposes Too, you may need to deliver the blocked page message not this way via an HTML Template but rather via Method 2 (of 2): Using a CGI Program. That method also requires adding a web server. A CGI program used to be the standard way to deliver a blocked page message, but has been superceded almost completely by the much simpler HTML Block Page Template; that's why many custom CGI programs for DansGuardian can still be found on the web, but they're several years old.)

Enabling the HTML Template

In your dansguardian.conf file set the reportinglevel = 3 as you see below.

# Web Access Denied Reporting (does not affect logging)
#  0 = just say 'Access Denied'
#  1 = report why but not what denied phrase
#  2 = report fully
reportinglevel = 3

Modifying the HTML Template

Which Base?

Usually the HTML Template File should at least be personalized a little bit to better fit into your environment. But what should you use as a base when personalizing the HTML Template?

The HTML Template File that is provided when DansGuardian is installed may itself be fully adequate. Often the appropriate thing to do is to simply modify this supplied HTML Template File. Sometimes though rather than modifying the supplied HTML Template File you'll want to replace it with a version you obtained elsewhere that looks completely different. To see some alternative HTML Template Files (and images), browse to http://dansguardian.org/?page=extras and look under the heading “Reporting script and gif replacements:”. (CGI Program variants were much more common before the HTML Template File option was available, so this list has not been updated nor expanded recently.)

Where Is It?

To find the HTML template file, follow the values of the languagedir and language options in your dansguardian.conf. Sometimes languagedir will be a subdirectory of your configuration directory (for example /etc/dansguardian/languages), while other times it will be in a “share” data directory. In every case the file will be named 'template.html'. Paths will of course be different on different systems; one typical path is /usr/local/etc/dansguardian/languages/ukenglish/template.html, another is /etc/dansguardian/languages/ukenglish/template.html, yet another is /usr/share/dansguardian/languages/ukenglish/template.html.

Editing It

Make a backup copy of the original HTML Template File before modifying or replacing it.

As the HTML Template is just regular HTML, edit it the same way you'd edit any other webpage source file. Often you should simply edit the file with any text editor. (HTML editors may or may not work well, as the comments and variable information may confuse them or may become mangled although the intention is to “save” them.)

Directly edit the pre-modified file that exists on the system, rather than any post-modified content that was sent to a web browser. The post-modified content will be specific to a particular blocked page, whereas what you want to edit is the more generic and flexible pre-modified template file.

View intermediate versions of your modified file as often as you like by directly (not through DansGuardian) using any web browser until the general appearance is as you desire. Then, to see the results of substituting the variable bits of information, first guarantee that DansGuardian is aware of your changes by executing dansguardian -g, and go to any end user computer and pretend to be any end user and try to access a website you know will be blocked so the blocked page will be shown through DansGuardian to your web browser.

Tweaking Functionality

The HTML File is just plain old HTML with no particular restrictions; you can put anything in here that web browsers understand. To give you more power, several variables can be filled in by “text substitution” before the file is sent to a browser. You can use these variable parameters to provide lots of functionality and enable different clever display options.

You can tell each user at several levels of detail exactly why the page they tried to access was banned. You can give yourself hints on which list file a restriction is in so you can change it more easily. You can provide click-to-acknowledge "bypass" functionality to some filter groups. And so forth. Since many options straddle the line between “functionality” and “appearance”, they're also described below.

Tweaking Appearance

You may simply wish to personalize the blocked page. For example you should probably replace “YOUR ORG NAME” with the name of your specific organization (“Humpty Dumpty Walls Co.”, or “Saguaro Elementary School”, or …) For another example, you may wish to change the reference to DansGuardian to be just regular text rather than an active hyperlink.

Doing only this sort of change is very simple.

Or, you may wish to go further and make the blocked page more informative to the user by rearranging or customizing the information that's specific for each request. You can tell the user both what was blocked and why it was blocked, and if you wish also give the user a way to acknowledge the block then bypass it. There are quite a few potential bits of information that can be substituted in by DansGuardian before the HTML is sent to the web browser. Only simple text replacement without any knowledge of or attention to syntax is used; the HTML Template File should be correct HTML before the replacements and remain correct HTML after the replacements.

These bits of information can be used to tailor the blocked page to be a little more specific for each presentation to each user. The available bits of information are described by comments in the template file; you can also consult a list of HTML File Parameters.

This sort of change is also straightforward, and is a good idea in many cases.

You may wish to go even further and use CSS to produce a fancier appearance (although the increased complexity may not be worth it). The HTML Template can (but need not) contain CSS, which will simply be passed through to the user's browser. The only pre-processing DansGuardian does to the template before delivering it to the user is simple text string variable substitution.

Finally, the HTML Template can even (but usually doesn't) contain JavaScript, either for further tweaking appearance or for implementing some client-side processing. (You could even do variable substitution within your JavaScript code.)

Be wary of adding JavaScript to the HTML Template though, not only is the increased complexity often not warranted but it might not even work all the time. Browsers often restrict some JavaScript features. By using JavaScript in the HTML Template, you could get into a situation where something as basic as the “blocked page message” sometimes can't be delivered. You should probably add JavaScript to the HTML Template only if you can guarantee that all web browsers will always have all the JavaScript functions you use enabled.

Even these sorts of more extensive changes are available to anyone that wrangles HTML, and they do not require a web server.

Only adding media files (for example images, not just solid rectangles of color) as described below will require adding a web server.

Adding logos or other content to the Template

If you wish to add extra content to the html template you will need to place that content (image, flash file etc.) on a web server. This can be on the same machine as DansGuardian is running, another server on your network or even a server on the internet.

Edit the html template so the img is a full URL. For Example:

img src="http://example.com/path/image.jpg"

The following won't work

img src="path/image.jpg"

If you don't follow the instructions above you will get the following scenario. When you visit a blocked page, the block page doesn't include the image/content and when you look at the properties of the object it shows the object location as:

http://denied url/image.jpg.

Sources of Graphics

You can either create/manipulate an appropriate graphic, or use unchanged an existing one.

Graphics can be in any of the formats understood by web browsers, or to say the same thing with different words those formats that are commonly used on the web. The common web still graphic formats are .GIF, .JPG, and .PNG. (DansGuardian supports any web still graphic format, which in some cases also includes other formats such as .SVG.) You can create images with almost any image editor, including high end commercial tools like Photoshop, high end Open Source Software tools like TheGIMP, and shareware or freeware tools like IrfanView. You may only need very few functions, such as “crop” “scale” and “edit palette”. If you have a suitable graphic but it's in TIFF format so you just need to convert it, just a very simple shareware or freeware tool may be all you need.

You might be able to obtain a graphic that's already suitable for use. Perhaps a school or company admin can supply one. Or perhaps you'll find something suitable in a clipart library. Or perhaps you can use some other DansGuardian user's contribution. On the webpage http://dansguardian.org/?page=extras look under the “Reporting script and gif replacements” heading.