SSbits - Home page
Site by Carbon Crayon
Submit a Post >

Tutorials - Big bits of code to help you do more

Adding Custom Filterable Reports to ReportAdmin

ReportImage

 Source files (2.1 KB)

With only the standard Broken Links Report, the report admin area in Silverstripe's CMS can feel a bit underused.  In this tutorial I'm going to take a look at how you can add a custom report into the report admin section of the CMS which can make keeping track of a variety of statistics a little more straightforward.

To keep this simple I am going to give users the ability to assign a colour to each page on the site and then generate a report of any pages on the site that have been assigned a particular colour.

Setting Up

First you need to add an Enum storing some colours to the Page class and add a new dropdown field to allow the user to select the colour on each page.

mysite/code/Page.php 

class Page extends SiteTree {

	public static $db = array(
		'Colour' => "Enum('Red, Blue, Green', 'Green')"
	);

	...
	
	public function getCMSFields() {
		$fields = parent::getCMSFields();
		
		$colourValues = $this->dbObject('Colour')->enumValues();
		$fields->addFieldToTab("Root.Content.Main", new DropdownField('Colour', 'Choose a Colour', $colourValues));
		
		return $fields;
	}

}

This should be pretty straightforward, a new Enum field, Colour, is added to the database with a selection of possible options.  You can then use the enumValues function to generate a dropdown friendly list of colours that are added to a new dropdownField in the CMS.

 

Creating the Report

Now that each page can have a colour assigned to it we can get down to creating the report itself.  First create a new file, lets call it PageColourReport.php, and set up the new class.

mysite/code/PageColourReport.php 

class PageColourReport extends SS_Report 
{
	function title() 
	{
        	return "Page Colour Report";
	}
	
	function sourceRecords($params, $sort, $limit) 
	{	
	}
	
	function columns() 
	{	
	}
	
	function parameterFields() 
	{	
	}
}

The new PageColourReport class will need to extend the SS_Report and will require the 4 functions title, sourceRecords, columns and parameterFields. The title function is pretty self explanatory, simply returning a title for the report, so I have already filled it in above.

Next you will need to add any required filters to the report.  This can be done by completing the parameterFields function.

mysite/code/PageColourReport.php

function parameterFields() 
	{
		$params = new FieldSet();
		
		//Colour filter
		$colours = singleton('Page')->dbObject('Colour')->enumValues();
		
		$params->push(new DropdownField(
			"Colour", 
			"Colour", 
			$colours
		));

		//Result Limit
		$ResultLimitOptions = array(
			50 => '50 Pages',
			100 => '100 Pages',
			200 => '200 Pages',
			500 => '500 Pages',
			Null => 'All Pages'
		);
		
		$params->push(new DropdownField(
			"ResultsLimit", 
			"Limit results to", 
			$ResultLimitOptions,
			50
		));
				
		return $params;
	}	

As you can see 2 filters have been added to the report; one to choose which colour of page the user wants to review and a second that will allow them to limit the number of pages that will be returned.

For each of the filters I have generated a DropdownField which is pushed onto the $params FieldSet to be returned.  I have opted to generate the Colours list dynamically from the Colour Enum that was created on the Page class and to hard code a set of result limits in an array; depending on what you are reporting you might want to take a look at some other methods of populating dropdown menus.

 

sourceRecords is the function that will actually build the list of pages to be shown to the user.

mysite/code/PageColourReport.php

function sourceRecords($params, $sort, $limit) 
	{
		if(isset($params['Colour']))
		{
			$Pages = DataObject::get("SiteTree", "Colour = '" . $params['Colour'] ."'", "Created DESC", Null, $params['ResultsLimit']);			
			return $Pages;
		}
	}

First you need to check if a colour has been selected by checking if the $params['Colour'] has been set.  If it has then you can get a list of all the pages on the site where the assigned Colour matches the one chosen in the filter.  You can then also override the limit with $params['ResultsLimit'] and then return the list of matching $Pages.

 

