For all examples in this article, I shall only be modifying the configuration of the HTML Scrubber through a communityserver_override.config for the sake of consistency, however do bear in mind that override files can be used to modify any aspect of a communityserver.config or a siteurls.config file.
The main benefit of using override files to make changes to the core configuration files is that you are not actually modifying the core configuration files. You are instead making the modifications through a separate configuration file. This means that when you come to upgrading Community Server, the changes you’ve made won’t be destroyed if the upgrade comes with new versions of the core configuration files.
An override file is just another xml file. The basic structure of an override file goes as follows
<?xml version="1.0" encoding="utf-8"> <Overrides> <!-- Overrides go here --> </Overrides>
The override file should go into the root of your website – i.e. the same location as the existing communityserver.config file. If you are overriding siteurls.config, it should be called siteurls_override.config. Similar with communityserver.config you’d name the file communityserver_override.config.
An override file contains a collection of overrides. Each override must have two attributes specified on it – xpath and mode.
The xpath attribute is the XPath to the node (or attribute) of the configuration file you want to manipulate with the override. A description of XPath goes beyond the scope of this article, but very briefly the XPath is a path to specific nodes in the core configuration file. You will see some example XPaths throughout this article, but for more details on XPath I suggest you have a look at the W3School’s XPath tutorial.
There are five different modes overrides can use
The remove option can be used to remove a whole node or a single attribute from the configuration file. For example, you may decide you don’t want to allow your users to specify css classes for the content they generated. To do this you could use the following override to remove class from the list of allowed global attributes.
<Override xpath="/CommunityServer/MarkUp/globalAttributes/class" mode="remove" />
Similarly you could decide that you don’t want users to be able to specify the colour used with font tags. To remove a specific attribute you must specify the name of the attribute to remove
<Override xpath="/CommunityServer/MarkUp/html/font" mode="remove" name="color" />
If you used the above two overrides in a communityserver_override.config, here is what the configuration file looks like to Community Server before and after the overrides are applied. (N.B. the before is not a complete snippet from the communityserver.config, any markup irrelevant to showing the changes these overrides make has been removed)
<MarkUp> <globalAttributes> <class enable="true" /> <!-- Snip --> </globalAttributes> <html> <!-- Snip –> <font color="true" face="true" size="true” /> <!-- Snip --> </html> </MarkUp>
<MarkUp> <globalAttributes> <!-- Snip --> </globalAttributes> <html> <!-- Snip –> <font face="true" size="true” /> <!-- Snip --> </html> </MarkUp>
The update mode allows you to totally replace a node in the original configuration file. This is particularly useful if you’re making so many changes to the original node, that it’s just easier to replace the whole node. For example say you wanted to allow users to only use an very small subset of html when posting (say just bold, italic, paragraphs and line breaks). You could use the following override.
<Override xpath="/CommunityServer/MarkUp/html" mode="update"> <html> <strong /> <em /> <p /> <br /> </html></Override>
<MarkUp> <html> <a charset="true" href="true" hreflang="true" name="true" rel="true" rev="true" target="true" type="true" /> <abbr /> <acronym /> <!-- Snip --> </html> </MarkUp>
<MarkUp>
</MarkUp>
The add mode allows you to add additional nodes into the original configuration file. With add overrides, you can specify a where attribute to specify where the overrides should be added. The following values can be used for the where attributes.
If no value is specified for where, the start behaviour will be used.
To better illustrate the difference between what different wheres do, take the following overrides
<Override xpath="/CommunityServer/MarkUp/html/" mode="add" where="before" > <Before /> </Override> <Override xpath="/CommunityServer/MarkUp/html/" mode="add" where="after" > <After /> </Override> <Override xpath="/CommunityServer/MarkUp/html/" mode="add" where="start" > <Start /> </Override> <Override xpath="/CommunityServer/MarkUp/html/" mode="add" where="end" > <End /> </Override> <Override xpath="/CommunityServer/MarkUp/html/" mode="add" where="" > <Unspecified /> </Override>
<MarkUp> <Html> <!-- Snip --> </Html> </MarkUp>
<MarkUp> <Before /> <Html> <Unspecified /> <Start /> <!-- Snip --> <End /> </Html> <After /> </MarkUp>
The change mode allows you to change the value of a specific attribute on an xml node. When using the change mode, you must specify two additional attributes on the override
For example, the following override can be used to disallow the colour attribute on the being used with the font html element in user generated content.
<Override xpath="/CommunityServer/MarkUp/html/font" mode="change" name="color" value="false" />
<MarkUp> <html> <!-- Snip --> <font color="true" face="true" size="true” /> <!-- Snip --> </html> </MarkUp>
<MarkUp> <html> <!-- Snip --> <font color="false" face="true" size="true” /> <!-- Snip --> </html> </MarkUp>
The new mode allows you to add a new attribute to an xml node. Like the change mode, you must specify two additional attributes on your override
For example, you may want to allow the type attribute to be specified on ordered lists. To do this you could use the following override
<Override xpath="/CommunityServer/MarkUp/html/ol" mode="new" name="type" value="true" />
<MarkUp> <html> <!-- Snip --> <ol /> <!-- Snip --> </html> </MarkUp>
<MarkUp> <html> <!-- Snip --> <ol type="true" /> <!-- Snip --> </html> </MarkUp>
That’s override files in a nutshell. For further details and some more examples you can have a look at Chapter 4 of the Professional Community Server Themes book. If you have any further questions, either post them to the Community Server Forums, or in the comments section below.