====== Extending Custom Group Actions ======

**Author:** Victor Boctor

===== Introduction =====

In Mantis 1.1.0a3, a new technique for extending the standard set of issue group actions with less work than what was required in previous releases.  The following steps walk through the steps to be done.

===== Page Title =====

This function prints the title for the custom page action page.

<code php>
/**
 * Prints the title for the custom action page.	 
 */
function action_add_note_print_title() {
	echo '<tr class="form-title">';
	echo '<td colspan="2">';
	echo lang_get( 'add_bugnote_title' );
	echo '</td></tr>';		
}
</code>

===== Form Fields =====

This function echos all the form fields.

<code php>
/**
 * Prints the field within the custom action form.  This has an entry for
 * every field the user need to supply + the submit button.  The fields are
 * added as rows in a table that is already created by the calling code.
 * A row has two columns.         	 
 */
function action_add_note_print_fields() {
	echo '<tr class="row-1" valign="top"><td class="category">', lang_get( 'add_bugnote_title' ), '</td><td><textarea name="bugnote_text" cols="80" rows="10" wrap="virtual"></textarea></td></tr>';
?>
<!-- View Status -->
<tr class="row-2">
<td class="category">
	<?php echo lang_get( 'view_status' ) ?>
</td>
<td>
<?php
	if ( access_has_project_level( config_get( 'change_view_status_threshold' ) ) ) { ?>
		<select name="view_state">
			<?php print_enum_string_option_list( 'view_state', $t_bug->view_state) ?>
		</select>
<?php
	} else {
		echo get_enum_element( 'view_state', $t_bug->view_state );
		echo '<input type="hidden" name="view_state" value="', $t_bug->view_state, '" />';
	}
?>
</td>
</tr>
<?php
	echo '<tr><td colspan="2"><center><input type="submit" class="button" value="' . lang_get( 'add_bugnote_button' ) . ' " /></center></td></tr>';
}
</code>

===== Form Validation =====

This function validates the user inputs for te form parameters and confirms that it is valid.

<code php>
/**
 * Validates the action on the specified bug id.
 * 
 * @returns true    Action can be applied.
 * @returns array( bug_id => reason for failure )	 
 */
function action_add_note_validate( $p_bug_id ) {
	$f_bugnote_text = gpc_get_string( 'bugnote_text' );

	if ( is_blank( $f_bugnote_text ) ) {
		error_parameters( lang_get( 'bugnote' ) );
		trigger_error( ERROR_EMPTY_FIELD, ERROR );
	}

	$t_failed_validation_ids = array();
	$t_add_bugnote_threshold = config_get( 'add_bugnote_threshold' );
	$t_bug_id = $p_bug_id;

	if ( bug_is_readonly( $t_bug_id ) ) {
		$t_failed_validation_ids[$t_bug_id] = lang_get( 'actiongroup_error_issue_is_readonly' );
		return $t_failed_validation_ids;
	}

	if ( !access_has_bug_level( $t_add_bugnote_threshold, $t_bug_id ) ) {
		$t_failed_validation_ids[$t_bug_id] = lang_get( 'access_denied' );
		return $t_failed_validation_ids;
	}

	return true;
}
</code>

===== Process Form =====

<code php>
/**
 * Executes the custom action on the specified bug id.
 * 
 * @param $p_bug_id  The bug id to execute the custom action on.
 * 
 * @returns true   Action executed successfully.
 * @returns array( bug_id => reason for failure )               	 
 */
function action_add_note_process( $p_bug_id ) {
	$f_bugnote_text = gpc_get_string( 'bugnote_text' );
	$f_view_state = gpc_get_int( 'view_state' );
	bugnote_add ( $p_bug_id, $f_bugnote_text, '0:00', /* $p_private = */ $f_view_state != VS_PUBLIC  );
        return true;
}
</code>


===== Configuration =====

This steps tells Mantis to load the extension relating to the custom issue group action.  For an extension with the name 'EXT_ADD_NOTE', the code will look for bug_actiongroup_add_note_inc.php.  Basically the file name is calculated by removing the "EXT_" prefix, converting to lower case, and inserting in the middle of "bug_actiongroup_" prefix and "_inc.php" suffix.

<code php>
	# Custom Group Actions
	#
	# This extensibility model allows developing new group custom actions.  This
	# can be implemented with a totally custom form and action pages or with a 
	# pre-implemented form and action page and call-outs to some functions.  These
	# functions are to be implemented in a predefined file whose name is based on
	# the action name.  For example, for an action to add a note, the action would
	# be EXT_ADD_NOTE and the file implementing it would be bug_actiongroup_add_note_inc.php.
	# See implementation of this file for details.
	#
	# Sample:
	#
	# array(
	#	array(	'action' => 'my_custom_action',
	#			'label' => 'my_label',   // string to be passed to lang_get_defaulted()
	#			'form_page' => 'my_custom_action_page.php',
	#			'action_page' => 'my_custom_action.php'
	#   )
	#	array(	'action' => 'my_custom_action2',
	#			'form_page' => 'my_custom_action2_page.php',
	#			'action_page' => 'my_custom_action2.php'
	#   )
	#	array(	'action' => 'EXT_ADD_NOTE',  // you need to implement bug_actiongroup_<action_without_'EXT_')_inc.php
	#		'label' => 'actiongroup_menu_add_note' // see strings_english.txt for this label
	#   )
	# );
	$g_custom_group_actions = array(0=>
					array(	'action' => 'EXT_ADD_NOTE',  // you need to implement bug_actiongroup_<action_without_'EXT_'>_inc.php
						'label' => 'actiongroup_menu_add_note' // see strings_english.txt for this label
						)
					);
</code>