Mar 10, 2012

Custom Block Views with Custom Attributes in C5

One of the things most commonly missed in the C5 community is custom block views.  I’ve already written a number of articles talking about this. But you never can have to many!  

In this go at it, I’m going to delv in some more common and practical uses of custom block views, and even custom attributes.

If you don’t already have a copy of ProEvents, you may want to go grab one, although you can walk through this tutorial using just the page properties pane.

We are going to take a look at:

• create a custom attribute to collect information and assign it to a page
• learn how to make a quick and dirty block
• learn how to make a custom block view of a package block
• pull our custom attribute and display it.
• implement a simple jQuery addon in our custom view.

These topics cover a broad range of common needs.  And we are going to make it simple!

Getting Started

First thing I want to do is establish the information I want to use for my attribute. I’m wanting to show an additional “promoters” badge attached to events.  If it’s present, show it. 

So I’m going to head to my dashboard->pages & themes->attributes area and create a new “image” attribute called “promoter_image”.  Since this is an events driven example, I want to assign this new attribute to the “Pro Events Additional Attributes” attribute set so that whenever my client is adding a new event, this promoter attribute is right there in the add event page.

Go ahead and create a page or two , or events in ProEvents, and be sure to add an image for the promoter, and place the page under a parent “events” page.

The Quick And Dirty (skip this if you do not want to learn more about objects)

What I’m going to demonstrate is actually a neat way to learn and grow in your understanding of C5’s base objects believe it or not.  The quick and dirty is not the preferred way to do things, but sometimes is handy if you need additional filtering or sorting other than what is provided in the standard list blocks.  To do this technique using the page_list block is actually NOT a good way to approach things simply for the fact that it is outputting a list of pages already. So should you need to “re-build” that list, you are making the system do twice the work for one task.  So sometimes, it’s best to just build a one off and get your results.  Enough disclaimers...moving on.

First, make a new custom block view of the html block in your root/blocks/html/templates/yourtemplatename/view.php

Open up your new html block template view.php file, and lets grab our page list.

<?php
defined('C5_EXECUTE') or die("Access Denied."); // permissions
Loader::model(‘page’); //load in the page model
Loader::model(‘page_list’); //load in the page_list model
$pl = New PageList();
?>

Right now, we officially have a page_list “object”.  An object is not to be confused with a list of pages at this point.  This object instead is a pre-database build of a “query” that will eventually go GET the list of pages using the get() command. For now though, we just want to make sure we are only grabbing what we need.

Next, we want to filter out our pages by parent page.  Because we know where we put our events (under the event page), we can just grab it’s id by path and only grab pages underneath it like so:

<?php
$pp = Page::getByPath(‘/events’); //grab the parent page
$pl->filterByParentID($pp->getCollectionID()); //filter by that page
?>

 

Lastly, we want to go grab our event pages and assign them to the $events var like so:

<?php
$events = $pl->getPage();
?>

Now we have an array of event objects that we can loop through.

Something to the effect of:

<?php
if(is_array($events)){
	foreach($events as $event){
		echo ‘<h4>’.$event->getCollectionName().’</h4>’;
		echo ‘<strong>’.$event->getCollectionDatePublic().’</strong><br/>’;
		echo ‘<p>’.$event->getCollectionDescription().’</p>’;
	}
}
?>

Now you can add the html block, and load up your new custom template. 

Making Custom Block views of Package Blocks (requires ProEvents)

Before we move on to grabbing our promoter image, lets make a quick custom block view of the pro_event_list block.

Why not just edit one of the views provided?  Because the second you update your ProEvents, you lose any changes you have made. C5 has a built in way to prevent this. Lets take advantage of that.

Copy the contents of the main pro_event_list view.php file in /packages/proevents/blocks/pro_event_list/  over to   /root/blocks/pro_event_list/templates/this_week_custom.php and save.

PROTIP:  ProEvents has a really cool naming convention system that automatically pulls the correct base list for you to work with.  So a template with the name “week” pulls in the next 7 days of events.  A template containing the name “this_week” pulls from Sun to Sun of the current week regardless.  And then likewise, month pulls this month, and day pulls today.  So when making ProEvent custom views, the name decides what span of events to pull.  pretty cool!

Add your block and change the custom template to your new view.

The Events Loop

Regardless of weather you are using the Quick and Dirty or a custom ProEvent List view, we need to enter into the loop and add in our promo image!  The technique will look the same for both.

Typically any page_list loop will be pretty obvious to even the novice as it’s the only thing on the page starting with “foreach(X as Y){ “ syntax.

Also common among any page_list loop is the assignment of data or vars just inside were the loop starts.

What this means is that for each time the loop is cycling through the array, it’s going to do XYZ to that item.

PROTIP:  Although we are working with an array, it is actually an array of OBJECTS.  Think of an object as a “container” of data similar to an array, but providing access to methods and functions related to that object. When you see the rocket symbol ( -> ) this is an indicator of using a function related to that object type.

For our promoter example, I intentionally used a more complex use case.  Images.  

Images require a couple extra steps: Load in the image helper, call the image attribute value, grab the images thumbnail via the loaded helper.

<?php
$image = null; //for each event, blank image.
$imgHelper = Loader::helper('image');  // load in the helper 
$imageF = $event->getAttribute('promoter_image'); //grab the attribute value
if (isset($imageF)) { //check for valid object
    	$image = $imgHelper->getThumbnail($imageF, 120,100)->src; //get the thumb
} 
?>

That’s it!  We now have a var $image that has a src value that we can print elsewhere in  our loop.  Now anywhere further down within the loop, we can print this out as html like so:

<?php
if($image){
	echo ‘<img src=”’.$image.’” alt=”promoter image” />’;
}
?>

Not to bad! 

Regular attributes (exempt the select attribute) are very straight forward.  A text attribute would simply be shown like so:

<?php
$my_text = $event->getAttribute(‘my_text’);
echo ‘<p>’.$my_text.’</p>’;
?>

Much more simple!

blog comments powered by Disqus