Hooks

Introduction

The usual way of overriding method behaviour in an object oriented context, is to override them in derived classes.

Magic methods in ATK are methods that are similar. The difference is that these are not overrides, because these methods are not present in the base class. The reason is that these methods are dynamic in nature. ATK checks whether these methods exist, and if so, calls them. This is also known as the 'Hollywood Principle'.

This concept might be confusing, but is best explained with an example. Add this method to your node:

  public function name_display($record) {
      return "Hello World";
  }

'name' refers to an attribute of your node. If this magic method exists, ATK will call name_display every time it want to display a value from the 'name' attribute, instead of its usual display logic. If you try this code, you'll see that the 'name' column of a recordlist will now only contain 'hello world' entries.

This example also demonstrates why these are 'magic methods'. There is no name_display method in atkNode, because atkNode has no knowledge of what attributes your node may have at any time.

Whenever we refer to magic methods in the ATK documentation, we usually refer to <attribname>_display, where attribname should be replaced by an actual attribute from your node.

When to use it

For each magic method, there is a solution that does not require a magic method. For example, to override the display behaviour of an attribute, you can also extend the attribute like this:

 class helloworldAttribute extends atkAttribute
 {
   function display($record, $mode)
   {  
     return "Hello World";
   }
 }

So why should you use magic methods? Magic methods are quicker to implement, and are always node specific. They only work in the node you add the method to. If you extend an attribute, you can reuse the attribute in multiple nodes. If all you need to do is alter the display of some column in one node, a magic <attribname>_display method is less code and less overhead.

A practical example

The most commonly used magic method is <attribname>_display. It is used to alter the output of attribute values. The safest way to do this is to call the original display behaviour, and alter its output, as in the following example, which makes the text of a column bold if it contains the word 'atk':

  public function content_display($record, $mode) 
  {
      $attribute = $this->getAttribute("content");
      $original = $attribute->display($record, $mode);
  
      if ($mode=="list" && strpos($original, "atk")!==false) {
          $original = "<nowiki><b></nowiki>".$original."<nowiki></b></nowiki>";
      }
  
      return $original;
  }

In this case, the $mode parameter is used to change the behaviour only in 'list' mode (recordlists, such as the admin page).

What parameters a magic method has, depends on the method. These are documented below.

List of ATK Magic Methods

Attribute related

<attribname>_display

Todo: show api and example

<attribname>_edit

Todo: show api and example

<attribname>_validate

Todo: show api and example

<attribname>_selection

Todo: show api and example

Action related

action_<action>

Best explained via example: if a URL is generated with

dispatch_url("general.user", "display");

then loading this URL results in a call to the action_display() of the general.user node.

adminHeader

If you implement a method in your node called 'adminHeader', returning a string, that string is displayed in an admin page above the list of records. This can be used for example to add information, buttons, filters or links.

adminFooter

Similar to adminHeader, but displays the string below the list of records.

Database related

If you want to add functionality whenever things happen in the database, have a look at Action Listeners, Trigger Listeners and Triggers. These aren't 'magic methods', but behave similarly.