Handlers
All plugin handlers have a number of common features:
- they are executable files (must have execution rights for the root user and group) located in the /usr/local/mgr5/addon directory;
- ispmanager executes handlers from the root user;
- they output to stdout XML, which is interpreted by ispmanager UI subsystem;
- descriptions of pages of various kinds and their elements, along with the information to be displayed — list items, form field values, etc.;
- errors to be displayed;
- the results of successful execution of actions that result in a page transition, etc.
- they have access to a number of environment variables that ispmanager provides them with during the command execution.
Since the handler is simply an executable that outputs XML, it is not difficult to implement it in almost any programming language.
A few examples can be found here: Examples of handlers in PHP, Python, Node.
Debugging handlers
Often in plugin development, when accessing the corresponding plugin func (e.g., when navigating to a created menu item), this notification appears:
helloworld.sh plugin terminated with an error or returned an invalid XML.
In this case, you need to find out what has happened: the handler failed to execute, or the handler returned invalid XML.
Since the handler is an executable file, one possible way to debug it is to simply execute it from the command line, e.g. for a plugin with Hello, world:
/usr/local/mgr5/addon/helloworld.sh
The situation becomes more complicated if the handler reads some environment variables, then you need to set appropriate values for them: for example, for the example below about reading form fields:
export PARAM_name=Vasya
/usr/local/mgr5/addon/helloworld.sh
Benefits of using mgrctl
- you can specify different output formats (with the
-o
option, the-o devel
and-o json
options are good for debugging); ; - you can pass values of form fields;
- you can execute the request on behalf of another user by adding su=user_name as a parameter.
Disadvantage of mgctl
mgrctl outputs the result of processing the XML that ispmanager received from the handler, and if the handler failed or returned invalid XML, we will get the error XML instead of the handler output, and it will do little to help us understand what went wrong.
Example of mgrctl call for Hello, World! plugin with passing form field value on behalf of user vasya:
mgrctl -o devel helloworld name=Vasya su=vasya