Guidelines: Clippy

From Pandora FMS Wiki
Jump to: navigation, search

It is a new feature for the Pandora 5.1x.

Green paperclip.png

1 Tours

A tour it is a several steps to teach a user to make a task.

The all tours start in the header when the user clicks the clippy icon or maybe when the user is logged.

Head clippy.png

And this dialog bubble has a list of tasks as can you see in the next screenshot.

Clippy list tasks.png

The code for to create new link a any task is:

					"<a href='javascript: clippy_go_link_show_help(\"index.php?sec=gagente&sec2=godmode/agentes/modificar_agente\", \"monitoring_server_step_1\");'>" . 
					//'<a href="index.php?sec=gagente&sec2=godmode/agentes/modificar_agente&clippy=monitoring_server">' . 
						__('Ping to a Linux or Windows server with a Pandora FMS agent') .
					'</a>' .

And it is in:

include/help/clippy/homepage.php

The javascript call is:

clippy_go_link_show_help("<url>", "<tour_name>")

The code of the tour must be into a file in:

include/help/clippy/<sec2_param_separated_with_underlines>.php

For example godmode/agentes/modificar_agente is

include/help/clippy/godmode_agentes_modificar_agente.php

And the code is more or less:

function clippy_start_page() {
	
	$return_tours = array();
	$return_tours['first_step_by_default'] = false;
	$return_tours['tours'] = array();
	
	//==================================================================
	//Help tour about the monitoring with a ping (step 1)
	//------------------------------------------------------------------
	$return_tours['tours']['monitoring_server_step_1'] = array();
	$return_tours['tours']['monitoring_server_step_1']['steps'] = array();
	$return_tours['tours']['monitoring_server_step_1']['steps'][] = array(
		'element'=> '#clippy',
		'intro' => __('I\'m going to show you how to monitor a server.')
		);
	$return_tours['tours']['monitoring_server_step_1']['steps'][] = array(
		'element'=> 'input[name="search"]',
		'intro' => __('Please, type an agent to save the modules for monitoring a server.')
		);
	$return_tours['tours']['monitoring_server_step_1']['steps'][] = array(
		'element'=> 'input[name="srcbutton"]',
		'intro' => __('If you have typed the name correctly you will see the agent.')
		);
	$return_tours['tours']['monitoring_server_step_1']['conf'] = array();
	$return_tours['tours']['monitoring_server_step_1']['conf']['show_bullets'] = 0;
	$return_tours['tours']['monitoring_server_step_1']['conf']['show_step_numbers'] = 1;
	$return_tours['tours']['monitoring_server_step_1']['conf']['next_help'] = 'monitoring_server_step_2';
	//==================================================================

	return $return_tours;
}

The code is always a function with the name clippy_start_page and the tours in this page.

The tour is several steps and sometimes this tour says what it is the next tour.

And a tour is showed when is call from the function clippy_go_link_show_help or other tour.

The tours is saved in PHP associative array (aka hash) and return to the function clippy_start_page:

$return_tours = array();
$return_tours['first_step_by_default'] = <bool>;
$return_tours['tours'] = array();
$return_tours['tours']['<step_foo_1>'] = array();
$return_tours['tours']['<step_foo_1>']['steps'] = array();
$return_tours['tours']['<step_foo_1>']['steps'][] = array(
  'element'=> '<dom_selector>',
  'intro' => '<html_text_in_the_bubble>'
  );
...
$return_tours['tours']['<step_foo_N>']['steps'][] = array(
  'element'=> '<dom_selector>',
  'intro' => '<html_text_in_the_bubble>'
  );
$return_tours['tours']['<step_foo_1>']['conf'] = array();
$return_tours['tours']['<step_foo_1>']['conf']['show_bullets'] = <bool>;
$return_tours['tours']['<step_foo_1>']['conf']['show_step_numbers'] = <bool>;
$return_tours['tours']['<step_foo_1>']['conf']['next_help'] = '<next_steep_bar>';

2 Context Help

It is more or less equal to the clippy but it is programmly. You set in your PHP where and when it is show the clippy agent, for example this screenshot:

Context help example.png

The PHP function to call:

clippy_context_help(<name_context_help>);

And you need a file with the same name:

include/help/clippy/<name_context_help>.php

The code is similar to clippy tour unless the:

  • name of function must be clippy_<name_context_help>
  • The tour must set the field help_context to true:
$return_tours['help_context'] = true;
  • And the first step of the tour for to hook to clippy icon loss in the page is diferent:
$return_tours['tours']['module_unknow']['steps'][] = array(
  'init_step_context' => true,
  'intro' => '<html>');
 There is not element field and there is the field init_step_context.

A example of context help:

function clippy_module_unknow() {
	
	$return_tours = array();
	$return_tours['first_step_by_default'] = true;
	$return_tours['help_context'] = true;
	$return_tours['tours'] = array();
	
	//==================================================================
	//Help tour about the monitoring with a ping (step 3)
	//------------------------------------------------------------------
	$return_tours['tours']['module_unknow'] = array();
	$return_tours['tours']['module_unknow']['steps'] = array();
	$return_tours['tours']['module_unknow']['steps'][] = array(
		'init_step_context' => true,
 		'intro' => '<table>' .
			'<tr>' .
			'<td class="context_help_title">' .
			__('You have unknown modules in this agent.') .
			'</td>' .
			'</tr>' .
			'<tr>' .
			'<td class="context_help_body">' .
			__('Unknown modules are modules which receive data normally at least in one occassion, but at this time are not receving data. Please check our troubleshoot help page to help you determine why you have unknown modules.') .
			ui_print_help_icon ('context_module_unknow', true, , 'images/help_w.png') .
			'</td>' .
			'</tr>' .
			'</table>'
		);
	$return_tours['tours']['module_unknow']['conf'] = array();
	$return_tours['tours']['module_unknow']['conf']['autostart'] = false;
	$return_tours['tours']['module_unknow']['conf']['show_bullets'] = 0;
	$return_tours['tours']['module_unknow']['conf']['show_step_numbers'] = 0;
	//==================================================================
	
	return $return_tours;
}