For the sake of consistency, the examples in this article modify only the configuration of the HTML Scrubber through a communityserver_override.config file. Bear in mind, however, that override files can be used to modify any aspect of a communityserver.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. Instead, you are making the modifications through a separate configuration file. This means that when you upgrade your platform, the changes you’ve made won’t be destroyed if the upgrade comes with new versions of the core configuration files.
[toc]
The Override File
An override file is just another xml file. The basic structure of an override file looks like this:
<?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. Similarly with the communityserver.config file, you’d name the file communityserver_override.config.
With Telligent Community Server 9.0, no override files were included. To begin using one, create the file with the file names listed above and the standard structure shown in this section. Community Server will recognize these new files as override files to their originals and begin using them without further configuration. You will need to restart the application, which can be done by touching the web.config file.
Override modes
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 you should look at the W3School’s XPath tutorial.
The mode attribute specifies the type of the Override. The mode attribute may contain one of five different value
- Remove – Deletes the specified node or attribute.
- Update – Replaces the specified node with new xml.
- Add – Adds a node (or nodes) before, after or within the specified node.
- Change – Used to change the value of the specified attribute on the specified node.
- New – Creates a new attribute with the specified value on the specified node.
Remove mode
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 can use the following override to remove class from the list of allowed global attributes.
<Override xpath="/CommunityServer/MarkUp/globalAttributes/class"
mode="remove" />
Similarly you can 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 you want to remove.
<Override xpath="/CommunityServer/MarkUp/html/font"
mode="remove"
name="color" />
If you used the two overrides described above in a communityserver_override.config file, the following table describes what the configuration file looks like to the Community Server application before and after the overrides are applied. The Before example is not a complete snippet from the communityserver.config file, any markup irrelevant to showing the changes these overrides make has been removed.
Before | After |
<MarkUp> |
<MarkUp> |
Update mode
The update mode allows you to 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 easier to replace the entire node. For example, if you want to allow users to use only a very small subset of html when posting (just bold, italic, paragraphs and line breaks), then you can use the following override:
<Override xpath="/CommunityServer/MarkUp/html" mode="update">
<html>
<strong />
<em />
<p />
<br />
</html>
</Override>
Before | After |
<MarkUp> |
<MarkUp> |
Add mode
The add mode allows you to add nodes into the original configuration file. With add overrides, you can specify an attribute to specify where the overrides should be added. The following values can be used for the where attributes:
- before – Adds the nodes within the override before the node specified in the XPath.
- after– Adds the nodes within the override after the node specified in the XPath.
- start – Adds the nodes within the override at the beginning of the node specified in the XPath.
- end – Adds the nodes within the override at the end of the node specified in the XPath.
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>
Before | After |
<MarkUp> |
<MarkUp> |
Change mode
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:
- name – Name of the attribute you want to change.
- value – New value you want the attribute to have.
The following override example can be used to disallow the colour attribute from being used with the font html element in user-generated content.
<Override xpath="/CommunityServer/MarkUp/html/font"
mode="change"
name="color"
value="false" />
Before | After |
<MarkUp> |
<MarkUp> |
New mode
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:
- name – Name of the attribute you want to add.
- value – Value you want the attribute to have.
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" />
Before | After |
<MarkUp> |
<MarkUp> |