4.0 - Trees

Introduction

I previously wrote a blog entry about building tables in IPS Social Suite 4.0. Similar to tables, we also have trees. Trees in many ways look and behave similarly to tables, but can be distinguished mainly by the fact that trees show a collection of objects in a fixed order (often, though not always the order can be changed by the administrator) whereas tables can show data sorted however you like at the time. An example of trees would be the list of forums in IP.Board.

Trees vary quite significantly in their individual implementations, for example:

• Objects in a tree often have parent/child relationships. Sometimes this relationship is between the same type of object (for example, forums in IP.Board or categories in IP.Downloads), sometimes the relationship is between different types of object (for example, applications and modules, where modules are always the child of applications) and sometimes it's a mix of both (for example, packages in IP.Nexus are always children of package groups, but package groups may or may not be children of each other).
• Objects in a tree can usually, but not always be reordered by the administrator.
• Objects in a tree can sometimes be enabled and disabled without being deleted, for example applications and modules. Sometimes individual objects can't when the rest can (for example, you can't disable the "Core" application).
• Trees usually have controls for adding, editing, assigning permissions, duplicating and deleting objects, though a subset of these controls, or additional controls may be available (for example, you can't edit the permissions on a package in IP.Nexus, but you can run a purchase report, which you can't do in any other trees).
  

/**
 * Custom Profile Field Group Node
 */
class _Group extends IPSNodeModel
{
	/**
	 * @brief	[ActiveRecord] Multiton Store
	 */
	protected static $multitons;
	
	/**
	 * @brief	[ActiveRecord] Default Values
	 */
	protected static $defaultValues = NULL;
	
	/**
	 * @brief	[ActiveRecord] Database Table
	 */
	public static $databaseTable = 'core_pfields_groups';
	
	/**
	 * @brief	[ActiveRecord] Database Prefix
	 */
	public static $databasePrefix = 'pf_group_';
	
	/**
	 * @brief	[ActiveRecord] ID Database Column
	 */
	public static $databaseColumnId = 'id';
		
	/**
	 * @brief	[Node] Node Title
	 */
	public static $nodeTitle = 'profile_fields';
		
}

• $multitons and $defaultValues are required by the IPSPatternsActiveRecord class. We don't need to do anything with them other than declare them.
• $databaseTable tells the IPSPatternsActiveRecord class what database table the records we need are in.
• $databasePrefix tells the IPSPatternsActiveRecord class the prefix used on all database columns. This isn't necessary, but since all the columns in my table start with "pf_group_", putting it here will save me typing it out every time.
• $databaseColumnId tells the IPSPatternsActiveRecord class which column contains the primary key.
• $nodeTitle tells the IPSNodeModel class what language string to use as the title on my page that shows the tree.
  

namespace IPScoremodulesadminmembersettings;

/**
 * Profile Fields and Settings
 */
class _profiles extends IPSNodeController
{
	/**
	 * Node Class
	 */
	protected $nodeClass = 'IPScoreProfileFieldsGroup';

}

Now I have a page which looks like this:





Customising the rows

You'll notice I now have two rows (because I have two rows in my database), but both are blank. This is because the IPSNodeModel class doesn't know what to use for the record title. Let's fix that by adding a method to our class:

	/**
	 * [Node] Get Node Title
	 *
	 * @return	string
	 */
	protected function get__title()
	{
		$key = "core_pfieldgroups_{$this->id}";
		return IPSLang::i()->$key;
	}

That code might seem a bit confusing, but note:

• $this->id gets the value of the "pf_group_id" column in the database. This is because the IPSPatternsActiveRecord class provides us with a __get method for retrieving the database row values. This is handy if we want to be able to modify the value returned for whatever reason, as we can override that method.
• We're retrieving the value for a language key rather than some kind of title field in the database. This is because in IPS Social Suite 4, data like this will be translatable, so if you have more than one language you can display different values depending on the user's language choice.
  

	/**
	 * [Node] Does the currently logged in user have permission to edit permissions for this node?
	 *
	 * @return	bool
	 */
	public function canManagePermissions()
	{
		return false;
	}

And now it's gone:





Making the buttons work

The first buttons I need to make work are the add on the "root" row, and the edit on each row below that. I'm going to ignore the add button on each record row for now as that is for adding a child record and we haven't got to that yet - it will start working automatically when we add support for children.

These buttons will display a form. In a previous blog entry I talked about our form helper class. I'm going to use this to build the add/edit form.

To do this, I'll add two methods to my class to display the form and to save it's values - here they are:

	/**
	 * [Node] Add/Edit Form
	 *
	 * @param	IPSHelpersForm	$form	The form
	 * @return	void
	 */
	public function form( &$form )
	{
		$form->add( new IPSHelpersFormTranslatable( 'pfield_group_title', NULL, TRUE, array( 'app' => 'core', 'key' => ( $this->id ? "core_pfieldgroups_{$this->id}" : NULL ) ) ) );
	}
	
	/**
	 * [Node] Save Add/Edit Form
	 *
	 * @param	array	$values	Values from the form
	 * @return	void
	 */
	public function saveForm( $values )
	{
		if ( !$this->id )
		{
			$this->save();
		}
		
		IPSLang::saveCustom( 'core', "core_pfieldgroups_{$this->id}", $values['pfield_group_title'] );
	}

