Add new menu and view by a plugin

2018-03-19T11:12:59Z

Potable: "name" argument missing for the Surveymenu::staticAddMenu function.

How to write a plugin that adds a menu to the admin menubar & when clicked renders some content.

= 3.0.0.beta-3 and above =

Since 3.0.0 it is possible to manually add and create menu entries.
Depending on your plugin you can use this function as a benchmark to add either a menuentry or a full menu for your plugin.
Please also have a look at the manual page for menucreation.

For this special case there is the newly added plugin event "onPluginRegistration" that is called once when the plugin is discovered.

<syntaxhighlight lang="php">

public function onPluginRegistration(){
$pluginName = $this->get('pluginName');
//Maybe add a check for the correct pluginName here
//Check if the menu/menu entries are already created use yii database methods for that

$menuArray = array(
"parent_id" => 1, //1 -> main surveymenu, 2-> quickemenu, NULL -> new base menu in sidebar
"name" => "[your plugin menus name]",
"title" => "[your plugin menus title]",
"position" => "side", // possible positions are "side" and "collapsed" state 3.0.0.beta-2
"description" => "[your plugins menu description]"
);
$newMenuId = Surveymenu::staticAddMenu($menuArray);

// repeat this as often as you need it
$menuEntryArray = array(
"name" => "[name of the action]",
"title" => "[title for the action]",
"menu_title" => "[title for the action]",
"menu_description" => "[description for the action]",
"menu_icon" => "[icon for action]", //it is either the fontawesome classname withot the fa- prefix, or the iconclass classname, or a src link
"menu_icon_type" => "fontawesome", // either 'fontawesome', 'iconclass' or 'image'
"menu_link" => "[admin/]controller/sa/action", //the link will be parsed through yii's createURL method
"addSurveyId" => true, //add the surveyid parameter to the url
"addQuestionGroupId" => true, //add gid parameter to url
"addQuestionId" => true, //add qid parameter to url
"linkExternal" => false, //open link in a new tab/window
"hideOnSurveyState" => null, //possible values are "active", "inactive" and null
"manualParams" => "" //please read up on this setting as it may render the link useless
);
SurveymenuEntries::staticAddMenuEntry($newMenuId, $menuEntryArray);

}
</syntaxhighlight>

= 2.55 to 2.73 =

1. Create a new plugin, in our case called '''PageDemo'''. In the plugins/ folder, there should be a folder name called PageDemo and within it a class called PageDemo inheriting \ls\pluginmanager\PluginBase. Also create a folder called views/ in your plugin folder and add index.php to it.

plugins/
PageDemo/
PageDemo.php
views/
index.php

This is the PageDemo.php file so far, with basic settings:

<syntaxhighlight lang="php">
<?php

use \ls\menu\MenuItem;
use \ls\menu\Menu;

/**
* Demo for adding new admin page in LimeSurvey 2.56.1
* @since 2016-11-22
* @author Olle Härstedt
*/
class PageDemo extends \ls\pluginmanager\PluginBase
{
static protected $description = 'Short demo on how to show a new admin page';
static protected $name = 'PageDemo';
protected $storage = 'DbStorage';
}
</syntaxhighlight>

2. Subscribe to event '''beforeAdminMenuRender''' to append menus:

<syntaxhighlight lang="php">
/**
* Init plugin and subscribe to event
* @return void
*/
public function init()
{
$this->subscribe('beforeAdminMenuRender');
}
</syntaxhighlight>

3. Add a method called '''beforeAdminMenurender''' to the plugin class and append a menu object to the event:

<syntaxhighlight lang="php">
/**
* Append menus to top admin menu bar
* @return void
*/
public function beforeAdminMenuRender()
{
// Create the URL to the plugin action
$url = $this->api->createUrl(
'admin/pluginhelper',
array(
'sa' => 'fullpagewrapper',
'plugin' => $this->getName(),
'method' => 'actionIndex' // Method name in our plugin
)
);

// Append menu
$event = $this->getEvent();
$event->append('extraMenus', array(
new Menu(array(
'label' => 'Menu label',
'href' => $url
))
));
}
</syntaxhighlight>

4. Add the method actionIndex to the plugin class. This method will call '''renderPartial''' to render a view in the views/ folder.

<syntaxhighlight lang="php">
/**
* @return string html
*/
public function actionIndex()
{
return $this->renderPartial('index', array(), true);
}
</syntaxhighlight>

5. Add some HTML to the view index.php in the views/ folder

<syntaxhighlight lang="html">
<div class='container-fluid'>
<h3 class='pagetitle'>A page</h3>
<div class='row'>
<div class='col-sm-6'>
<p>Left column</p>
</div>
<div class='col-sm-6'>
<p>Right column</p>
</div>
</div>
</div>
</syntaxhighlight>

6. Result

[[File:pagedemo.png]]

= 2.06 lts/2.6.x lts =

1. Create a new plugin. let us call it Rewards

2. register for events afterAdminMenuLoad and newDirectRequest in the constructor

3. implement the above methods methods in the new plugin class

4. In the method afterAdminMenuLoad, add a new menu item and link it to
admin/plugins/direct?plugin=<plugin_name>&function=<plugin_action>
e.g
admin/plugins/direct?plugin=rewards&function=assignRewards
The best way to to this would be to make use of the createURL method:
'href' => $this->api->createUrl('plugins/direct', array('plugin' => 'Rewards', 'function' => 'assignRewards')),

5. implement the method newDirectRequest

public function newDirectRequest(){
$event = $this->event;

// you can get other params from the request object
$request = $event->get('request');

//get the function name to call and use the method call_user_func
$functionToCall = $event->get('function');
$content = call_user_func(array($this,$functionToCall));
//set the content on the event
$event->setContent($this, $content);
}

6. implement the method plugin_action, in our case it is assignRewards().
In this method currently i am just trying to return some dummy content, you can have sophisticated page rendered.

<nowiki>public function assignRewards() {
$content = "<h1> plugin content set succesfully </h1>";
return $content;
}</nowiki>

7. The full Rewards.php
[[File:Rewards1.zip]]

8. This is how the UI looks now.
[[File:Screenshot_2014-08-21_01.34.05.png]]

LimeSurvey Manual - User contributions [en]

Add new menu and view by a plugin