ATK contains lots of hidden gems. Most of them are hidden because they are undocumented or because they are only documented in the API docs (which nobody seems to read...). In the past few years we've tried to improve the documentation for ATK. We've created a Wiki with lots of how-to's, the "Pizza Guides", a demo application and improved the API documentation. However there are still some features of ATK nobody seems to know about. In my next few blogs, starting with this one, I will write about some of them.

Using list columns for atkManyToOneRelations

By default the atkManyToOneRelation displays the descriptor of the destination record in the record list. However, sometimes your descriptor consists of more than one field which you would rather show in separate columns. The benefit of showing them in separate columns is that it's more clear to read and that it allows you to sort and search the list using these fields. What many people don't know is that the atkManyToOneRelation supports this out-of-the-box.

To use this feature you add an atkManyToOneRelation to your (meta-) node the way you would do so normally. After the relation has been added you can call the addListColumn method on the relation object to register the destination fields you want to see in separate columns in the record list. That's it! If you now look at the record list you will see a column for the relation itself and next to it one or more columns for the registered list fields. If you want to make these fields searchable you need to add the AF_SEARCHABLE flag to the attributes they represent in the destination node.

Sometimes you only want to show registered list columns and not the column for the relation itself. If that's the case you need to add the AF_HIDE_LIST flag for the relation and you should call setAlwaysShowListColumns(true) on the relation object. If you now look at the record list you will see that it doesn't contain the relation column anymore but the list columns are still there.

A small code example:

1
2
3
4
5
6

$attr=$this->add(new atkManyToOneRelation('manager_id', 'employee.manager', AF_OBLIGATORY|AF_HIDE));
 
$attr->addListColumn('firstname');
$attr->addListColumn('lastname');
$attr->addListColumn('city');
$attr->setAlwaysShowListColumns(true);

This will show the manager relation as 3 separate columns in the record list which allows the user to filter the list by manager firstname, lastname and/or city.

More next time.