DataObject as Pages: The Module

Tweet

24 January 2012 | Aram Balakjian | DataObjects, Model Admin, Controllers, Search

29 15

 Source files  Demo (admin/pass)

It's been a while since we published the DataObject as Pages series of tutorials, which have proved to be particularly popular. At Aab Web we use those techniques regularly as a way to allow our clients to mange large amounts of flat content or content that is distributed in multiple places throughout a site. Although the final implementations in each project are often varied and bespoke, they all start with the basics outlined in those tutorials, so it made sense for us to build a starting point to work from (and include some more complex features at the same time). That starting point is this module, catchily entitled: DataObject as Pages.

About the Module

Get the Module on Github: DataObjects-as-Pages: The Module

So first things you are probably wondering is 'what can I do with this module'. Well once you have extended the classes in the Module you will have a fully functioning DataObject as Page system with

Features

• Basic Versioning, with Stage & Live versions of each Data Object, managed in Model Admin.
• Searchable DataObjects, allowing instant implementation into a search dependent site using the DoapSearchForm and Controller.
• Fully extendable listing page type, allowing implementation of filtering systems and tags/category models
• Easy implementation: Simply extend the 3 classes, add a couple of static values and you are ready to go!
• URLSegment based DataObjects with MetaTitle and Description built in.

So without further ado, you can grab the code from the module here: https://github.com/arambalakjian/DataObjects-as-Pages and then follow the instructions below, where we'll first take you through the most basic implementation, then show you how you can extend it to do some really cood things, like we did on www.mymuswell.com, where all the Articles, Places, events and Deals are based on DataObjects.

Basic Setup

Ok, so you probably want to just get going with this so you can have a play around. We'll here are the 3 files you need to create, just like when doing the Part 2 tutorial, only this time without any actual logic!

mysite/code/ProductListingPage.php (Extends DataObjectAsPageHolder

 

class ProductListingPage extends DataObjectAsPageHolder 
{

}

class ProductListingPage_Controller extends DataObjectAsPageHolder_Controller 
{
	//This needs to know be the Class of the DataObject you want this page to list
	static $item_class = 'Product';
	//Set the sort for the items (defaults to Created DESC)
	static $item_sort = 'Title ASC';
}

mysite/code/Product.php (Extends DataObjectAsPage)

class Product extends DataObjectAsPage 
{
	//The class of the page which will list this DataObject
	static $listing_class = 'ProductListingPage';
	//Class Naming (optional but reccomended)
	static $plural_name = 'Products';
	static $singular_name = 'Product';
}

mysite/code/ProductAdmin.php (extends DataObjectAsPageAdmin)

class ProductAdmin extends DataObjectAsPageAdmin {
   
	public static $managed_models = array(
		'Product'
	);

	static $url_segment = 'products';
	static $menu_title = 'Products';
}

And that's it! You now have a fully functioning, versioned, searchable DataObject as Page implementation! You can now carry on as normal and add all the fields you want to Product, implement your templates (see below) and see where you can take it.

Templates

You will see there are 2 very basic templates provided with the module, DataObjectAsPageHolder.ss and DataObjectAsPageHolder_show.ss. These are just to get you started but should show you how to setup your own. The modules show function makes use of SilverStripes automatic template finder which follows the naming convention [PageClass]_[action].ss. So for this module our [action] is 'show' meaning we just need to add a second template with _show on the end of our standard template for displaying the DataObject detail page.

Following this logic, if we wanted to create a template for our Products in the code above, we would have the following:

themes/mytheme/templates/Layout/ProductListingPage.ss (the page to list all the Products)

<div class="typography">
	
	  	<% include BreadCrumbs %>
		
		<ul>
		<% control Items %>
			<li>
				<h2>$Title</h2>
				<p>$Content.FirstParagraph</p>
				<a href="$Link">View</a>
			</li>
		<% end_control %>
		</ul>
</div>

<% control Items %> is used to cycle through the DataObjects which are being listed on this page. If you check the 'Use Items as children' under the Behavior tab of the Listing Page, the items will also be returned as <% children %>, allowing you to include them in Menu's etc. You can also pass in an arberary limit to Items(), for example <% control Items(5) %> would give you the first 5 products.

themes/mytheme/templates/Layout/ProductListingPage_show.ss (the actual product page)

<div class="typography">

	<div id="Breadcrumbs">
		<p>$Breadcrumbs</p>
	</div>
		
	<% control Item %>
		<h2>$Title</h2>
				
		$Content
	<% end_control %>

</div>

On this page we use <% control Item %> to go into the current DataObject and display it's data, in this case just the default $Title and $Content.

Extending the Listing Page to do Fancy things

The Listing page is really the core of the module. It fetches and displays the relevent DataObjects and it's here that you can start extending in order to gain more control over how those DataObjects are returned by the Items function. We have built the module to allow you to extend the Listing Page functionality without having to re-write the core functions (in most cases). Primrily this section focuses on the functions you can use to manipulate the DO's that are retreived, but in a future tutorial we will look at creating specific functionality such as a URL based filtering system.

Pagination

Pagination is built into the Module, and enabled by default. You can find the options to change the page size and disable it under the Behavior tab of your listing page, along with the switch to return your Items as Children of the listing page.

 

Manipulating the WHERE

	/*
	 * Overload the SQL WHERE builder
	 */
	public function getItemsWhere() 
	{
		//Use this function to return a custom filter to the Items() function
		return "Date > CURDATE";
	}

By adding a getItemsWhere() function to your ListingPage_Controller, you can manipulate the Where statement that is used when collecting all the DataObjects to list on this page. This allows you to build filtering into your page, dynamically adding extra conditions to the SQL. As a basic example you could return Date > CURRDATE(); if your DataObject had a Date field and you only wanted to show DataObjects where this date was after today.

 

Manipulating the Sort Order

As well as using the static $item_sort as detailed above, there is also a function which you can use to set the sort more dynamically:

	/*
	 * Overload the Sorting of Items
	 */	
	function getItemsSort()
	{
		return "MyField DESC";
	}	

Manipulating the Join

	/*
	 * Overload the Join builder
	 */	
	function getItemsJoin()
	{
		return [JOIN STATEMENT];
	}

Pretty self explanitory, but here you can add a join to the SQL in the Items() function, so if you needed to filter on a related objects field, you could add the filter in the getItemsWhere() function then return the required Join here.

 

So there you have it, the first release of what will hopefully prove to be a useful module. Obviously it's in it's early days so if anyone has any suggestions as to how to improve it please let us know!