+
+
(Quick Reference)
+
+
+
Html Cleaner Docs Plugin - Reference Documentation
+
Authors: Sudhir Nimavat
+
Version: 0.1
+
+
+
+
+
+
Table of Contents
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
1 Introduction
+The
html-cleaner plugin is a whitelist based html sanitizer, based on
jsoup.
+Plugin provides a DSL to define whitelists and adds a method
cleanHtml() to every controllers.
+
+
+
+
1.1 Change Log
+
+
Version 0.1
+
+- Initial release - for grails version 1.3.7 and greater.
+
+
+
+
2 Usage
+The plugin adds
cleanHtml(String unsafe, String whitelist) method to every controller. The method can be used to clean and sanitize
+user entered unsafe html against given whitelist. See
Whitelist to know more about whitelist.
cleanHtml()
+Let's say you have a form with a text area, but you don't want to allow any html. You can clean the user supplied text with whitelist
none and it will stripe out all the html.
class FooController { def save = { String cleaned = cleanHtml(params.textArea, 'none')
+ } }
allow basic html as per
basic whitelist.
def cleaned = cleanHtml(unsafe, 'basic')
Following whitelists are available by default and does not need any configuration.
+
+- none
+- simpleText
+- basic
+- basicWithImages
+- relaxed
+
htmlCleaner bean
+Plugin makes a spring bean with name
htmlCleaner available. htmlCleaner provides a method
cleanHtml() with same signature as the dynamic method available in controllers.
Using htmlCleaner inside a service
class FooService { def htmlCleaner def foo() {
+ String cleaned = htmlCleaner.cleanHtml(unsafe, 'none')
+ }
+ }
<hc:cleanHtml /> tag
Example
<hc:cleanHtml unsafe="${domainInstance.description}" whitelist="basic"/>
+
+
+
3 Defining custom whitelists
+Plugin provides a DSL to define custom whitelists in configuration.
Define a custom whitelist
sample that will allow just <b>,<i>,<p> and <span> tags.
Config.groovy
+
htmlcleaner {
+ whitelists = {
+ whitelist("sample") {
+ startwith "none"
+ allow "b", "p", "i", "span"
+ }
+ }
+}
The above configuration would define a whitelist with name
sample that builds on top of whitelist
none and allows additional tags <b>,<i>,<p> and <span>
A whitelist can start with any of the default whitelists or A whitelist can start with any custom whitelists that are defined earlier in configuration as well, but it must start with another whitelist.
Define a whitelist
sample2 that starts with whitelist
sample we defined above and allows tag <a> with just one attribute
href and puts
rel="nofollow" htmlcleaner {
+ whitelists = {
+ whitelist("sample2") {
+ startwith "sample"
+ allow("a") {
+ attributes "href"
+ enforce attribute:"rel", value:"nofollow"
+ }
+ }
+ }
+}
Define a whitelist basic-with-tables that starts with whitelist
basic and allows tables.
htmlcleaner {
+ whitelists = {
+ whitelist("basic-with-tables") {
+ startwith "basic"
+ allow "table", "tr", "td"
+ }
+ }
+}
Restricting attributes
+
htmlcleaner {
+ whitelists = {
+ whitelist("sample") {
+ allow("div") {
+ attributes "id", "class"
+ }
+ }
+ }
+}
Enforcing attributes - An enforced attribute will always be added to the element. If the element already has the attribute set, it will be overridden.
+
htmlcleaner {
+ whitelists = {
+ whitelist("sample") {
+ allow("div") {
+ enforce attribute:"class", value:"block"
+ }
+ }
+ }
+}
Defining multiple whitelists
htmlcleaner {
+ whitelists = {
+ whitelist("sample") {
+ startwith "none"
+ allow "b", "p", "span"
+ } whitelist("sample-with-anchor") {
+ startwith "sample"
+ allow("a") {
+ attributes "href"
+ enforce attribute:"rel", value:"nofollow"
+ }
+ } whitelist("basic-with-tables") {
+ startwith "basic"
+ allow "table", "tr", "td"
+ } }
+}
+
+
+