Most of that should be self explanatory - however in the blog entry about forms I didn't mention the Translatable class. If you have one language installed, this will just display a normal text field, however, if you have more than one, it will show one for each language. It then returns an array, which we can pass to IPSLang::saveCustom() to save the values.

This is what our form might look like if I have several languages installed:


Or, more commonly, if I just have one:



Now the add and edit forms are working, but since these are very small forms (they only have one input field) I'd like them to display in a modal popup rather than take the user to a new page (if the user has JavaScript disabled, a new page will do). To do this, I just add a property to my class:

	/**
	 * @brief	[Node] Show forms modally?
	 */
	public static $modalForms = TRUE;

Next we have the copy and delete buttons. These will actually work by themselves (the central class will handle copying and deleting the records from the database), however, since we have translatable values, we need to make sure those too are copied and deleted appropriately. To do this, I'll override the two methods which handle copying and deleting:

	/**
	 * [ActiveRecord] Duplicate
	 *
	 * @return	void
	 */
	public function __clone()
	{
		$oldId = $this->id;
		parent::__clone();
		IPSLang::saveCustom( 'core', "core_pfieldgroups_{$this->id}", IPSDb::i()->buildAndFetchAll( array( 'select' => '*', 'from' => 'core_sys_lang_words', 'where' => array( 'word_key=?', "core_pfieldgroups_{$oldId}" ) ), 'lang_id', 'word_custom' ) );
	}
	
	/**
	 * [ActiveRecord] Delete Record
	 *
	 * @return	void
	 */
	public function delete()
	{
		parent::delete();
		IPSLang::deleteCustom( 'core', 'core_pfieldgroups_' . $this->id );
	}

Search

You'll notice that the system has automatically added a search box at the top of the table. In order to make this work, we need to add a simple search method:

	/**
	 * Search
	 *
	 * @param	string		$column	Column to search
	 * @param	string		$query	Search query
	 * @param	string|null	$order	Column to order by
	 * @return	array
	 */
	public static function search( $column, $query, $order )
	{	
		if ( $column === '_title' )
		{
			$return = array();			
			foreach ( IPSLang::i()->searchCustom( 'core_pfieldgroups_', $query ) as $key => $value )
			{
				try
				{
					$return[ $key ] = self::load( $key );
				}
				catch ( Exception $e ) { }
			}
			return $return;
		}
		return parent::search( $column, $query, $order );
	}

Making the rows re-orderable

The last thing I need to do to finish the handling of groups is make it so we can drag and drop to reorder them. To do this I just add another property to my class telling IPSPatternsActiveRecord which column contains the order ID:

	/**
	 * @brief	[Node] Order Database Column
	 */
	public static $databaseColumnOrder = 'order';

ACP Restrictions

It's important of course to make sure we honour ACP restrictions. The easiest way to do this is to create individual ACP restrictions for add/edit/delete (this can be done in the developer center) with a common prefix, and then specify like so:

	/**
	 * @brief	[Node] ACP Restrictions
	 */
	protected static $restrictions = array(
		'app'		=> 'core',
		'module'	=> 'membersettings',
		'prefix'	=> 'profilefieldgroups_',
	);

The system will now look for ACP restrictions with the keys "profilefieldgroups_add", "profilefieldgroups_edit" and "profilefieldgroups_delete" when performing those actions.


Children

Let's recap what we have so far with a video:
http://screencast.com/t/TUBuuYBSBON
Now that we have groups sorted, we're going to create another class for the actual fields which will show as children. The process is almost exactly the same as for groups. Since the process is the same, I won't go through the process step-by-step, but here is the class I've written if you're interested:
Field.php

The only changes are:

• I've declared two additional properties specifying the class name of the parent ("IPScoreProfileFieldsGroup") and which column contains the parent ID.
• I've declared an additional method to fetch an icon for the row so we can see what type of field this is.
• Just like we overwrote canManagePermissions for groups, I've also overridden canAdd in the same way, as you cannot add children to profile fields.
  

	/**
	 * @brief	[Node] Subnode class
	 */
	public static $subnodeClass = 'IPScoreProfileFieldsField';

The system will now automatically change the behaviour of our page in the following ways:

• When clicking on a group, it will expand out to show the fields under it.
• The search box will include fields as well as groups in its results.
• When clicking the "Add" button for a group, it will show the field to add a field to that group.
• When clicking the "Copy" button for a group, you'll have the option to copy children too or not.
• When clicking the "Delete" button for a group, you'll have the option to move children elsewhere or delete them too.
• (This is my favourite feature) In addition to being able to drag and drop fields to reorder, you can drag a field out of one group and into another.