As you know CandyCane is CakePHP based Redmine clone. We have released CandyCane v0.8.4 just a hour ago. From now CandyCane is ready to plug your plugin! Making perfect product for everyone should be too far goal. But plugin system give you ability to change CandyCane as you like. I really wish you make your plugin for missing features like beautiful charting, more agile like dashboard. YOU CAN MAKE IT ON CAKEPHP WAY!
Let’s get walk through the overview of plugin system for CandyCane.

Basic of plugin for CandyCane

CandyCane plugin is actually CakePHP plugin. You can put CakePHP MVC based codes as plugin. Also you can interact with Models, Helpers, Components of CandyCane. For example, you can pull ticket data, project data or any other data from CandyCane model classes. Pages you made need to be integrated with CandyCane. CandyCane has some API for that. You will call those API from init.php in your plugin.

Adding new page to top menu

On your want to run your page as a application wide page, your page should be added into top left menu. To adding link to your page there, use MenuContainer object from init.php in your plugin.

$menuContainer = ClassRegistry::getObject('MenuContainer');
$menuContainer->addTopMenu(
	array(
		'url' => '/cc_nyancat/nyan/index',
		'class' => 'nyan-cat',
		'caption' => 'Nyan Cat',
		'logged' => false,
		'admin' => false
	)
);

Adding new page in project level tab

Usually pages works as an item under some project. In that case, your page should be added as project level item. to do that, use MenuContainer class again. Also route setting must be added to determine which is the current project.

$menuContainer->addProjectMenu(
  'nyancat',
  array(
          'plugin' => 'cc_nyancat',
          'controller' => 'cc_nyancat_chart',
          'action' => 'index',
          'class' => '',
          'caption' => 'Nyan Down Chart',
          'params' => 'project_id',
          '_allowed' => true // for bypassing permmission system.
  )
);
// make sure put new route setting which includes project_id
App::import('Core','Router');
Router::connect('/projects/:project_id/nyanchart/:action', array('plugin' => 'cc_nyancat','controller' => 'cc_nyancat_chart'));

Injecting HTML piece to various places

When you want to change existing pages in CandyCane, you can interrupt page rendering based on template. You can hook specific template by HookContainer class. As long as templates are separated well, you can inject your code into existing page. In this example, Nyan Cat will be shown after the template of related issues.

$hookContainer = ClassRegistry::getObject('HookContainer');
$hookContainer->registerElementHook(
	'issues/relations', // target element name.
	'../../plugins/cc_nyancat/views/elements/nyancat', // additional template you want to inject.
	false // it should be true when you want to inject before the target template.
);

Installing plugin

Installing plugin requires manual step currently. It should be automated some time in future. But actual step is just unpack plugin and place it under app/plugins. All candycane plugin must be named starting with “cc_”. CandyCane will find init.php under the directory like “app/plugins/cc_*”.

To see detail, please try cc_nyancat plugin on my github page.
I hope you enjoying CandyCane and making your cool plugin on that.

Thanks.