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).
For IPS Social Suite 4.0, I wanted to create a central class to create trees - currently we duplicate a lot of functionality, and all our trees display differently (in some places, quite radically so), but without loosing any of the flexibility necessary given the various differences in each implementation. Because trees are both more complicated and flexible than tables, the method for creating one might seem complicated - however, when you compare it to having to write every part manually (including all the JavaScript) as was the case in IP.Board 3, you'll be shaving hours off of development time.
There are two ways you can create trees in IPS Social Suite 4.0. The most common way is when each item in the table has a record in the database. There are occasions when this isn't the case (for example, the developer center displays trees created from JSON objects), and the Tree class can handle these, but in this blog entry I'm going to show you the more common method.
Just like I did for tables, I'm going to take you through how I programmed a real-world example, specifically the tree for custom profile fields.
Creating the classes
Custom profile fields are arranged into groups, so I'm going to start by creating a tree that shows the groups. To do this, I need to create a class for the custom profile field groups, I'll set this class to extend IPSNodeModel which is an abstract class that provides most of the functionality we need. IPSNodeModel in turn extends a class called IPSPatternsActiveRecord which provides functionality to make a class an Active Record (by that I mean, an object of the class corresponds to a record in the database).
In this class I need to define a few variables - I'll explain them below, but this is the code I'll write:
/**
* 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.
Now I need to create a controller to display my tree - the developer center will set up the structure of this for me, then I just fill in the name of the class I just created:
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.
So now we have this (I've clicked the dropdown arrow so you can see it's contents):
Most of this is okay, but permissions aren't relevant for custom profile field groups, so let's get rid of that. The IPSNodeModel class has methods for checking if the user has permission to each button it displays (which by default check ACP restrictions, which I'll explain more about later) - we can simply override the method which checks for that button so it always returns false:
/**
* [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.
Now all we need to do is link them up. To do this, I add a property to my group class telling IPSNodeModel the name of the class which contains children:
/** * @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.
Here's a video:
http://screencast.com/t/5fQwgle3EX