Override Files in Community Server

Community Server

Group for Content about my AlexCrome.CS addon package for Community Server 2008

Override Files in Community Server

  • Comments 1

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.

Why Should I use Override Files?

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.

The Override File

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.

Overrides

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

  • Remove – Deletes a node or attribute
  • Update – Used to change an entire xml node
  • Add – Adds a node (or nodes) either before, after or within the specified node
  • Change – Used to change the value of an attribute
  • New – Used to create a new attribute with the specified value

Remove

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)

Before After

<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>

Update

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>
Before After

<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>
 

  <html>
    <strong />
    <em />
    <p />
    <br />
  </html>

</MarkUp>

Add

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.

  • before – This adds the nodes within the override before the node specified in the XPath
  • after– This 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>
  <Html>
    <!-- Snip -->
  </Html>
</MarkUp>

<MarkUp>
  <Before />
  <Html>
    <Unspecified />
    <Start />

    <!-- Snip -->
    <End />
  </Html>
  <After />
</MarkUp>

Change

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 – the name of the attribute you want to change
  • value – the new value you want the attribute to have

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" />
Before After

<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>

New

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 – the name of the attribute you want to add
  • value – the 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>
  <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.

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Post
  • CSModules allow you to plug into Community Server and run your own code when certain events happen. In
Page 1 of 1 (1 items)