2.4 - Working with SiteConfig

Requirements

v2.4 +

One of the great new features of 2.4 is the introduction of a Site Config page. This allows you to put all of those fields which are not page related, such as The sites title, root access permissions and even the current theme. The SiteConfig class is simply a dataobject and so can easily be extended to include fields, relationships and functions which you can then access from anywhere in your site.

Accessing items in your SiteConfig is as easy as preceding each item with $SiteConfig. For example this would display the Title field:
<h1>$SiteConfig.Title</h1>

Or alternatively:
<% control SiteConfig %> <h1>$Title</h1> <% end_control %>

Accessing SiteConfig from the Controller

So accessing it from the template is super simple and so it turns out is accessing it from a Controller:
$this->SiteConfig();

Or alternatively:
ContentController::SiteConfig()

Customizing SiteConfig

So of course there's not much point in the SiteConfig unless we can add or own fields, relationships and functions. To do so we use the DataObjectDecorator class which allows us to 'decorate' other classes with fields, functions and relationships. We need to decorate SiteConfig instead of extend it with our own class because the core SiteConfig class is the one that SilverStripe will look for. Here is an example of a CustomSiteConfig class which extends DataObjectDecorator:

CustomSiteConfig.php
<?php class CustomSiteConfig extends DataObjectDecorator { function extraStatics() { return array( 'db' => array( 'Spiel' => 'Text' ), 'has_one' => array( 'SiteLogo' => 'Image' ) ); } public function updateCMSFields(FieldSet &$fields) { $fields->addFieldToTab("Root.Main", new TextareaField("Spiel")); $fields->addFieldToTab("Root.Main", new ImageField("SiteLogo", "Logo")); } public function getPooSpiel(){ return '<h3>Poo!</h3>' . $this->owner->Spiel; } }

So here we are adding an extra field to $db and a $has_one relationship. We then add the appropriate form fields to the CMS and we also define a new function. The function is not particularly useful in this case and simple adds the header 'poo' to the start of our Spiel field. However, notice that we use $this->owner to refer to the Spiel field. This is the syntax you must use when extending a DataObject using the DataObjectDecorator so that SilverStripe refers to the object that is being extended rather than the Extention class it self.

Now inorder to get SilverStripe to recognize this extention we need to add this line to our _config.php:
DataObject::add_extension('SiteConfig', 'CustomSiteConfig');

Now in our template we can use these new fields like so:
$SiteConfig.SiteLogo <% control SiteConfig.SiteLogo %> $CroppedImage(100,100) <% end_control %> <p>$SiteConfig.Spiel</p> <p>$SiteConfig.PooSpiel</p>

 

Using DataObjectManager (and ComplextableField) in SiteConfig

So although this should be as simple as using the DataObjectManager on a page, because we are effectively relating 2 DataObjects instead of a page and a DataObject, for some reason SilverStripe is unable to set the ParentID on the DataObject and so it doesn't work. There is however a workaround which is to extend the DataObjectManager class and add a function to explicitly set the sourceID. So to do this all we need to do is create a new class after our CustomSiteConfig class. We could do this in a seperate file, but as it is only used for the SiteConfig it makes sense to keep it there. We also need to adjust our DataObjectManger definition from usual to set the sourceID and make sure it picks up the correct controller:

CustomSiteConfig.php
<?php class CustomSiteConfig extends DataObjectDecorator { function extraStatics() { return array( 'has_many' => array( 'SomeDataObjects' => 'DataObjectClass' ) ); } public function updateCMSFields(FieldSet &$fields) { $manager = new SiteConfig_DataObjectManager( $this->owner, 'SomeDataObjects', 'DataObjectClass', array('SomeField' => 'Some Field'), 'getCMSFields_forPopup' ); $manager->setSourceID($this->owner->ID); $fields->addFieldToTab("Root.DOM", $manager); } } class SiteConfig_DataObjectManager extends DataObjectManager { function setSourceID($val) { if (is_numeric($val)) { $this->sourceID = $val; } } function sourceID() { if (isset($this->sourceID) && $this->sourceID !== null && is_numeric($this->sourceID)) { return $this->sourceID; } return parent::sourceID(); } }

So as you can see instead of using $this we use $this->owner to set the DOM controller. We also use the SiteConfig_DataObjectManager class that we define at the bottom so that we can call our custom setSourceID() function and set the sourceID to $this->owner->ID, which is the ID of the SiteConfig.

Special thanks to Dan Hensby for providing the DOM extension code. You can see the forum post here.

So there you have it, the new SiteConfig. Very useful and easy when you know how! :)

Thanks to Johannes Fischer for suggesting this post.

About the Author