Custom (record) actions

ATK Howto: Custom (record) actions Complexity: Advanced Author: Boy Baukema <boy@ibuildings.nl>

List of other Howto's

Defining your own action

Defining your own action for your node is quite easy in ATK, you can do so simply by implementing a function called action_actionname.
Example where we also output our own 'Hello World' page, just like a normal ATK action page:

 function action_showhelloworld()
 {
   $page = &$this->getPage();
 
   $ui = &$this->getUi();
 
   $output = $ui->renderBox(array("title"=>"My Hello World Page",
                                  "content"=>"Hello World!"));
 
   $this->addStyle("style.css");
   $page->addContent($this->renderActionPage("showhelloworld", $output));
 }

Don't forget to also register the node in your module.inc so you can assign rights and let 'normal' users (I'm not saying your users are normal, but you know what I mean :)) use your action as well, instead of only the administrator user.
In our example this would be:

 function getNodes()
 {
   registerNode("worlds.world", array("admin", "add", "edit", "delete","showhelloworld"));
 }

Worlds being the module name and world the node name.

Your own record action

Now say we wanna go a bit further and we want to perform our own action on a record. Say we have a node with data on worlds, and we wanna make a fun action that we could click that would say "Hello $worldname!", so for earth it would be "Hello earth!". We'd have to define it as a recordaction:

 function recordActions($record, &$actions, &$mraactions)
 {
   $actions["showhelloworld"]= session_url(dispatch_url($this->atknodetype(),
                                                        "showhelloworld",
                                                        array("worldname"=>$record["worldname"])));
 }

And change:

 $output = $ui->renderBox(array("title"=>'My Hello World Page',
                                "content"=>"Hello World!"));

to:

 $output = $ui->renderBox(array("title"=>'My Hello World Page',
                                "content"=>"Hello {$this->m_postvars['worldname']}!"));

Now we can say hello to all the worlds in our node!

Your own record action icon

As a finishing touch we have an icon of a hand (hand.gif) we want to use for this action in the node.
To do this, we need to rename the icon to the actionname, making it showhelloworld.gif.
Now we need somewhere to put this icon where ATK will find it.
In the appropriate module directory (modules/worlds/) create a directory structure like the following:
modules/worlds/themes/default/icons/recordlist/

Now we need to put the icon (showhelloworld.gif) in the directory structure we just created (modules/worlds/themes/default/icons/recordlist/).
And finally, all we need to do is throw away the theme cache (as user with appropriate rights or root user in the application root 'rm -vf atktmp/themes/*') and voila!

A custom form button

Now say you want to have an extra button in your node 'Save and say hello!' besides 'Save and close' and 'Save'.
This is useful in situations where you want to perform a special action on a record besides saving it.
You could add the following method to your node:

 function getFormButtons($mode, $record)
 {
   // Get the normal buttons
   $buttons = parent::getFormButtons($mode,$record);
   if ($mode==='edit')
   {
     // If the user is editting, add a 'saveandsayhello' button (you should also add a translation to your language file for saveandsayhello)
     array_unshift($buttons, '<input type="submit" class="btn_save" name="saveandsayhello" value="'.atktext("saveandsayhello", "worlds").'">');
   }
   return $buttons;
 }

 function postUpdate($record)
 {
   if ($this->m_postvars['atksaveandsayhello'])
   {
     $this->redirect(dispatch_url($this->atknodetype(),'showhelloworld'));
   }
 }

 function action_update(&$handler)
 {
   // Trick the update handler into thinking that when we clicked
   // the saveandsayhello button, we also clicked the save and close button.
   // You could also use atknoclose if you just want to save
   if ($handler->m_postvars['saveandsayhello']) $handler->m_postvars['atksaveandclose']=1;
   return $handler->action_update();
 }

For more documentation please see:
http://achievo.org/docs/atk/latest/atk/atkNode.html#getFormButtons