The last function to create is columns.  This function is used to dictate what information should be displayed to the user in the report and to specify the format that it should take.

mysite/code/PageColourReport.php

function columns() 
	{
		$fields = array(
			'Title' => array(
				'title' => 'Page name',
				'formatting' => '<a href=\"admin/show/{$ID}\" title=\"Edit page\">{$value}</a>'
			),
			'Created' => array(
				'title' => 'Created',
				'casting' => 'SS_Datetime->Full'
			),
			'LastEdited' => array(
				'title' => 'Last Edited',
				'casting' => 'SS_Datetime->Ago'
			)
		);
		return $fields;
	}

The chosen fields need to be returned in an array that specifies the name of the field and, in another array, states how the field's information should be displayed.

 As you can see above I have have specified that the Title field should be displayed with the title "Page Name" and the formatting has been adjusted to wrap it in a link to directly edit the page.  The Created and LastEdited fields are also to be displayed and casting has been used to display the dates in a neater format than the default.  For Created SS_Datetime->Full is used to display the date in a day month year format while LastEdited uses SS_Datetime->Ago to state how long has passed since the last edit was made to the page.

Now that the 3 functions have been filled in the work on the PageColourReport class is complete.

 

Finishing Up

Finally you need to remember to let silverstripe know about the new report by adding the following line to your _config.php file.

mysite/_config.php

SS_Report::register("ReportAdmin", "PageColourReport");

Then you can run a quick dev/build, add a few test pages to the site and then take a look at the report in the report admin section.

 

 

Craig Ballantyne avatar

Craig Ballantyne

Craig is a developer working at London based agency Aab Web, who run SSBits and specialise in building attractive, usable sites around the SilverStripe CMS and Framework.

  • Matt Clegg
    07/10/2011 1:52pm (3 years ago)

    nice, good work

  • Mark M
    11/10/2011 2:34pm (3 years ago)

    Craig,

    Perfect timing ! Just been going through the Report process and now have a handy page to reference when needed...

  • MRKDevelopment
    20/10/2011 7:35am (2 years ago)

    wow, another great tutorial. You guys rock and have really helped me out with this one.

  • Peter Toi
    20/10/2011 9:19pm (2 years ago)

    Thanks Craig,

    I've always glossed over the Reports section of SilverStripe CMS in the past. Now that I have an easy tutorial to follow I might just start building out this feature further.

    Best, Peter

  • Paltat
    24/10/2011 12:20pm (2 years ago)

    Nice tutorial! I look forward to more advanced techniques of using the SIlvertripe's Report admin.

  • Wade
    27/10/2011 2:17pm (2 years ago)

    Great Tutorial guys,

    But i have been wondering if it is possible to place a button at the bottom that lets the user print the report?

    Any ideas would be great.

    Thanks
    Wade

  • SamTheJarvis
    29/10/2011 7:17pm (2 years ago)

    Great, this is just what the community needed, I couldn't find anything on Report Admin.

  • lx
    09/12/2011 1:14pm (2 years ago)

    if you fix a small bug in /cms/code/Report.php (SS2.4.6) line 178,179: $this->description() instead of $this->description

    then you can also add a description to your report.

    function description() {
    return "This is a very important report.";
    }

  • Robert
    25/01/2013 7:03am (1 year ago)

    Really helpful ... thanks for another great tutorial ...

Post a comment ...

You cannot post comments until you have logged in. Login Here.

Advertisement

Site of the Month

Find SSbits on

Top Contributers

Rank Avatar Name
1 article image Aram Balakjian
2 article image Daniel Hensby
3 article image Marcus Dalgren
4 article image Hamish Campbell
5 article image Ty Barho
6 article image njorndare
7 article image Martijn van Nieuwenhoven
8 article image Darren-Lee
9 article image Roman Schmid
10 article image Matt Clegg

View full leaderboard


Advertisement