One of the nice things about an open source CMS project is it moves really fast and it isn’t afraid to make big changes. Such is the case with PyroCMS, and the upcoming 2.0 release is a case in point. With PyroCMS 2, we get a whole new back end interface and some more back end tools for developing great add-ons.

So, if you happen to develop add-ons for PyroCMS, you’ll need to do a little bit of work to make sure your shit don’t break. Here are some tips to get your stuff working on PyroCMS 2 in no time.

A Word on Standards

With PyroCMS, I’ve thrown my hat into the ring to try and nail down some standards about how UI conventions should be used. You can find the running document here. Some of them are common sense, but I highly recommend following these as much as you can to create a smooth UI experience across modules. If you have any questions, let me know on Twitter.

The New Interface

PyroCMS 0.x used an off the shelf admin interface, and then 1.x used an interface that was apparently designed by Dan Horrigan. I’m not even going to ask how that happened. Anyways, it was fine, but it had a vertical nav system that is so 2004 and took up too much screen real estate.

Luckily, the man behind the design of the PyroCMS and FuelPHP websites, Scott Parry, has undertaken getting an admin interface going. It’s really fantastic. Based off of his Workless framework, the new interface is colorful, flexible, and easy to implement.

Upgrading to the new interface is pretty easy, so let’s start with your view code. Here’s a quick comparison of a typical page:

// PyroCMS 1.3.x and below:
 
<h3>Your Title</h3>
 
<table>
// Table Content Here
</table>
 
// PyroCMS 1.4
 
<section class="title">
<h4>Your Title</h4>
</section>
 
<section class="item">
<table>
// Table Content Here
</table>
</section>

If you are not familiar, that is the HTML5 section tag that we are rocking. Yes, it is more markup, but it allows you to easily define a box of content on the backend – header and body.

The new interace is made up of these blocks, and beyond that, almost all of your current view code should work, including tables and other basic markup.

Buttons

We get to have some fun with buttons in PyroCMS 2. Workless comes with some shiny buttons that make the interface a little more fun. They come in two varieties: primary and secondary. Primary buttons take a class of “btn” and can have a color as a class (red, blue, gray, orange, green). So, for example:

<button class="btn blue">Save</button>

Luckily, PyroCMS has a button partial that you can pass data to, and it color codes the buttons by their function. So, if you are using the button partial, your Save, Delete, etc. buttons should already be upgraded. If not, get your head in the game. Secondary buttons are smaller and used for lists and other places where flashy buttons would be a distraction. These take a class of “button” and do not come in colors. If you are using the button partial and it is defaulting to the large ones, simply add a new param to get the secondary buttons:

<?php $this->load->view('admin/partials/buttons', array('button_type'=>'secondary', 'buttons' => array('edit' => array('id' => '../instances/edit/' . $widget->id), 'delete')) ); ?>

It defaults to primary, so don’t worry about it if you want the primary buttons.

Sections and Shortcuts

The interface in PyroCMS 1.3 was made for simple modules, like “Redirects”, which is essentially a GUI crud for a DB table. If you want more functionality for sections of admin content within a module, you needed to roll your own solution. I did that for PyroStreams with a special level of nav that defined a “Fields” and “Streams” section. In PyroCMS 2, you can define “sections” in your details.php file. Here is an example:

<?php defined('BASEPATH') or exit('No direct script access allowed');
 
class Module_Sample extends Module {
 
	public $version = '1.0';
 
	public function info()
	{
		return array(
			'name' => array(
				'en' => 'Sample',
			),
			'description' => array(
				'en' => 'Only the samplest.'
			),
			'frontend'	=> TRUE,
			'backend'	=> TRUE,
			'skip_xss'	=> TRUE,
			'menu'		=> 'content',
 
			'roles' => array(
				'admin_module'
			),
			
			'sections' => array(
			    'dogs' => array(
				    'name' => 'sample_dogs',
				    'uri' => 'admin/sample',
				    'shortcuts' => array(
						array(
					 	   'name' => 'sample_new_dog',
						    'uri' => 'admin/sample/create',
						),
					),
				),
			    'cats' => array(
				    'name' => 'sample_cats',
				    'uri' => 'admin/sample/cats',
				    'shortcuts' => array(
						array(
						    'name' => 'cats_new_cat',
						    'uri' => 'admin/sample/cats/create',
						),
				    ),
			    ),
		    ),
		);
	}
 
}
 
/* End of file details.php */

This way, you can easily separate your modules into different sections, and the interface will respond in kind:

The best way to integrate this is to separate your module into separate admin controllers. The admin.php controller, and another controller for each section. For the blog module, it would be admin_categories.php for the categories section.

PyroCMS knows what section you are in by reading a class variable in the section controller:

protected $section = 'categories';

Add one to each of your section controllers, and you are on your way.

Shortcuts

You might notice in the example above, that shortcuts are part of this array as well. In PyroCMS 2, shortcuts are no longer a partial – you add them to your details.php file. See the example above for the specifics.

For modules that do not have sections, the shortcuts section of the array is on the same leve with the ‘name’ and ‘description’ nodes.

Filtering Data

Many core PyroCMS modules us data filtering (such as the blog module), and yours may too. In PyroCMS 2, filtering is not handled by a partial – you need to add it to your views. Take the example of the blog filtering:

<fieldset id="filters">
	
	<legend><?php echo lang('global:filters'); ?></legend>
	
	<?php echo form_open(); ?>
 
	<?php echo form_hidden('f_module', $module_details['slug']); ?>
		<ul>  
			<li>
        		<?php echo lang('blog_status_label', 'f_status'); ?>
        		<?php echo form_dropdown('f_status', array(0 => lang('global:select-all'), 'draft'=>lang('blog_draft_label'), 'live'=>lang('blog_live_label'))); ?>
    		</li>
		
			<li>
        		<?php echo lang('blog_category_label', 'f_category'); ?>
        		<?php echo form_dropdown('f_category', array(0 => lang('global:select-all')) + $categories); ?>
    		</li>
			
			<li><?php echo form_input('f_keywords'); ?></li>
			<li><?php echo anchor(current_url() . '#', lang('buttons.cancel'), 'class="cancel"'); ?></li>
		</ul>
	<?php echo form_close(); ?>
</fieldset>

Simply define a fieldset with the id of “filters” with a legend tag, and you can put a UL of params in there with your filtering options. Filtering should take place at the table-level, meaning that when a filter is applied, the table is changed, not the entire block of content. You can wrap your table (or other element you want filtered) in a div with an id of “filter-stage”:

<div id="filter-stage">

Misc Items

- A new feature in PyroCMS 2allows action buttons on tables (such as a mass “Delete” function) to stay inactive until a user does something that would enable data to be acted upon (ie: checking a box). To enable this, just wrap your buttons in a div with a class of “table_action_buttons”.

- As with PyroCMS 1.3.2, $this->user is deprecated in favor of $this->current_user.

- To float buttons to the right in an action table column, give it a class of “actions”.

Tags

The one piece of the pie not yet in place is the new tag system, which is being rewritten. I’ve leave it to Phil Sturgeon to update the troops on that one, but you can follow the progress on the new tag parser library (called “Lex”) here.

Go Forth and Update

PyroCMS 2 is going to be a huge leap forward. Clients will love it, and it offers a lot more in terms of flexibility and style for Add-on developers. If you have any questions, comment below or ask in the PyroCMS forums.