2.4 - Using Short Codes to embed a YouTube video

Wed, 28 Apr 2010 00:00:00 -0500

What are shortcodes?

SilverStripe 2.4 has introduced shortcodes to the CMS editor. Simply, the CMS user can now add short BBCode style code to the editor area and it can then be replaced using a predefined function. For example [link id=23] could be replaces by the link to Page with an ID of 23. In fact that is exactly how internal links created in the links sidebar work in 2.4, preventing them from breaking when URLs change.

The aim of this tutorial

The aim of this tutorial is to allow the CMS user to enter the short code:

[YouTube id=3UTu6lV8ppY]

[YouTube id=3UTu6lV8ppY]A video about SilverStripe[/YouTube]

we will also allow them to add more custom attributes. We will then use this to embed a YouTube video automatically for the user.

Short code structure

Shortcodes are made up of three parts, the actual ShortCode (YouTube) its arguments (id) and its content (the text surrounded buy the tags - 'A video about SilverStripe').

The Short Code Parser

The first thing we need to do is to set-up our parser function that will handle the tag, its arguments and its content.

In Page.php we need to add our handler:
class Page extends SiteTree { ... public static function YouTubeShortCodeHandler($arguments,$content = null,$parser = null) { } ... }

$arguments will be an associative array and $content will be a string.

