NusaATK - User contributions [en]

Custom (record) actions

2026-01-17T11:40:14Z

36.68.89.237: /* Defining your own action */

{{Howto|Advanced|[[Boy Baukema]]}}

== 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: 

<syntaxhighlight lang="php">
function action_showhelloworld()
{
$output = $this->getUI()->renderBox(array("title"=>"My Hello World Page",
"content"=>"Hello World!"));

$this->addStyle("style.css");
$this->getPage()->addContent($this->renderActionPage("showhelloworld", $output));
}
</syntaxhighlight>

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:

<syntaxhighlight lang="php">
function getNodes()
{
registerNode("worlds.world", array("admin", "add", "edit", "delete","showhelloworld"));
}
</syntaxhighlight>

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:

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

And change:

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

to:

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

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!

== Overriding existing actions ==

To override existing actions (for example, the edit action), do:

<syntaxhighlight lang="php">
function recordActions($record, &$actions, &$mraactions) {

$actions["edit"] = dispatch_url(
$this->atknodetype(),
"edit",
array(
"foo" => "bar",
"atkselector" => "mytable.id = {$record["id"]}"
)
);

}

function action_edit($handler) {
$foo = $this->m_postvars['foo']; // "bar"
$handler->action_edit();
}
</syntaxhighlight>

Note that you *must* define the atkselector key--if you don't, the edit link will (silently) produce an edit page of the first row in the associated table, which probably isn't what you want. You also need to explicitly set the selector: setting it to "[pk]" doesn't work, because it gets encoded.

== Returning to the record ==

If you have an action that updates your record, after doing the update you can go back to the edit screen by using this code
<syntaxhighlight lang="php">
$this->redirect($record);
</syntaxhighlight>

== Your own multi record action ==

Here is a simple example of creating a mra-action.

First, add the NF_MRA flag to your node:

<syntaxhighlight lang="php">
class foo extends atkMetaNode {

protected $flags = array(NF_MRA);

// ...

}
</syntaxhighlight>

Adding the flag will change the "admin" (list) display so that a checkbox is displayed next to each row, and add some text ("Select all", etc.) beneath the table.

Add the action to <code>$mraactions</code>:

<syntaxhighlight lang="php">
function recordActions($record, &$actions, &$mraactions)
{
$mraactions['my_mra_action'] = "my_mra_action";
}
</syntaxhighlight>

Implement the <code>action_XXX</code> function:

<syntaxhighlight lang="php">
function action_my_mra_action()
{
atk_var_dump($this->m_postvars["atkselector"], 'selected records');
}
</syntaxhighlight>

atkselector will contain the primary keys of all records that are selected. You can use this to retrieve the rows and perform the actual action on it.

Add the action via the <code>registerNode</code> function in <code>module.inc</code>:

<syntaxhighlight lang="php">
function getNodes() {
registerNode('projects.foo', array('my_mra_action'));
}
</syntaxhighlight>

(After calling registerNode(), go into the web interface and enable this action for the appropriate user.)

Finally, if your action does not appear in the drop-down, ensure that the <code>allow</code> function isn't inhibiting the display of your action. (Hardcode <code>return true</code> to make sure.) For multi-record actions, the <code>allow()</code> function is not passed a populated <code>$record</code>--use <code>recordAction()</code> to determine which actions can be performed on a per-record basis.

If you want to, for example, update the status of multiple records, your code would look something like this:

<syntaxhighlight lang="php">
function action_my_mra_validate_action()
{
$this->updateStatus('valid', $this->m_postvars["atkselector"]);

return $this->redirect();
}

function updateStatus($status, $primkeys)
{
foreach ($primkeys as $pk)
{
$record = array("atkprimkey"=>$pk,
"status"=>$status);

$this->updateDb($record);
}
}
</syntaxhighlight>

=== Customizing MRA actions ===
Sometimes simply performing an action is not enough. For instance, you want the user to be able to select multiple records to set an attribute or perform an action with a parmeter on.

Like setting a population status (uninhabitable, unpopulated, populated) for several worlds at once.

You can do this by creating a ''getCustomMraHtml'' method in your node. The recordlist will then use the output from this method and place it directly in between the list of actions and the action button.
Example:

<syntaxhighlight lang="php">
public function recordActions($record, $actions, &$mraactions)
{
$mraactions['update_population'] = "update_population";
}

public function getCustomMraHtml()
{
$list = $this->getAttribute('population_status')->edit();
return $list;
}

public function action_update_population()
{
$status = $this->getAttribute('population_status')->fetchValue($this->m_postvars);
foreach ($this->m_postvars['atkselector'] as $pk)
{
$record = array("atkprimkey"=>$pk,
"population_status"=>$status);

$this->updateDb($record);
}
}
</syntaxhighlight>

''NOTE:'' If you are playing around with NF_MRA you will inevitably notice NF_MRPA (Multi Record Priority Actions) which is a feature that SHOULD allow you to select the order in which records are processed by a multi record action. However this feature should be considered deprecated as no real world usage cases has ever been found beyond the initial one.

== 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:

<syntaxhighlight lang="php">
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['saveandsayhello'])
{
$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();
}
</syntaxhighlight>

For more documentation please see: 
http://www.atk-framework.com/docs/atk/trunk/atk/atkNode.html#getFormButtons

== Removing Actions ==

=== Via <code>recordActions()</code> ===

As shown above, a common way to add actions is via the <code>$actions</code> array that is provided as an argument to, for example, the <code>recordActions()</code>. Actions can similarly be removed, by deleting values from this array. For example, all actions can be removed from a node with the following <code>recordActions()</code> method:

<syntaxhighlight lang="php">
function recordActions($record, &$actions, &$mraactions) {
$actions = array();
}
</syntaxhighlight>

Individual actions can also be removed by deleting the appropriate key:

<syntaxhighlight lang="php">
public function recordActions($record, &$actions, &$mraactions) {
unset($actions['delete']);
}
</syntaxhighlight>

=== Via <code>allow()</code> ===

= atkDataGrid Actions =

== Adding actions ==

e.g.

<syntaxhighlight lang="php">
$grid->setDefaultActions(array(
"view" => dispatch_url("projects.quote", "view", array("atkselector" => "[pk]"))
));
</syntaxhighlight>

These actions apply to all rows in the table; note that the "[pk]", is essentially interpolated. You may find an <code>atk_var_dump()</code> of <code>$grid->getDefaultActions()</code>useful to see what actions are currently configured.

== Removing actions ==

Actions can be removed from an <code>[[atkDataGrid]]</code> by using the <code>setDefaultActions()</code> method:

<syntaxhighlight lang="php">
$grid->setDefaultActions(array()); // remove all actions
$grid->setDefaultActions(array_diff_key($grid->getDefaultActions(),
array("delete" => true))); // remove just the "delete" action
</syntaxhighlight>

Custom (record) actions

2026-01-17T11:39:24Z

36.68.89.237: /* Defining your own action */

{{Howto|Advanced|[[Boy Baukema]]}}

== Defining your own action ==
ok
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: 

<syntaxhighlight lang="php">
function action_showhelloworld()
{
$output = $this->getUI()->renderBox(array("title"=>"My Hello World Page",
"content"=>"Hello World!"));

$this->addStyle("style.css");
$this->getPage()->addContent($this->renderActionPage("showhelloworld", $output));
}
</syntaxhighlight>

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:

<syntaxhighlight lang="php">
function getNodes()
{
registerNode("worlds.world", array("admin", "add", "edit", "delete","showhelloworld"));
}
</syntaxhighlight>

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:

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

And change:

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

to:

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

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!

== Overriding existing actions ==

To override existing actions (for example, the edit action), do:

<syntaxhighlight lang="php">
function recordActions($record, &$actions, &$mraactions) {

$actions["edit"] = dispatch_url(
$this->atknodetype(),
"edit",
array(
"foo" => "bar",
"atkselector" => "mytable.id = {$record["id"]}"
)
);

}

function action_edit($handler) {
$foo = $this->m_postvars['foo']; // "bar"
$handler->action_edit();
}
</syntaxhighlight>

Note that you *must* define the atkselector key--if you don't, the edit link will (silently) produce an edit page of the first row in the associated table, which probably isn't what you want. You also need to explicitly set the selector: setting it to "[pk]" doesn't work, because it gets encoded.

== Returning to the record ==

If you have an action that updates your record, after doing the update you can go back to the edit screen by using this code
<syntaxhighlight lang="php">
$this->redirect($record);
</syntaxhighlight>

== Your own multi record action ==

Here is a simple example of creating a mra-action.

First, add the NF_MRA flag to your node:

<syntaxhighlight lang="php">
class foo extends atkMetaNode {

protected $flags = array(NF_MRA);

// ...

}
</syntaxhighlight>

Adding the flag will change the "admin" (list) display so that a checkbox is displayed next to each row, and add some text ("Select all", etc.) beneath the table.

Add the action to <code>$mraactions</code>:

<syntaxhighlight lang="php">
function recordActions($record, &$actions, &$mraactions)
{
$mraactions['my_mra_action'] = "my_mra_action";
}
</syntaxhighlight>