We now need to set-up some default values for the YouTube video we are going to embed, such as size, height and quality. We need to also merge the defaults with the passed arguments and then return the embed code using a template that we will create next.
public static function YouTubeShortCodeHandler($arguments,$caption = null,$parser = null) { // first things first, if we dont have a video ID, then we don't need to // go any further if (!$arguments['id']) { return; } $customise = array(); /*** SET DEFAULTS ***/ $customise['YouTubeID'] = $arguments['id']; //play the video on page load $customise['autoplay'] = false; //set the caption $customise['caption'] = $caption ? Convert::raw2xml($caption) : false; //set dimensions $customise['width'] = 640; $customise['height'] = 385; //overide the defaults with the arguments supplied $customise = array_merge($customise,$arguments); //get our YouTube template $template = new SSViewer('YouTube'); //return the customised template return $template->process(new ArrayData($customise)); }

It is worth noting that the keys of the $arguments array will always be in lowercase.

The Template

In your themes folder you can now add a template called YouTube.ss; I have it in themes/mytheme/Includes as this means I can also use it hard coded into my other page templates if I need to.

YouTube.ss:
<div class="YouTube"> <object type="application/x-shockwave-flash" data="http://www.youtube-nocookie.com/v/$YouTubeID<% if autoplay %>&autoplay=1<% end_if %> width="$width" height="$height"> <embed name="movie" value="http://www.youtube-nocookie.com/v/$YouTubeID<% if autoplay %>&autoplay=1<% end_if %>" /> </object> <p>$VideoCaption</p> </div>

This is XHTML valid YouTube embedding code which uses our custom parameters.

Registering the Parser

Finally, we need to register the parser in our _config.php file:
... //shorcodes ShortcodeParser::get()->register('YouTube',array('Page','YouTubeShortCodeHandler'));

That is it, we have now created our Short Code handler and when a CMS user wants to embed a video from YouTube, they can with ease.

Example usage

[YouTube id=4af1bFh3duo width=300 height=150 related=0]blah[/YouTube]

2.4 - Working with SiteConfig

Mon, 19 Apr 2010 00:00:00 -0500

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.

Display DataObjects in an SEO friendly way

Wed, 10 Feb 2010 00:00:00 -0600

Regarding this 'Need to know' tutorial from Aram, I would like to extend this principle by explaining how to display DataObjects in a SEO friendly way.

There are several ways to do this. I will explain one I prefer the most, by using SiteTree::GenerateURLSegment();.

First step is to add an extra field to the Database called URLSegment. If you use Aram's files in his tutorial on displaying DataObjects, your StaffMember $db array will look like this:

mysite/code/StaffMember.php
class StaffMember extends Page{ static $db = array( 'Name' => 'Varchar(255)', 'Description' => 'Text', 'URLSegment' => 'Varchar(255)' ); . . . . }

To add the URLSegment on save automatically, add the onBeforeWrite() method to the StaffMember class:

mysite/code/StaffMember.php
class StaffMember extends Page{ . . . . public function onBeforeWrite(){ if($this->Name){ $this->URLSegment = SiteTree::GenerateURLSegment($this->Name); if($object = DataObject::get_one($this->ClassName, "URLSegment='".$this->URLSegment."' AND ID !=".$this->ID)){ $this->URLSegment = $this->URLSegment.'-'.$this->ID; } } else { $this->URLSegment = SiteTree::GenerateURLSegment($this->ClassName.'-'.$this->ID); } parent::onBeforeWrite(); } }

First we check for a Name to generate the URLSegment. If present, probably it is, we use SiteTree::GenerateURLSegment(); to create the pretty URL. To prevent duplicate urls, we check for a DataObject by getting a StaffMember with the newly created URLSegment and set an extra filter, so it is not getting itself by adding ID !="This->ID". In this case I only want to know if there is one, and if so I just add the ID to the URLSegment, which is always unique.

This is slightly different then the SiteTree::onBeforeWrite() handles the URLSegment, which counts for the same PageTitles. I prefer to keep it simple by adding the unique ID in case the URLSegment already exist.
And finally, just in case when no Name is entered, we create an unique URLSegment, by using the ClassName and ID.

The Next step is to change the StaffMember links in the StaffSideBar.ss file by replacing {$ID} to {$URLSegment} .

The last step is to change the function getIndividualStaffMember() in StaffPage_Controller:

mysite/code/StaffPage.php
class StaffPage_Controller extends Page_Controller{ public function getIndividualStaffMember(){ if($URLAction = Director::URLParam('Action')){ $StaffMemberURLSegment = Convert::raw2xml($URLAction); if($StaffMemberURLSegment ){ return DataObject::get_one('StaffMember', "URLSegment='".$StaffMemberURLSegment."'"); } } } }

Instead of getting the DataObject by id, we simply use DataObject::get_one() and filter by URLSegment.

What about searchengines and old urls?
There is one thing you have to keep in mind. The SiteTree is versioned. This means that when a page URLSegment is changed, and old page urls are accessed, Silverstripe will redirect the visitor with a 301 Permanently Moved header to the new page url. This is not the case when using my method on getting DataObjects by URLSegment. Each time the Name is changed, the URLSegment will change too, and this will cause old links become inaccessible!

Use a 301 redirect
One way to solve this issue, is to just get the StaffMember by id and attach the URLSegment to the StaffMember link : /{$ID}/{$URLSegment} .

Your getIndividualStaffMember function in StaffPage_controller will then look like this :

mysite/code/StaffPage.php
public function getIndividualStaffMember(){ if($URLAction = Director::URLParam('Action')){ $StaffMemberID = Convert::raw2xml($URLAction); if(is_numeric($StaffMemberID )){ $object = DataObject::get_by_id('StaffMember', $StaffMemberID); if($object->URLSegment != '' && $object->URLSegment != Director::URLParam('ID')){ Director::redirect($this->URLSegment.'/'.$object->ID.'/'.$object->URLSegment,301); } else { return $object; } } } }

Here we still get the StaffMember by ID, but we add a check if the URLSegment from the StaffMember is the same as the URLSegment in the link. The URLSegment is defined Director::URLParam('ID') . If the URLSegment is not the same, we will use Director::redirect() to redirect to the new URLSegment with a 301 permanently moved header. This is important, so search engines will know the url is changed and the 'page' is moved.

Of course you could switch the $ID and $URLSegment, so you move the less important number to the end of the url. In the getIndividualStaffMember function you just switch Director::URLParam('Action') and Director::URLParam('ID') .

Combine ID and URLSegment
If you don't want to use 2 URLParams, you could combine the ID and the URLSegment. To do this add a function URL() to the StaffMember DataObject:

mysite/code/Staffmember.php
public function URL(){ return $this->ID.'-'.$this->URLSegment; }

In StaffSidebar.ss replace {$ID} with {$URL} to display the combined URL. () you could also skip the function and use {$ID}-{$URLSegment} instead.

Use this function in StaffPage_Controller to get the Member:

mysite/code/StaffPage.php
public function getIndividualStaffMember(){ if($URLAction = Director::URLParam('Action')){ $StaffMemberID = Convert::raw2xml($URLAction); $pos = strpos($StaffMemberID, '-'); $ID = substr($StaffMemberID, 0,$pos); $URLSegment = substr($StaffMemberID, $pos + 1); if(is_numeric($ID )){ $object = DataObject::get_by_id('StaffMember', $ID); if($object->URLSegment != '' && $object->URLSegment != $URLSegment){ Director::redirect($this->URLSegment.'/'.$object->ID.'/'.$object->URLSegment,301); } else { return $object; } } } }

We use strpos() to get the first position of - and use substr() to split the URL to the $ID and $URLSegment.

Now, this tutorial got a little longer then I expected when I started to write it. This should give you some methods to use pretty urls to display DataObjects on a Page. Maybe next tutorial should be 'How to add Versioning to DataObjects' to access DataObjects by URLSegment without the use of $ID and with 301 redirects!

Adding Fields to Page Comments

Thu, 04 Feb 2010 00:00:00 -0600

This isn't as simple as it should be. I am also sure that things could be done in a better way, please comment if you have improvments.

Override PageComments

You'll need to override the ContentController->PageComments() function. This is essentially a copy and paste from sapphire/core/control/ContentController.php and change the reference to PageCommentInterface to PageCommentExtendedInterface, which you will create in the next step.
mysite/code/Page.php
<?php class Page extends SiteTree { /*...*/ } class Page_Controller extends ContentController { /*...*/ /** * Returns a page comment system */ function PageComments() { if($this->data() && $this->data()->ProvideComments) { return new PageCommentExtendedInterface($this, 'PageComments', $this->data()); } else { if(isset($_REQUEST['executeForm']) && $_REQUEST['executeForm'] == 'PageComments.PostCommentForm') { echo "Comments have been disabled for this page"; die(); } } } /*...*/ }

Extending PageCommentInterface

PageCommentInterface is the Request Handler for page comments. You will need to override the function PostCommentForm(). Unfortunately because of the way this function is written calling the parent on it and then adding the new fields is not possible (as far as I know), so you must copy the existing function from the parent class and then add your new field in the fields and then to load the new field from the session you'll also have to add your new field to the loadDataFrom array. You are not done with this file yet, now you must also set the session for your new field. To accomplish this you'll have to extend the internal class PageCommentInterface_Form and the function postComment(). In this case you can load up your session and then just call the parent function. Don't forget to change the reference to PageCommentInterface_Form to your new class.
mysite/code/PageCommentExtendedInterface.php:
<?php class PageCommentExtendedInterface extends PageCommentInterface { function PostCommentForm() { $fields = new FieldSet( new HiddenField("ParentID", "ParentID", $this->page->ID) ); $member = Member::currentUser(); if((self::$comments_require_login || self::$comments_require_permission) && $member && $member->FirstName) { // note this was a ReadonlyField - which displayed the name in a span as well as the hidden field but // it was not saving correctly. Have changed it to a hidden field. It passes the data correctly but I // believe the id of the form field is wrong. $fields->push(new ReadonlyField("NameView", _t('PageCommentInterface.YOURNAME', 'Your name'), $member->getName())); $fields->push(new HiddenField("Name", "", $member->getName())); } else { $fields->push(new TextField("Name", _t('PageCommentInterface.YOURNAME', 'Your name'))); } // optional commenter EMAIL $fields->push(new TextField("CommenterEmail", _t('PageCommentInterface.COMMENTEREMAIL', "Email:"))); // optional commenter URL $fields->push(new TextField("CommenterURL", _t('PageCommentInterface.COMMENTERURL', "Your website URL"))); if(MathSpamProtection::isEnabled()){ $fields->push(new TextField("Math", sprintf(_t('PageCommentInterface.SPAMQUESTION', "Spam protection question: %s"), MathSpamProtection::getMathQuestion()))); } $fields->push(new TextareaField("Comment", _t('PageCommentInterface.YOURCOMMENT', "Comments"))); $form = new NewPageCommentInterface_Form($this, "PostCommentForm", $fields, new FieldSet( new FormAction("postcomment", _t('PageCommentInterface.POST', 'Post')) )); // Set it so the user gets redirected back down to the form upon form fail $form->setRedirectToFormOnValidationError(true); // Optional Spam Protection. if(class_exists('SpamProtectorManager')) { SpamProtectorManager::update_form($form, null, array('Name', 'CommenterURL', 'Comment')); self::set_use_ajax_commenting(false); } // Shall We use AJAX? if(self::$use_ajax_commenting) { Requirements::javascript(THIRDPARTY_DIR . '/behaviour.js'); Requirements::javascript(THIRDPARTY_DIR . '/prototype.js'); Requirements::javascript(THIRDPARTY_DIR . '/scriptaculous/effects.js'); Requirements::javascript(CMS_DIR . '/javascript/PageCommentInterface.js'); } // Load the data from Session $form->loadDataFrom(array( "Name" => Cookie::get("PageCommentInterface_Name"), "Comment" => Cookie::get("PageCommentInterface_Comment"), "CommenterEmail" => Cookie::get("PageCommentInterface_CommenterEmail"), "CommenterURL" => Cookie::get("PageCommentInterface_CommenterURL") )); return $form; } } /** * @package cms * @subpackage comments */ class NewPageCommentInterface_Form extends PageCommentInterface_Form { function postcomment($data) { Cookie::set("PageCommentInterface_CommenterEmail", $data['CommenterEmail']); return parent::postcomment($data); } } ?>

Setuping up your site configuration

You will be creating a decorator, you must include some code in your _config.php to assign it. You will also be creating an extension to an Admin section you will want to add a rule to redirect the comments action to your new extension, also remove the old admin section.
mysite/_config.php:
DataObject::add_extension('PageComment','PageCommentDecorator'); Director::addRules(50, array( 'admin/comments//$Action/$ID' => 'CommentAdminExtension', )); CMSMenu::remove_menu_item('CommentAdmin');
(NOTE: I tried to use LeftAndMainDecorator initially instead of extending CommentAdmin, but I ran into several issues)

Decorating PageComment

This could be as simple as just adding a new db static and pushing a new TextField onto CMSFields, however I took it a step further and set it up to send and email after someone posts a comment. The email needs better formatting and it could use the admin email and the links to delete and mark as spam could be generated more dynamically. This is not really part of the tutorial but I thought I would share.
mysite/code/PageCommentDecorator.php:
<?php class PageCommentDecorator extends DataObjectDecorator { function extraStatics() { return array( 'db' => array( "CommenterEmail" => "Varchar(255)", ) ); } public function updateCMSFields(FieldSet &$fields) { $fields->push(new TextField('CommenterEmail', 'Commenter Email')); } function updateFieldLabels(&$labels) { parent::updateFieldLabels($labels); $labels['CommenterEmail'] = "Commenter Email"; } function onAfterWrite() { $post = DataObject::get_one('SiteTree', "`SiteTree`.ID=".$this->owner->getField('ParentID')); $e = new Email( $this->owner->getField('CommenterEmail'),//From Address 'comment@yoursite.com',//To Address - Currently hard coded should get admin address and/or posters address "Posted a comment on ".$post->title,//Subject "".$this->owner->getField('Name') . " said " . '"' . $this->owner->getField('Comment') . '"<br/>'. '<a href="http://yoursite.com/admin/comments/EditForm/field/Comments/item/' . $this->owner->getField('ID') . '?methodName=spam">Mark as SPAM</a><br/>'. '<a href="http://yoursite.com/admin/comments/EditForm/field/Comments/item/' . $this->owner->getField('ID') . '/delete">DELETE</a>' );//Body $e->send(); } } ?>

Extending CommentAdmin

And Finally, if you want to see the new data fields in the backend you'll have to extend the CommentAdmin and override EditForm(). Again, I had to copy and paste the function from the source due to the way it was written. You must add the table field and the PopupFields for your new data field.
mysite/code/CommentAdminExtension:
<?php /*Copied from CommentAdmin.php version 2.3.1 - Added Email field */ class CommentAdminExtension extends CommentAdmin { public function EditForm() { $section = $this->Section(); if($section == 'approved') { $filter = 'IsSpam=0 AND NeedsModeration=0'; $title = "<h2>". _t('CommentAdmin.APPROVEDCOMMENTS', 'Approved Comments')."</h2>"; } else if($section == 'unmoderated') { $filter = 'NeedsModeration=1'; $title = "<h2>"._t('CommentAdmin.COMMENTSAWAITINGMODERATION', 'Comments Awaiting Moderation')."</h2>"; } else { $filter = 'IsSpam=1'; $title = "<h2>"._t('CommentAdmin.SPAM', 'Spam')."</h2>"; } $filter .= ' AND ParentID>0'; $tableFields = array( "Name" => _t('CommentAdmin.AUTHOR', 'Author'), "Comment" => _t('CommentAdmin.COMMENT', 'Comment'), "CommenterEmail" => _t('CommentAdmin.COMMENTEREMAIL', 'Email'), "PageTitle" => _t('CommentAdmin.PAGE', 'Page'), "CommenterURL" => _t('CommentAdmin.COMMENTERURL', 'URL'), "Created" => _t('CommentAdmin.DATEPOSTED', 'Date Posted') ); $popupFields = new FieldSet( new TextField('Name', _t('CommentAdmin.NAME', 'Name')), new TextField('CommenterEmail', _t('CommentAdmin.COMMENTEREMAIL', 'Email')), new TextField('CommenterURL', _t('CommentAdmin.COMMENTERURL', 'URL')), new TextareaField('Comment', _t('CommentAdmin.COMMENT', 'Comment')) ); $idField = new HiddenField('ID', '', $section); $table = new CommentTableField($this, "Comments", "PageComment", $section, $tableFields, $popupFields, array($filter)); $table->setParentClass(false); $fields = new FieldSet( new TabSet( 'Root', new Tab(_t('CommentAdmin.COMMENTS', 'Comments'), new LiteralField("Title", $title), $idField, $table ) ) ); $actions = new FieldSet(); if($section == 'unmoderated') { $actions->push(new FormAction('acceptmarked', _t('CommentAdmin.ACCEPT', 'Accept'))); } if($section == 'approved' || $section == 'unmoderated') { $actions->push(new FormAction('spammarked', _t('CommentAdmin.SPAMMARKED', 'Mark as spam'))); } if($section == 'spam') { $actions->push(new FormAction('hammarked', _t('CommentAdmin.MARKASNOTSPAM', 'Mark as not spam'))); } $actions->push(new FormAction('deletemarked', _t('CommentAdmin.DELETE', 'Delete'))); if($section == 'spam') { $actions->push(new FormAction('deleteall', _t('CommentAdmin.DELETEALL', 'Delete All'))); } $form = new Form($this, "EditForm", $fields, $actions); return $form; } } ?>

That is it. I'd apreciate any feedback you have as this is my first tutorial. I'm considering packaging this as a module, it would also be my first module. I feel the code needs to be a bit better for a module so if you have any improvements don't hesitate contacting me.

Special thanks to Mike Mannix for running through this and proving it works and is somewhat easy to follow, as well as fixing my horrible grammar. Mike is working on his first Silverstripe site elmbrew.com, he completed the level one tutorials and then moved on to this. It is a work in progress so keep an eye on it.

Using SilverStripe URL Parameters to display DataObjects on a page

Tue, 26 Jan 2010 00:00:00 -0600

Many of you may have come across the SilverStripe URL parameters in which take the form $Action/$ID/$OtherID. These are very useful for creating pages that act as templates for a DataObject. Lets say you had a Number of staff that you wanted to enter into the CMS as DataObjects on a StaffPage page type. This would mean that staff members would not have their own page on the site. In an ideal world the StaffPage itself would be able to display a list of all staff member as well as each one individually, based on a name passed as a parameter, for example www.yoursite.com/staff/jonny-cache.

Well in this tutorial we are going to create a system just like this, the only difference is that in order to keep things simple we will be using the staff members ID as the parameter, so the URL would look like this: www.yoursite.com/staff/15. The reason for doing it this way is that we won't have to worry about creating a URL field for each staff member, making sure it doesn't contain special chars and keeping it unique, which would form a tutorial in it self. By suing the ID we can be sure of all of this without having to do anything! On the downside it doesn't make pretty URLs and it's not SEO friendly for the same reason. Well it is only a tutorial after all!

Part 1: Creating the StaffMember DataObject

The first thing we need to do is create the StaffMember it self. We are going to keep this simple and just have a photo, their name and a short description. Obviously you can make this as detailed as you like:

mysite/code/StaffMember.php
<?php class StaffMember extends DataObject { static $db = array( 'Name' => 'Varchar(255)', 'Description' => 'Text' ); static $has_one = array( 'StaffPage' => 'StaffPage', 'Photo' => 'Image' ); public function getCMSFields_forPopup() { return new FieldSet( new TextField('Name'), new TextareaField('Description'), new ImageField('Photo') ); } public function getThumb(){ if($this->PhotoID) return $this->Photo()->CMSThumbnail(); else return '(No Photo)'; } }

This should be pretty familiar to you, just a sandard DataObject class. The only thing that might be new is the getThumb() function. This is used to return a thumbnail of the photo to the DataObjectManager so that you get a nice preview of the person in the table.

Part 2: Creating our StaffPage

Now we need to create the StaffPage that is going to hold all our StaffMember DataObjects. Again this is pretty standard stuff, we create a has_many relationship and define a DataObjectManger as the fieldtype to manage it:

mysite/code/StaffPage.php
<?php class StaffPage extends Page { static $has_many = array( "StaffMembers" => "StaffMember", ); function getCMSFields() { $fields = parent::getCMSFields(); $dataobjectmanager = new DataObjectManager( $this, 'StaffMembers', 'StaffMember', array('Thumb' => 'Photo', 'Name' => 'Name', 'Description' => 'Description'), 'getCMSFields_forPopup' ); $dataobjectmanager->setPluralTitle("a member of staff"); $fields->addFieldToTab("Root.Content.StaffMembers", $dataobjectmanager); return $fields; } } class StaffPage_Controller extends Page_Controller { }

You could also use a complexTableField if you are mad want to. Notice that in the field label definition we call Thumb not getThumb. This is making use of PHP's magic Methods which allows you to add get to the start of a function, without having to use it when calling from a template.

Now lets also just create a basic template for our staff page that will display a list of all the StaffMembers photos:

themes/blackcandy/templates/Layout/StaffPage.ss
<div class="typography"> <h2>$Title</h2> <% control StaffMembers %> $Photo.SetWidth(100) <% end_control %> </div>

Part 3: The funky function

So we have our classes and a basic template which is displaying our staff members. Now what we need to do is create a function which checks to see if there is a URL parameter set and if there is checks the DataBase for a StaffMember with that ID, which if found would then be returned to the template to render. So here is the function which is placed in the StaffPage_Controller class:

mysite/code/StaffPage.php
class StaffPage_Controller extends Page_Controller { public function getIndividualStaffMember(){ if($URLAction = Director::URLParam('Action')){ $StaffMemberID = Convert::raw2xml($URLAction); if(is_numeric($StaffMemberID )){ return DataObject::get_by_id('StaffMember', $StaffMemberID); } } } }

So lets go though this function. The first line gets the URL parameter 'Action' (i.e. the first parameter) and tries to assign it to the variable $URLAction.If it fails we know that there is no action and we can return to the template. Next if there was an 'Action' defined then we 'sanitize' the argument to ensure there is no malicious code in there that could harm the database (if you are wondering why you need to sanitize, read this).

Finally we check that the argument is numeric before we pass it to DataObject::get_by_id() which will try to fetch our staff DataObject. If the ID is wrong, then it will just return false, which we can then use in our template to test whether to render an individual staff member or the list.

Part 4: Displaying it all in the template

So now lets take a look at our template and see how we can use this function to decide what to display:

themes/blackcandy/templates/Layout/StaffPage.ss
<div class="typography"> <h2>$Title</h2> <% if IndividualStaffMember %> <% control IndividualStaffMember %> <ul> <li>$Photo.SetWidth(100)</li> <li>Name: $Name</li> <li>Description: $Description</li> </ul> <% end_control %> <% else %> <% control StaffMembers %> <a href="{$Top.Link}{$ID}" >$Photo.SetWidth(100)</a> <% end_control %> <% end_if %> </div

The function we created in the last step will return false either if there is no action parameter defined or if the defined action is not the ID of a StaffMember. So we first test whether there is an IndividualStaffMember to display which if there is we display some detailed info about that staff member, otherwise we simply display the list of staff all members, this time with a link to view that staff member in more detail. To construct the link we simple join the MenuPage's Link (by using $Top.Link which will jump out of the control loop and get the Link from the main page we are on) with the ID of the staff member in our control loop, giving us URLs like "staff/3". We also wrap these variables in {} to make sure SilverStripe reads them properly.

So now we have a page which will display our dataobjects individually as well as in a list. The last thing we need to do is make our sidebar read them too.

Part5: Creating the Sidebar

To display the DataObjects in the sidebar we need to replace our standard sidebar with a custom one:

themes/blackcandy/templates/Includes/StaffSidebar.ss
<div id="Sidebar" class="typography"> <div class="sidebarBox"> <h3><% control Level(1) %>$Title<% end_control %></h3> <ul id="Menu2"> <% control StaffMembers %> <li><a href="{$Top.Link}/{$ID}" mce_href="{$Top.Link}/{$ID}" title="Go to the $Title.XML page" class="$LinkingMode levela"><span><i>$Name</i></span></a></li> <% end_control %> </ul> <div class="clear"></div> </div> <div class="sidebarBottom"></div> </div>

So as you can see this looks very much like the standard blackcandy sidebar, the only difference being that we have replaced <% control Children %> with <% control Staffmembers %> which will get all our staff members and create links for each. Again we use the {$Top.Link}{$ID} to generate the link. One thing you might notice is that because we are using a single page for all of these, the $LinkingMode will no longer work. So to remedy this lets create our own function LinkingMode() inside the StaffMember DataObject:

mysite/code/StaffMember.php
class StaffMember extends DataObject { . . . . public function getLinkingMode(){ if($this->ID == Director::URLParam('Action')){ return 'current'; } else{ return 'link'; } } }

All this function does is compare the current Action parameter with it's own ID. If they match it returns 'current' otherwise 'link' just like the $LinkingMode for pages!

The last thing left to do is include the sidebar on our template:

themes/blackcandy/templates/Layout/StaffPage.ss
<div class="typography"> <% include StaffSidear %> <div id="Content"> <h2>$Title</h2> <% if IndividualStaffMember %> <% control IndividualStaffMember %> <ul> <li>$Photo.SetWidth(100)</li> <li>Name: $Name</li> <li>Description: $Description</li> </ul> <% end_control %> <% else %> <% control StaffMembers %> <a href="{$Top.Link}{$ID}" >$Photo.SetWidth(100)</a> <% end_control %> <% end_if %> </div> </div>

So that's it! You now have a fully functioning DataObject display(er).

More about URLParameters

In this tutorial we only really scraped the surface of using URL parameters. There are 3 setup by default in SilverStripe, 'Action', 'ID and 'OtherID'. These can be accessed in the same way as this tutorial using Director:URLParam('ParamName'). They can also be accessed by assigning all of them to an array like so:

$URLParams = Director::URLParams(); $Action = $URLParams['Action']; $ID = $URLParams['ID']; $OtherID = $URLParams['OtherID'];

You can also define your own URL parameter structure using Director::addRules(), though documentation on the subject is sparse.

Embedding YouTube or Vimeo inside your Text-Content using a custom 'TextParser'

Thu, 10 Dec 2009 00:00:00 -0600

Embedded videos from platforms like YouTube or Vimeo are very common nowadays. To embed such a video in the SilverStripe CMS, you would have to enter the HTML-Code directly in the HTML-Source of the TinyMCE Editor.

This is a cumbersome and error prone process and may mess with your layout. Wouldn't it be nice if you could type: $YouTube(<videoId>) anywhere in your text and then automatically get the video embedded there?
This snippet makes use of a custom TextParser to achieve that goal.

The VideoParser

Save the following code in a file named mysite/code/parsers/VideoParser.php
<?php class VideoParser extends TextParser { public static $hooks = array( 'YouTube' => array(__CLASS__, 'embedYoutube'), 'Vimeo' => array(__CLASS__, 'embedVimeo') ); public function parse(){ $regex = '{\$('. implode('|', array_keys(self::$hooks)) . ')$([^$]+)\)}i'; return preg_replace_callback($regex, array(&$this, 'replace'), $this->content); } protected function replace(&$in){ if(array_key_exists($in[1], self::$hooks)){ return call_user_func_array(self::$hooks[$in[1]], explode(',', $in[2])); } } protected static function embedYoutube($videoId, $width = 400, $height = 300){ return ' <object type="application/x-shockwave-flash" data="http://www.youtube.com/v/'. $videoId .'" width="'. $width .'" height="'. $height .'"> <param name="movie" value="http://www.youtube.com/v/'. $videoId .'" /> <param name="allowfullscreen" value="true" /><param name="allowscriptaccess" value="always"/> </object>'; } protected static function embedVimeo($videoId, $width = 400, $height = 300){ return ' <object type="application/x-shockwave-flash" data="http://vimeo.com/moogaloop.swf?clip_id='.$videoId.'&server=vimeo.com&fullscreen=1" width="'. $width .'" height="'. $height .'"> <param name="movie" value="http://vimeo.com/moogaloop.swf?clip_id='.$videoId.'&server=vimeo.com&fullscreen=1" /> <param name="allowfullscreen" value="true" /><span name="allowscriptaccess" value="always"/> </object>'; } }

This class parses your text upon request and adds the capability to embed Vimeo or YouTube videos with the use of a simple variable.

Usage

To make use of the new parser, you have to invoke it on your content. This can be achieved by writing:
$Content.Parse(VideoParser)

in your Template (instead of just $Content).

After you did so, you can make use of the new functionality. Log in to the CMS and enter the following in your Content-Area: $YouTube(oHg5SJYRHA0,500,400)

When you visit the page, you should see the YouTube Video with ID oHg5SJYRHA0 and a dimension of 500x400 pixels (you can also skip the dimensions, they will default to 400x300 pixels).

The same works for Vimeo videos. This code: $Vimeo(2619976) will embed the video at http://vimeo.com/2619976. You're free to specify width and height as second and third parameters.

Known issues

Somehow, the parsing breaks the Login page, so if you plan to use the parser for all pages (by putting $Content.Parse(VideoParser) in the Page.ss template), then you should create a custom template for the login page (Security_login.ss) and not use the parser there.

Custom replacements

You can register custom replacement hooks, by registering new handlers in mysite/_config.php
VideoParsers::$hooks['MyHook'] = array('Page', 'myReplacer');

Your Page class would need a static method with a signature like myReplacer(arg1, arg2, arg3,...,argN) and could then be invoked by writing: $MyHook(arg1, arg2, arg3,...,argN) in your content area! So this class could in fact be used for much more than just embedding videos.

Embed flash content using SWFObject

Thu, 03 Dec 2009 00:00:00 -0600

There are numerous ways to embed flash content into your SilverStripe Website. A commonly used and very flexible method to embed flash is provided by the SWFObject script. In this snippet I'll show you how to create a custom FlashPage that will contain flash content, embedded using SWFObject.

Prerequisites

Download and unpack swfobject 2.2 from http://code.google.com/p/swfobject/
copy swfobject.js and expressInstall.swf from the swfobject folder to your mysite folder. I copied the files into mysite/javascript/lib, so this is what I'm gonna use in this example

The FlashPage Class

We're going to create a custom class for our Flash-Content-Page. Save the following code as mysite/code/FlashPage.php
<?php class FlashPage extends Page { public static $db = array( 'AlternateContent' => 'HTMLText' ); public static $has_one = array( 'FlashFile' => 'File' ); public function getCMSFields(){ $fields = parent::getCMSFields(); // create a file upload field that only allows swf to be uploaded $fileUpload = new FileIFrameField('FlashFile', 'Flash file (swf)'); $fileUpload->setAllowedExtensions(array('swf')); $fields->addFieldsToTab('Root.Content.Flash', array( $fileUpload, new HtmlEditorField('AlternateContent', 'Flash replacement text', 20) )); return $fields; } } class FlashPage_Controller extends Page_Controller { public function init(){ parent::init(); // require SWF Object script Requirements::javascript('mysite/javascript/lib/swfobject.js'); } }

After doing so, run /dev/build

Our FlashPage adds a new Tab named "Flash" to the CMS Content Tab. In this tab you'll be able to upload a swf file and provide an alternative content for all the people who don't have flash installed (iPhone comes to mind).

The template

All that's left now is the template part. Create a new template (or layout) named FlashPage.ss and add the following code to it:
<% if FlashFile %> <div id="FlashContainer"> $AlternateContent </div> <script type="text/javascript"> /* <![CDATA[ */ swfobject.embedSWF( "$FlashFile.URL", "FlashContainer", "400", "300", "9.0.0", "mysite/javascript/lib/expressInstall.swf" ); /* ]]> */ </script> <% end_if %>

The above part just outputs the flash content, so feel free to add <h1>$Title</h1>, $Content or any other of the markup you desire.

Here's a short summary what we do with that template code:
First we check if there's a FlashFile available (<% if FlashFile %>). If not, we can skip the whole flash embed stuff.
The <div id="FlashContainer"> container holds the alternative content, and will be replaced with the flash content if the user has the required flash plugin installed.
What follows at the end is the script call to swfobject. SWFObject is highly customizable. You can add parameters to flash, or specify special embed tags (like wmode or bgcolor). There's a good description of all possible parameters on the SWFObject website:
http://code.google.com/p/swfobject/wiki/documentation#STEP_3:_Embed_your_SWF_with

The size of the flash content (width, height) is now defined in the template code. Of course you could also replace these values with variables that can be customized inside the CMS. Give it a try!

Using jQuery for form validation

Fri, 13 Nov 2009 00:00:00 -0600

Demo

Note. This tutorial continues from the Creating a Simple Contact Form tutorial, if you are not sure about form creation is SilverStripe, read that first.

As you may have noticed, SilverStripes built in form validation is based on Prototype and is pretty limited. It also means that even though you might be using jQuery for other things on your site, you will still need to load prototype.js and all the associated files that SilverStripe requires for it's built in JavaScript form validation.

With this in mind using a jQuery validator, such as the excellent Validate plugin has some obvious benefits:

Validate multiple forms on a single page
Customize error messages
More control over inline error styling
Remove the need for loading extra JS files, such as Prototype.js and Behavior.js etc. (more than 90KB in total)
Extended validation options as well as the ability to create custom regex validation rules.

So now that you are (most likely) convinced about the benefits of using jQuery validation let's get started.

Part 1. Removing SilverStripe's built in JS Validator

The first thing we need to do is disable SilverStripe's Prototype validation. We can do that with a single line in our ContactPage_Controller's init() function:
class ContactPage_Controller extends Page_controller{ function init() { parent::init(); Validator::set_javascript_validation_handler('none'); } . . . }

Now if you try the form you will notice that the live Javascript validation is no longer present and more importantly all of the files associated with form validation in SilverStripe (Prototype.js etc) and the messy inline Javascript at the bottom of the page's source is also no where to be seen. Great!

Part 2. Including the jQuery Validator files

Now let's go about adding in our sexy jQuery validation. First things first we need to include both the jQuery source file and the jQuery.Validate plugin. You may already be including jQuery in your Page.php init() function for other uses, if so just skip the first include.
Note. I tend to include jQuery from the google API index as it is often already cached by the users browser, but you can include the one inside the SilverStripe JSparty folder if you prefer. However I could not get the SilverStripe included jquery.validate.min.js to work with the lastest jQuery release, so again I used a hosted version.

So now your init() function will look like this:
function init() { parent::init(); Validator::set_javascript_validation_handler('none'); Requirements::javascript("http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"); Requirements::javascript("http://ajax.microsoft.com/ajax/jquery.validate/1.5.5/jquery.validate.min.js"); }

Part 3. Applying the Validation to the form

Now that we have our jQuery files included we can go about validating our form fields. Due to the great design of the plugin, this is extremely easy. For brevity sake, we are going to include this script by adding a customScript requirement to our init() function, but you could just as easily place it in a seperate .js file and include it in the same was as the files above. So now our innit() function looks like this:
function init() { parent::init(); Validator::set_javascript_validation_handler('none'); Requirements::javascript("http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"); Requirements::javascript("jsparty/jquery/plugins/validate/jquery.validate.min.js"); Requirements::customScript(' jQuery(document).ready(function() { jQuery("#Form_ContactForm").validate({ rules: { Name: "required", Email: { required: true, email: true }, Comments: { required: true, minlength: 20 } }, messages: { Name: "I would really love to know your name", Email: "It is quite important that you give me your actual email address so I can send you messages", Comments: "What are you thinking? Tell me" } }); }); '); }

Although this may look a little scary, it's really very simple. We are simply calling the jQuery.validate() function on #Form_ContactForm which is the id of the <form> tag. We then define the rules by passing in a series of options for each field, following the same field names as defined when creating the fields. For Name we simply tell the validator that it is required, while for Email we tell it that it's required and is of type 'Email'. For the Comments field we also specify a minimum length to make sure people write something of significance.

We then define some suitably creepy error messages that will be displayed if validation fails.

Done! You now have a jQuery Validated form. Best of all the server side SilverStripe validation still works, so you have something to fall back on if Javascript is switched off.

Styling the error messages

As with the rest of the plugin, styling errors is super simple. Here are a couple of css rules to get you going:
label.error{ border: 1px solid #aaa; background: #aa2222; color: #fff; padding: 5px; margin: 0; width: 100%; } input.error{ border: 1px solid #aa2222; }

Using multiple forms on a single page

This validation will work on as many forms as you like per page, but in order for it to work you need to call the jQuery.Validate() function and pass it's options for each form. So copy everything inside the jQuery(document).ready(function(){ and change the id that is passed into the validate() function.

If you are using AJAX for form submission, will will also need to give each field a unique name. AJAX form submission....hmm I feel another tutorial coming on :)

Web 2.0 Mirrored Images

Mon, 02 Nov 2009 00:00:00 -0600

Ever wanted to create the so-called 'web 2.0' mirrored images as you can see on http://www.dio5.com/portfolio/, without having to manually rotate and proces the image? Then this one is for you.

I attached a fully working zip-package, but let's run through some of the code nonetheless.

When it comes to images the Image and GD class are the ones we need to tackle. Create a file in your mysite/code/ folder called ImageDecorator.php and add in the next code:
class ImageDecorator extends DataObjectDecorator { function getMirroredImage($width, $height) { if ($this->owner->ID && $this->owner->Filename && Director::fileExists($this->owner->Filename)) { $cacheFile = $this->owner->cacheFilename("MirroredImage", $width, $height); if (!file_exists("../".$cacheFile) || isset ($_GET['flush'])) { $this->generateMirroredImage($width, $height); } return new Image_Cached($cacheFile); } } function generateMirroredImage($width, $height) { $cacheFile = $this->owner->cacheFilename("MirroredImage", $width, $height); $gd = new MyGD("../".$this->owner->Filename); if ($gd->hasGD()) { $gd = $gd->mirroredImage($width, $height); if ($gd) { $gd->writeTo("../".$cacheFile); } } } }

Create another file called MyGD.php in the same folder:
class MyGD extends GD { public function mirroredImage($width, $height) { $newGD = imagecreatetruecolor($this->width, $this->height); $bg = imagecolorallocatealpha($newGD, 255, 255, 255, 127); imagefill($newGD, 0, 0, $bg); $dst_x = 0; $src_x = 0; $coordinate = ($this->height-1); foreach (range($this->height, 0) as $range) { $src_y = $range; $dst_y = $coordinate-$range; imagecopy($newGD, $this->gd, $dst_x, $dst_y, $src_x, $src_y, $this->width, 1); } $output = new GD(); $output->setGD($newGD); $output = $output->croppedResize($width, $height); return $output; } }

The previous code may look a bit daunting but it's basically just taking the current picture and mirrors it, after which we do a crop on it so you can add in a width & height.

To get the Image Decorator working, we'll need to add this line to our _config.php file:
DataObject::add_extension('Image', 'ImageDecorator');

The interesting part is how you can use it in your templates: $ExampleImage.getMirroredImage(300,200) will give you a mirrored image with a width of 300px and height of 200px.

Combine this with some clever use of css and a png gradient and you will be able to achieve what I did on http://www.dio5.com/portfolio/.

For those of you wanting to test this out, I provided a simple zip-package which contains a folder called 'mirrors'. Just unzip this in your root SS-folder, do a dev/build/ and you'll have an 'Example Page'-type which allows you to set an image on which this effect is demonstrated. It basically contains this html-snippet:
<div class="photo" style="background:url(http://www.ssbits.com/<% control ExampleImage %> <% control getMirroredImage(300,200) %>$URL<% end_control %> <% end_control %>) no-repeat left bottom"> <div> <img src="<% control ExampleImage %> <% control CroppedImage(300,200) %>$URL<% end_control %> <% end_control %>" alt="$Title.ATT" /> </div> </div>

With this css:
.photo div{ position:relative; width:300px; height:401px; background:url(http://www.ssbits.com/../images/overlay.png) repeat-x left 201px; }

Here we are adding the mirrored image as a background image on the outer container div of the 'normal' image. On the inner container div we add a black to transparent png-gradient and position the whole thing with css.

You probably want to experiment with changing the png-overlay image size & color in the zip. For a reflection on white you'll need to replace it with a white to transparent one, instead of a black one.

Hope this little snippet inspired you to do great things! Do not hesitate to ask for help or improve this where possible.

Note: I'm not adding support for IE6 here.

Detecting Mobile Browsers to Re-Theme Your Site

Tue, 06 Oct 2009 00:00:00 -0500

With the proliferation of Smart Phones and other non-traditional-computer ways to browse the internet, wouldn’t it be great if you could provide a custom browsing experience for different users?

You could re-template your site using the sub-sites module, but it might not be stable/functional enough for every one yet. So I’ll show you how to use Anthony Hand’s great User Agent Detection Class to re-template your site based on the User Agent of your visitor.

First things first get yourself a copy of the Class from the link above. He also has a lot of great resources on designing for mobile browsers.

Before we can actually use the calls we need to make some modification. Because of the way SilverStripe’s Manifest builder handles filenames and class names we need to change name of the file, remove the underscores from the name of the class. To sum up:
mdetect_php.txt becomes uagentinfo.php
and in the actual file (line 53):
class uagent_info becomes class uagentinfo

You now add this file to your mysite/code directory and do a dev/build.

Now that SilverStripe knows about the Class we need to call it from the init() function in your mysite/code/page.php
$iPhoneTheme='tutorial'; $blackBerryTheme='tutorial'; $wapTheme='tutorial'; //Check if Mobile Phone Is Already Set if(isset($_SESSION['mobilePhone'])) { switch ($_SESSION['mobilePhone']){ case "iphone": SSViewer::set_theme($iPhoneTheme); break; case "BlackBerry": SSViewer::set_theme($blackBerryTheme); break; case "WAP": SSViewer::set_theme($wapTheme); break; case "None": break; } } else { //Detect Mobile Phone Tier $uagentobj = new uagentinfo(); $mobilePhone = $uagentobj->DetectTierIphone(); if ($mobilePhone == 1){ SSViewer::set_theme($iPhoneTheme); $_SESSION['mobilePhone']="iPhone"; } else { $mobilePhone = $uagentobj->DetectTierSmartphones(); if ($mobilePhone == 1) { SSViewer::set_theme($blackBerryTheme); $_SESSION['mobilePhone']="BlackBerry"; } else { $mobilePhone = $uagentobj->DetectTierOtherPhones(); if ($mobilePhone == 1) { SSViewer::set_theme($wapTheme); $_SESSION['mobilePhone']="WAP"; } else { $_SESSION['mobilePhone']="None"; } } } }

Lets Step through This
$iPhoneTheme='tutorial'; $blackBerryTheme='tutorial'; $wapTheme='tutorial';

In the first part of the code we set variables for the themes we want to use for the three main tiers of mobile browser: iPhone, BlackBerry and Plain old WAP. Right now we’re just using tutorial but you can set these to whatever your want.
if(isset($_SESSION['mobilePhone'])) { switch ($_SESSION['mobilePhone']){ case "iphone": SSViewer::set_theme($iPhoneTheme); break; case "BlackBerry": SSViewer::set_theme($blackBerryTheme); break; case "WAP": SSViewer::set_theme($wapTheme); break; case "None": break; } }

n this part we check to see if the mobilePhone session variable is already set, and if it is we use a switch function to use this variable to set the theme with the SSViewer::set_theme() function, dropping in the corresponding theme name variable in each case. If the session variable isn’t set we move on to actually detecting the user agent.

Here we create a new instance of the uagentinfo class and save it to $uagentobj. we then Take that object and run the first class detection on it, iphone. If the browser is an iPhone its saves that value to the $_SESSION[‘mobilePhone’] variable. If not it runs the next tier detection and so on.
else { //Detect Mobile Phone Tier $uagentobj = new uagentinfo(); $mobilePhone = $uagentobj->DetectTierIphone(); if ($mobilePhone == 1){ SSViewer::set_theme($iPhoneTheme); $_SESSION['mobilePhone']="iPhone"; } else { $mobilePhone = $uagentobj->DetectTierSmartphones(); if ($mobilePhone == 1) { SSViewer::set_theme($blackBerryTheme); $_SESSION['mobilePhone']="BlackBerry"; } else { $mobilePhone = $uagentobj->DetectTierOtherPhones(); if ($mobilePhone == 1) { SSViewer::set_theme($wapTheme); $_SESSION['mobilePhone']="WAP"; } else { $_SESSION['mobilePhone']="None"; } } } }

This is great, but what if someone is using an iPhone or other similar device whose browser can support a non-mobile site with all the bells and whistles. We need to provide the user with a way to override the detection.

In you page_controller add the following function:
//Overide Mobile Theme function MobileOveride(){ $_SESSION['mobilePhone']="None"; Director::redirect(Director::baseURL(). $this->URLSegment); }

This function provides us a way to manually set the $_SESSION[‘mobilePhone’] variable to “None” so that the first CHECK function won’t move on to detecting the user agent. It then forces the browser to reload the current page. All we have to do is add the following to mobile phone templates:
<a href="$URLSegment/MobileOveride" >View Full Site</a>

Thats it, now all you have to do design you mobile templates and you have functioning mobile version of your site. The class is great as it contains methods for detecting many more user agent types including video game platforms and other hand held devices. You could also expand this to use sub-domains to set the $_SESSION[‘mobilePhone’] variable.

Enjoy

Adding a CMS action the (slightly) hacky way

Tue, 01 Sep 2009 00:00:00 -0500

The bit you probably know

If like me you cannot figure out how on earth to use the updateCMSActions() function in a decorator and you also can't get the getCMSActions() function to find your custom method inside the controller then here is a way to make it work, which although certainly not the 'correct' way to do it, still does not require any editing of the core files and is not particularly messy.

Note. If anyone from SilverStripe is reading this (or anyone else who knows how these functions work), please oh please write some 'proper' documentation for us. I/we will be very grateful :)

So back to my way of doing this, first thing we need to do is add the form action to our page using the getCMSActions() function which many of you will have already had (probably frustrating) experience of. So inside your page model we add this:
function getCMSActions(){ $actions = parent::getCMSActions(); $Action = new FormAction( "doAction", "Do something different" ); $actions->push($Action); return $actions; }

Decorating CMSMain

Now we have our button you might have though adding the doAction() function would be a simple case of sticking it into our controller. Unfortunately not, for some reason this will give you an error, so instead we are going to add our function to the same place as the other CMS actions: inside CMSMain. However to avoid having to edit the core files we will use the LeftAndMainDecorator to do this. This works in exactly the same way as the DataObjectDecorator but, you guessed it, decorates LeftAndMain.

So create a new file inside mysite/code called CMSActionDecorator.php and put this code in it:
<?php class CMSActionDecorator extends LeftAndMainDecorator { function doAction(){ FormResponse::status_message(sprintf('All good!'),'good'); return FormResponse::respond(); } }

So all our doAction() function is going to do when run is show a green 'All good!' message at the bottom of the page. You can however put anything you like in here.

Something a little more useful

At this point you may be wondering how much use this is without having the currently selected pages ID. Well by adding $id = (int)$_REQUEST['ID']; to the top of this function we can then use DataObject::get_by_id() or similar to get the current page and work on it. For example say I wanted to create a button that deleted all the DataObjects attached to the current page I could change my doAction() function to something like this:
function doAction(){ $id = (int)$_REQUEST['ID']; $DataObjects = DataObject::get('SomeObject', 'PageID=' . $id); foreach($DataObjects as $DataObject){ $DataObject->Delete(); } FormResponse::status_message(sprintf('Deleted all objects' ),'good'); return FormResponse::respond(); }

Config settings

Finally we need to tell SilverStripe that we have extended CMSMain by adding this line to our mysite/_config.php:
Object::add_extension('CMSMain', 'CMSActionDecorator');

And there you have it, the hacky way to add form actions to your CMS pages. Wasn't all that bad was is? :)

Creating a Simple Contact Form

Sun, 03 May 2009 00:00:00 -0500

Preperation

We will be using 3 files in this tutorial, our Contact form page type, ContactPage.php and it's layout template ContactPage.ss as well as the email template ContactEmail.ss. Let's create these files and their initial code:

mysite/code/ContactForm.php
<?php class ContactPage extends Page{ } class ContactPage_Controller extends Page_Controller{ }

themes/yourtheme/templates/Layout/ContactPage.ss
<div class="typography"> <h2>$Title</h2> </div>

themes/yourtheme/templates/ContactEmail.ss
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> </head> <body> </body> </html>

Part I: Creating the Page Model

The first thing we need to do is setup the ContactPage model with database fields ($db) and CMS fields. For this tutorial we will keep it simple and add 2 fields, a MailTo field for the address to mail the contact form to and also a field for the text on submission of the form, which we'll call SubmitText. So add the following to your ContactPage class:

mysite/code/ContactForm.php
class ContactPage extends Page { static $db = array( 'Mailto' => 'Varchar(100)', 'SubmitText' => 'Text' ); function getCMSFields() { $fields = parent::getCMSFields(); $fields->addFieldToTab("Root.Content.OnSubmission", new TextField('Mailto', 'Email submissions to')); $fields->addFieldToTab("Root.Content.OnSubmission", new TextareaField('SubmitText', 'Text on Submission')); return $fields; } } . . .

Once done, flush your database by visiting yoursite.com/dev/build

Part II: Defining the Contact Form

Now let's actually create the fields for our contact form. Again we will keep it simple and add a Name, Email and Comments field, but you can add as many fields as you like without making the logic more complicated. To get SilverStripe to generate the form we need a function on our ContactPage_Controller class which will return the fields to the page template. We will call this function ContactForm(). A blindingly original name I know.

mysite/code/ContactForm.php
. . . class ContactPage_Controller extends Page_Controller { function ContactForm() { // Create fields $fields = new FieldSet( new TextField('Name', 'Name*'), new EmailField('Email', 'Email*'), new TextareaField('Comments','Comments*') ); // Create action $actions = new FieldSet( new FormAction('SendContactForm', 'Send') ); // Create Validators $validator = new RequiredFields('Name', 'Email', 'Comments'); return new Form($this, 'ContactForm', $fields, $actions, $validator); } }

The first thing we do is define the variable $fields which contains a FieldSet with our 3 fields in them.

Next we define the $action variable which creates a form action (i.e. the submit button) and assigns it the SendContactForm function which we will be defining in the next step. The second argument that the FormAction() function takes is the label for the submit button, in this case we are labeling it with Send but you can label yours with whatever you like.

We then set the required fields for the form, in this case all of them and store them in the $validator variable. Finally we return a new form using our predefined variables as arguments. Now when we call $ContactForm from the template, SilverStripe will place our contact form object in it's place.

Part III: Processing the Form Submission

Our Contact Form can now be drawn and submitted, but once submitted SilverStripe won't know what to do with it because we haven't defined a function to deal with it. The Submit Button we defined in the last step is going to look for a function called SendContactForm when it's pressed so let's define that function now inside our ContactPage_Controller class:

mysite/code/ContactForm.php
class ContactPage_Controller extends Page_Controller { . . . function SendContactForm($data) { //Set data $From = $data['Email']; $To = $this->Mailto; $Subject = "Website Contact message"; $email = new Email($From, $To, $Subject); //set template $email->setTemplate('ContactEmail'); //populate template $email->populateTemplate($data); //send mail $email->send(); //return to submitted message Director::redirect(Director::baseURL(). $this->URLSegment . "/?success=1"); } }

This function is pretty self explanatory, but let's go through it quickly. We pass in the $data variable which provides the function with the submitted form data so that we can process it. We then assign the relevant bits of data to variables ($From, $To and $Subject) before creating a new Email() object with these variables as arguments. Next we set the template for the email which is just the name of the Template without the .ss on the end. Then we simple pass our $data array into the populateTemplate() function so that we can use the data in our template by simply calling $Name , $Comments etc. You could also pass a custom array into this function if you needed to add other data beyond that submitted in the form.

Finally we send the email and return the user to the current URL + /?Success=1 which allows us to test whether the form has been submitted and if it has then display the SubmitText message instead of the form. To do this we need a function which will return true when Success is equal to 1. We can put in in the ContactPage_Controller under our SendContactForm() function It will look like this:

mysite/code/ContactForm.php
class ContactPage_Controller extends Page_Controller { . . . public function Success() { return isset($_REQUEST['success']) && $_REQUEST['success'] == "1"; } }

This function checks to see if success is set and whether it is set to 1, returning true if so. We can now use <% if Success %> in our template to add/remove content depending on whether the form has been submitted or not. This completes our php code so lets move onto the frond end templates.

Part IV: Email Template

Before we send the email in our SendContactForm() function we populate the template ContactEmail. Although the official SilverStripe documentation states that this template should go into mysite/templates/email/ I have found that it in fact only works when it's in your themes/yourtheme/templates/ folder. We need to create this template so that our email arrives with pretty HTML formatting. In the preparation we made the empty file with doc type and a <head> and <body> tags. We now need to add some CSS styling and the<body> content. This is very much down to how you want your email to look so just take this as an example, the only things which need to be the same are the names of the variables, which should match the names of the Form Fields defined in Part II, in this case $Name and $Comments.

themes/yourtheme/templates/ContactEmail.ss
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html> <head> <style> p{ font-size: 1.2em; color: #444; } p.comments{ font-size: 1.4em; color: #222; padding: 20px; } </style> </head> <body> <p>The following message was submitted to your site by $Name:</p> <p class="comments">$Comments</P> <p>You may respond by directly replying to this email.</p> </body> </html>

Part V: ContactPage Template

Finally we just need to define the template for our contact Page. using our Success() function we can use a conditional to decide whether to include the form of the SubmitText like this:

themes/yourtheme/templates/Layout/ContactForm.ss
<div class="typography"> <h2>$Title</h2> <% if Success %> $SubmitText <% else %> $Content $ContactForm <% end_if %> </div>

And that's it! You should now have a fully functioning contact form for your visitors to send you wonderful insightful and thought provoking messages to their hearts content!

Custom Login Form with Group Based Redirection

Tue, 07 Apr 2009 00:00:00 -0500

Preparation

We will be using 2 files in this tutorial: CustomLoginForm.php and GroupDecorator.php. Create both of these files in your mysite/code directory and fill them will the following:

mysite/code/GroupDecorator.php
<?php class GroupDecorator extends DataObjectDecorator { }

Mysite/code/CustomLoginForm.php
<?php class CustomLoginForm extends MemberLoginForm { }

Part I: Decorating

We need to add a couple of database fields to the group class as well as their corresponding CMS fields. First lets add our database fields:

mysite/code/GroupDecorator.php
class GroupDecorator extends DataObjectDecorator { function augmentSQL(SQLQuery &$query) {} public function extraStatics(){ return array( 'db' => array( "GoToAdmin" => "Boolean" ), 'has_one' => array( "LinkPage" => "SiteTree" ), ); } }

The first function "augmentSQL()" tells silversripe that it's going to need to add some new fields the existing table in the database.

The next function 'extraStatics' is where we define these new fields. Here we define a Boolean to use when deciding if we want our group to go strait to the admin area. We also define a new has_one relationship attaching a siteTree object to our group, which will be the page that we want to redirect to if our GoToAdmin value is false.

Next we want to add our CMS fields to the Group object so that we can select our page from a nice dropdown or check a checkbox to go strait to the admin area. We use a TreeDropdownField and a CheckboxField respectively.

mysite/code/GroupDecorator.php
class GroupDecorator extends DataObjectDecorator { . . . public function updateCMSFields(FieldSet &$fields) { $fields->addFieldToTab("Root.Members", new CheckboxField("GoToAdmin", " Go to Admin area"), 'Members'); $fields->addFieldToTab("Root.Members", new TreeDropdownField("LinkPageID", "Or select a Page to redirect to", "SiteTree"), 'Members'); } }

Note. Even though our has_one relationship was called “LinkPage” we call the TreeDropdown “LinkPageID” as this is what the column in the Group table will be called, as it is referencing a page in another table.

We now need to tell silverstripe to extend the group object with our decorator. We do this by adding the following line to our _config.php file.

mysite/_config.php
. . . Object::add_extension('Group', 'GroupDecorator');

Now if you visit www.yoursite.com/dev/build the fields will be added to the database. You can now see in the CMS under security that each group has a checkbox and a tree dropdown. However they don’t do a whole lot just yet.

Part II: Creating the Custom Login action.

Our new Loginform is going to be an extension of the MemberLoginForm which holds all of the login actions. We only need to overload (read create a new version of) the dologin() function, as this is the function that normally does the redirecting.

This is what our new function will look like:

Mysite/code/CustomLoginForm.php
class CustomLoginForm extends MemberLoginForm { public function dologin($data) { if($this->performLogin($data)) { if(!$this->redirectByGroup($data)) Director::redirect(Director::baseURL()); } else { if($badLoginURL = Session::get("BadLoginURL")) { Director::redirect($badLoginURL); } else { Director::redirectBack(); } } } }

First we try to perform the login by calling ($this->performLogin($data)), if we succeed then we move on, otherwise we check for a bad Login and if that returns false we just return the user back to where they were.

If our login was a success then we try to call our redirectByGroup() function (which we will write in a minute) from an if statement. If this returns false then we run the contents of the if and just direct to the base URL. Otherwise if it has returned true then it was run and we don't need to worry. In most cases (hopefully!) this is what will happen, but it's still essential to make sure there is a fallback just in case.

Now let's add our magic function that will redirect the user based on their group.

Mysite/code/CustomLoginForm.php
class CustomLoginForm extends MemberLoginForm { . . . . public function redirectByGroup($data) { // gets the current member that is logging in. $member = Member::currentUser(); // gets all the groups. $Groups = DataObject::get("Group"); //cycle through each group foreach($Groups as $Group){ //if the member is in the group and that group has GoToAdmin checked if($member->inGroup($Group->ID) && $Group->GoToAdmin == 1) { //redirect to the admin page Director::redirect(Director::baseURL() . 'admin' ); return true; } //otherwise if the member is in the group and that group has a page link defined elseif($member->inGroup($Group->ID) && $Group->LinkPageID != 0) { //Get the page that is referenced in the group $Link = DataObject::get_by_id("SiteTree", "{$Group->LinkPageID}")->URLSegment; //direct to that page Director::redirect(Director::baseURL() . $Link); return true; } } //otherwise if none of the above worked return fase return false; } }

So first thing we do is get the currently logged in user (i.e. the one that just logged in) followed by all the groups that exist.

We then cycle through each group checking whether the user is in any of them. If they are and that group has GoToAdmin checked then we go straight to the admin page. Otherwise if they are in the group and that group has a page relationship defined we get that page and link to it. If the user is not in any other the groups (very unlikely if not impossible), or the group they are in does not have a pageLink defined then we return false and the doLogin() function takes back control.

Finally we just need to tell SilverStripe to use our custom login class instead of the usual one. Again this is done in the _config.php file.

mysite/_config.php

. . . Object::useCustomClass('MemberLoginForm', 'CustomLoginForm');

That's it! You can now create user groups and choose which page they link to on login.

Limitations

If a user is in multiple groups the login will just redirect them to the first group it comes across with that member in. This will usually be the one with the lowest ID. You can manipulate this by reordering the $Groups array before cycling through it in the redirectByGroup() function.

Building a Theme from a Static Template

Thu, 26 Mar 2009 00:00:00 -0500

Preperation

The example template provided with this article was created using the CSS framework in this article and so is structured correctly for turning into a silverstripe theme. If this is the first time you are creating a SilverStripe theme we would recommend using this template as it will make following the tutorial a lot easier. However if you are using another template that is not structured in this way see the appendix for some things to look out for before starting.

To use the included template, download and extract the zip file attached above. Copy the brushedsilver folder into the themes/ directory of your SilverStripe install. We then need to tell SilverStripe to use this theme, which is done in the mysite/_config.php file. You will see a line setting the theme to blackcandy which we need to replace with the name of our theme. In this example our theme folder is called brushedsilver so we change this line in _config.php to:
SSViewer::set_theme('brushedsilver');

Part 1: Getting Started

The first thing we need to do is create a single theme template which we can then break down into smaller pieces. Create the file themes/brushedsilver/templates/Page.ss and copy the contents of themes/brushedsilver/index.html into it. We now have a static HTML template under a .ss file. It would still work in silverstripe but it would not create any dynamic content. This gives us some indication as to how flexible silverstripes templating system is, we can use as little or as much regular HTML as we like all the way to having a pure HTML page! Obviously we don't want that so lets start making our template dynamic.

The first thing to do is edit the <head> section. We need silverstripe to dynamically generate the meta-tags, the page title and also include any files we specify in our page controllers. Here is the same <head> section converted into a silverstripe template:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> <html xmlns="http://www.w3.org/1999/html" xml:lang="en" > <head> <link rel="shortcut icon" href="/favicon.ico" > <% base_tag %> <title>$Title - Your Site Name</title> $Metatags(false) <% require themedCSS(layout) %> <% require themedCSS(typography) %> <% require themedCSS(form) %>  </head>

So lets run through this. The first thing we do is include the <% base_tag %> and set the title to hold the variable $Title which will be replaced by the title of whichever page we are on. This is followed by $Metatags(false) which adds the meta-tags set. We add false to this so that SilverStripe does not include the page title twice. If we wanted our page title to be independently set for each under the meta-data tab in the CMS, we could set this to true and delete the <title> tag. SilverStripe would then include the entire title line for us, but we would not be able to set a persistent part of it like the name of our site.

We then just add <% require themedCSS() %> tags for each of our CSS files and adjust the IE6 conditional path to be relative to the root of the site. And thats it, our <head> section is now ready for SilverStripe's dynamic magic.

Part II: Top Level Navigation

The navigation in the satic HTML is in the form of an unordered list. We are going to emulate this structure using a SilverStripe control loop which will loop over the top level pages allowing us to create a new list item and link for each one. It looks like this:
<body> <div id="container"> <div id="navbar"> <a class="home" href="" title="go to home"><span>Home</span></a> <ul> <% control Menu(1) %> <li> <a class="$LinkingMode" href="$Link" title="Go to $Title">$MenuTitle</a> </li> <% end_control %> </ul> </div>

The control loop <% control Menu(1) %> tells SilverSripe to loop through the pages in the top level menu, creating whatever HTML is between this starting control and the <% end_control %> for each one. So in this case we create a <li> followed by a <a> and then a closing </li>. Within the <a> we use a few SilverStripe variables, namely $LinkingMode, $Link, $Title and $MenuTitle. The key to understanding how this works and how control loops work in general is understanding that within this control loop you are in the context of whatever item is being looped through, in this case pages in the top level of the site tree. So when we loop through and use the $Link variable in the href, SilverStripe inserts the link to the page whose context we are currently in. Likewise for $LinkingMode, $Title and $MenuTitle, while outside the control we would be getting the values from the actual page we are on, inside it the values returned are of the items in the loop.

$LinkingMode inserts a class based on whether the link we are creating is for the current page or whether the current page is a child of this link. This way we can style a.current and a.section to be highlighted to show the user they are on that page or in that section.

For more information on the built in variables and functions you can use in a template see this page: http://doc.silverstripe.com/doku.php?id=built-in-page-controls.

At this point, have a look at your page. You will notice the header image not showing as we havn't adjusted the path yet, but also notice that the top level navigation is now generated from your silverstripe site. Remember that you will need to add ?flush=1 to the end of your URL each time you want to see changes made to a template. This makes sure SilverStripe clears its template cache before rendering the page. It's also worth disabling or clearing your browsers cache to avoid any confusion. If your using firefox you can download the Developer Toolbar that has a "disable cache" button among numerous other useful tools.

Part III: Layout Section (Content and Sidebar)

Now lets get onto the main section of our page, otherwise know as the 'Layout'. The Layout is the section of the page that changes between different types of page, so later on we will be stripping this out of our page and placing it in it's own file so that we can vary the look of our pages without having to have completely new templates. Before we do that though we want a completely working page.

First part is the banner image and the sidebar. For the banner image we just need to make the path to the image relative to the root. For the sidebar we use a control loop identical to the one we used for the top navigation, only this time we call Menu(2) instead of Menu(1).
<div id="layout"> <img id="headerImage" src="themes/brushedsilver/images/header_color.jpg" mce_src="themes/brushedsilver/images/header_color.jpg" alt="header Image"> <div class="typography"> <div id="sidebar"> <div class="sidebarBox"> <h3>$Level(1).Title</h3> <ul id="menu2"> <% control Menu(2) %> <li> <a class="$LinkingMode" href="$Link" mce_href="$Link" title="Go to $Title">$MenuTitle</a> </li> <% end_control %> </ul> </div> </div>

The only extra thing to notice here is that we use the variable $Level(1).Title for our sidebar's header. This is a shorter way of writing <% control Level(1) %>$Title<% end_control %> which is just as good because we don't need to loop through multiple items, just jump to the top level page of this section and grab its Title.

Next up is the actual content area. This is really quite simple as all we need to do is insert our $Content variable along with the $Form (for the login form etc.) and $PageComments (for pages where comments are enabled in the CMS) and then make sure our typography, layout and container divs are closed. We also want to get our breadcrumbs in there which is as simple as using $Breadcrumbs. Gotta love SilverStripe :)
<div id="content" > <div id="Breadcrumbs"> <p>$Breadcrumbs</p> </div> $Content $Form $Pagecomments </div> </div> </div> </div>

Part IV: The Footer

There's not a whole lot to our footer, and even less that needs to be dynamic. We will however add a nifty variable to make the copyright year dynamic. $Now.Year will return the current year, so we can just stick that strait into our template. Alternatively if we want something like 2009 - {year} we can use the dynamic year function in this post. For this example well just use the $Now.Year variable:
<div id="footer"> <div class="footerContent"> <p>© YourCompany $Now.Year | Provided by <a href="http://ssbits.com">SSbits.com</a></p> </div> </div> </body> </html>

Well that wraps up our generic template, but at the moment it's just in a single file which means if we wanted a page without a sidebar for example we would have to make a whole new template. But as usual SilverStripe provides an elegant solution to this situation.

Part V:Creating the Layout Template

We need to strip out our layout section and place it in its own file so that we can create 'Layouts' for each page type we need. So first cut everything within the <div id="layout"> </div> tags pasting it into a new file themes/brushedsilver/templates/Layout/Page.ss and replacing it in the main template with $Layout like so:

<div id="layout"> $Layout </div>

Now when SilverStripe draws a page it first grabs the main template from themes/brushedsilver/templates/Page.ss and when it encounters the $Layout variable it looks in the templates/Layout/ folder for a layout which matches the name of the current page type. If it can't find one or the current page type is Page then it just uses themes/brushedsilver/templates/Layout/Page.ss. It then resumes drawing from the main template for the footer etc.

Part VI: Creating the Includes

We can also take this a step further and remove some things from our Layout template so that we can then re-use them in other templates. Let's remove the sidebar and the breadcrumbs. Create two files in the themes/brushedsilver/templates/Includes/ folder, Sidebar.ss and Breadcrumbs.ss. Cut everything inside and including the <div id="sidebar"> </div> and paste it into Sidebar.ss. Now we can simply replace it with an <% include %> tag, as well as introducing a condition to decide whether we add it to our template or not:
<% if Menu(2) %> <% include Sidebar %> <div id="content"> <% end_if %>

What we are doing here is testing to see whether there is a second level menu to display and if there is we add our sidebar and our <div id="content> which limits the size of our content area. Otherwise we just leave the sidebar out all together and let the content fill the whole page.

Note. we are moving the <div id="content> to be inside this conditional statement, so if you copied and pasted the code above make sure you don't have another content div below it.

We can do a similar thing with our breadcrumbs so that they are only displayed if we are on the second level. Cut the contents of and including the <div id="breadcrumbs"> </div> and paste it into the Breadcrumbs.ss file. In its place put this code into themes/brushedsilver/templates/Layout/Page.ss <% if Level(2) %> <% include Breadcrumbs %> <% end_if %>

This code has a subtle difference to the one we used for the sidebar. In our If statement we use Level(2) instead of Menu(2). The difference here is that with the breadcrumbs we only want to display them when the user is actually on the second level or greater, while with the sidebar we want to show it on the first level only if a second level exists.

This proccess of separating page elements into Includes is good practice that we recommend repeating for the Footer and Header sections as well as any custom blocks you use repeatedly in your templates.

So that pretty much wraps up the tutorial. You should now have a fully fledged SilverStripe theme that can be extended as you create new page types with different data. The key thing to realise is that SilverStripe's templating system is not only very simple for non-programmers to understand but it is also unobtrusive and allows you to build your templates in a fashion very similar to those of a static HTML page.

Appendix

Sometimes you may want to use a template that was created by somone else who did not have SilverStripe in mind. Here are a few pointers to preparing it for conversion into a SilverStripe theme.

Use the blackcandy theme bundled with SilverStripe as a guide to the file structure of a theme. All your files should be in one folder with the name of your theme, containing three folders: css, images and templates. The templates folder should then contain two folders: Layout and Includes. Place all your images in the images folder and all your style sheets into the css folder.
Although not essential it's good practice to separate layout, typography and form CSS into their own files. This makes editing easier as well as encouraging re-use in later projects.
If you are using active states for navigation buttons so that they are highlighted if you are on that page check to make sure they are using the correct CSS selectors. Silverstripe uses .current and .section classes, returned when using the $LinkingMode variable.

Create a Static, CMS editable sidebar

Tue, 24 Mar 2009 00:00:00 -0500

Preperation

We need to create 2 new files for this tutorial, one for the php (Model & Controller) called StaticSidebar.php and another for the template (View) called StaticSidebar.ss.

You can leave StaticSidebar.ss blank for now, but inside StaticSidebar.php add the following:

mysite/StaticSidebar.php
<?php class StaticSidebar extends Page { } class StaticSidebar_Controller extends Page_Controller { }

Part 1: Setting up the model

Our static sidebar is going to have an external link (TextField), and internal link (SitetreeDropdownField) and an Image as well as using the pages default Content (HTMLEditorField) for its HTML text. So lets add our database model to the class.
class StaticSidebar extends Page { static $db = array( 'ExternalLink' => 'Text' ); static $has_one= array( "Image" => "Image", "InternalLink" => "SiteTree" ); }

Now lets add the CMS fields so that we can edit the sidebar:
class StaticSidebar extends Page { public function getCMSFields() { $fields = parent::getCMSFields(); $fields->addFieldToTab("Root.Content.Main", new TextField("ExternalLink")); $fields->addFieldToTab("Root.Content.Main", new TreeDropdownField("InternalLinkID", "InternalLink", "SiteTree")); $fields->addFieldToTab("Root.Content.Main", new ImageField("Image")); return $fields; } }

Note. Even though our has_one relationship was called “InternalLink" we call the TreeDropdown “InternalLinkID” as this is the column in the StaticSidebar table that it needs to save it's contents into. This is a slight inconsistency with Silverstripe, as we don't need to call our ImageField 'ImageID' even though it is the same principle.

The last thing to do is to add a line which stops the user creating children under our sidebar and also setting the default for 'ShowInMenus' to be false so that our sidebar page doesnt show up as an actual page on our site.
class StaticSidebar extends Page { . . . static $allowed_children = array("none"); }

Now run yoursite.com/dev/build (in 2.2X run yoursite.com/db/build?flush=1). You will see the new fields being added and you can now log into the

Part II: Creating the Template

We are going to intergrate our sidebar into the default blackcandy theme, but it should be an almost indentical process to add it to your theme, just apply your own structure to it. You could also just as easily make it part of the footer, header or any other part of the page you fancy as we havnt actually defined anything that says where the information stored in the model needs to be on the page. Silverstripe gives up total freedom.

For our tempalte we can just copy and adapt the existing Sidebar template found in themes/blackcandy/templates/Includes/Sidebar.ss. minus the outermost div (id="Sidebar"). So copy and paste that into our StaticSidebar.ss file we created earlier and make it look like this:

themes/blackcandy/templates/Includes/StaticSidebar.ss
<% if GetStaticSidebar %> <% control GetStaticSidebar %> <div id="Sidebar" class="typography"> <div class="sidebarBox"> <h3>Static Sidebar</h3> <ul > <li><a href="$ExternalLink" title="Go to ExternalLink">External Link</a></li> <li><a href="$InternalLink.Link" title="Go to InternalLink">$InternalLink.MenuTitle</a></li> <li>$Image.SetWidth(180)</li> <li>$Content</li> </ul> <div class="clear"></div> </div> <div class="sidebarBottom"></div> </div> <% end_control %> <% end_if %>

So first up you will notice that we are calling a function 'GetStaticSidebar'. We havnt created this function yet, we do that in the next part, but all it does is return our StaticSidebar page so that we can use the data held in. So we first check if our StaticSidebar exists and if it does we enter a control context for it, allowing us to use all the variables first hand (i.e. $Image instead of $GetStaticSidebar.Image).

Then we remove the outermost div so that we dont't get 2 #sidebars and then just use the unordered list (<ul>) and enter each item as a list item (<li>). We use $InternalLink.Link because $InternalLink on it's own returns the actual page that we are linking to where as we want the link to that page in the same way as we use $Link in our menus. We use the same method to get the pages title, $InternalLink.MenuTitle. We also set the image to be 80px wide by calling $Image.SetWidth(80).

part III: Adding it to our Page

Finally we just need add the sidebar to our page template and create the function that will return our StaticSidebar for use in all our pages. Because we want to use it accross the whole site, it makes sense to put this function in the Page_Controller so that all our pages that extend Page will have access to this function. In the case of the blackcandy theme we need to add our sidebar underneath the existing menu(2) sidebar. To do this we will include our template in the Sidebar.ss file which is in turn included in our Layout/Page.ss template. We then need to make some slight alterations to the <% if %> block which surrounds the Sidebar include as we now want to draw the sidebar even if there is no level 2 menu to display.

So first lets add the function to our Page.php file:

mysite/Page.php
<?php class Page extends SiteTree { . . . } class Page_Controller extends ContentController { . . . public function GetStaticSidebar(){ return DataObject::get_one("StaticSidebar"); } }

All this function does is grabs the first StaticSidebar it can find and returns it. This is all we need as there will only be one of these sidebars in the site. If you need to have more then one, you will need to create a function which can filter the result based on a parameter that you define. So for example calling <% GetStaticSidebar(right) %> might use a function that has the database call DataObject::get("StaticSidebar", "Type = $Side"), where $Side is the variable passed into the function (in this case "right").

Finally we need to include our StaticSidebar.ss tempalte in the Sidebar.ss template and then make some slight alterations to the Layout/Page.ss template to ensure the Sidebar.ss is always included. So open up Includes/Sidebar.ss and make the following changes:

themes/blackcandy/templates/Includes/Sidebar.ss
<div id="Sidebar" class="typography"> <% if menu(2) %>  <div class="sidebarBox"> . . . <div class="sidebarBottom"></div> <% end_if %>  <% include StaticSidebar %>  </div>

Now we just need to remove the if statment from our Layout/Page.ss:

themes/blackcandy/templates/Layout/Page.ss
<div class="typography">  <% include SideBar %> <div id="Content">  . . .

Remember you will need to add the <% include Sidebar %> to all your new Layout files if you want any sidebar on those pages.