Implement the <code>action_XXX</code> function:

<syntaxhighlight lang="php">
function action_my_mra_action()
{
atk_var_dump($this->m_postvars["atkselector"], 'selected records');
}
</syntaxhighlight>

atkselector will contain the primary keys of all records that are selected. You can use this to retrieve the rows and perform the actual action on it.

Add the action via the <code>registerNode</code> function in <code>module.inc</code>:

<syntaxhighlight lang="php">
function getNodes() {
registerNode('projects.foo', array('my_mra_action'));
}
</syntaxhighlight>

(After calling registerNode(), go into the web interface and enable this action for the appropriate user.)

Finally, if your action does not appear in the drop-down, ensure that the <code>allow</code> function isn't inhibiting the display of your action. (Hardcode <code>return true</code> to make sure.) For multi-record actions, the <code>allow()</code> function is not passed a populated <code>$record</code>--use <code>recordAction()</code> to determine which actions can be performed on a per-record basis.

If you want to, for example, update the status of multiple records, your code would look something like this:

<syntaxhighlight lang="php">
function action_my_mra_validate_action()
{
$this->updateStatus('valid', $this->m_postvars["atkselector"]);

return $this->redirect();
}

function updateStatus($status, $primkeys)
{
foreach ($primkeys as $pk)
{
$record = array("atkprimkey"=>$pk,
"status"=>$status);

$this->updateDb($record);
}
}
</syntaxhighlight>

=== Customizing MRA actions ===
Sometimes simply performing an action is not enough. For instance, you want the user to be able to select multiple records to set an attribute or perform an action with a parmeter on.

Like setting a population status (uninhabitable, unpopulated, populated) for several worlds at once.

You can do this by creating a ''getCustomMraHtml'' method in your node. The recordlist will then use the output from this method and place it directly in between the list of actions and the action button.
Example:

<syntaxhighlight lang="php">
public function recordActions($record, $actions, &$mraactions)
{
$mraactions['update_population'] = "update_population";
}

public function getCustomMraHtml()
{
$list = $this->getAttribute('population_status')->edit();
return $list;
}

public function action_update_population()
{
$status = $this->getAttribute('population_status')->fetchValue($this->m_postvars);
foreach ($this->m_postvars['atkselector'] as $pk)
{
$record = array("atkprimkey"=>$pk,
"population_status"=>$status);

$this->updateDb($record);
}
}
</syntaxhighlight>

''NOTE:'' If you are playing around with NF_MRA you will inevitably notice NF_MRPA (Multi Record Priority Actions) which is a feature that SHOULD allow you to select the order in which records are processed by a multi record action. However this feature should be considered deprecated as no real world usage cases has ever been found beyond the initial one.

== 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:

<syntaxhighlight lang="php">
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['saveandsayhello'])
{
$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();
}
</syntaxhighlight>

For more documentation please see: 
http://www.atk-framework.com/docs/atk/trunk/atk/atkNode.html#getFormButtons

== Removing Actions ==

=== Via <code>recordActions()</code> ===

As shown above, a common way to add actions is via the <code>$actions</code> array that is provided as an argument to, for example, the <code>recordActions()</code>. Actions can similarly be removed, by deleting values from this array. For example, all actions can be removed from a node with the following <code>recordActions()</code> method:

<syntaxhighlight lang="php">
function recordActions($record, &$actions, &$mraactions) {
$actions = array();
}
</syntaxhighlight>

Individual actions can also be removed by deleting the appropriate key:

<syntaxhighlight lang="php">
public function recordActions($record, &$actions, &$mraactions) {
unset($actions['delete']);
}
</syntaxhighlight>

=== Via <code>allow()</code> ===

= atkDataGrid Actions =

== Adding actions ==

e.g.

<syntaxhighlight lang="php">
$grid->setDefaultActions(array(
"view" => dispatch_url("projects.quote", "view", array("atkselector" => "[pk]"))
));
</syntaxhighlight>

These actions apply to all rows in the table; note that the "[pk]", is essentially interpolated. You may find an <code>atk_var_dump()</code> of <code>$grid->getDefaultActions()</code>useful to see what actions are currently configured.

== Removing actions ==

Actions can be removed from an <code>[[atkDataGrid]]</code> by using the <code>setDefaultActions()</code> method:

<syntaxhighlight lang="php">
$grid->setDefaultActions(array()); // remove all actions
$grid->setDefaultActions(array_diff_key($grid->getDefaultActions(),
array("delete" => true))); // remove just the "delete" action
</syntaxhighlight>