Events

From ISPWiki

Jump to: navigation, search

Events allow to extend functionality of a control panel by means of adding customer CGI-programs or scripts that will start automatically during or after performing a function.

Event handlers may have the following attributes:

  • (before="yes") Handlers that start before a function has been executed. Such events cannot call the control panel. However, the xml that they return will be merged with that of a control panel. If this event returns an error, the manager function handler won't be called at all.
  • (after="yes") Handlers that start after a function has been executed. If it is a form, the script will start when the form opens and closes by clicking OK. The sok parameter allows to find out the time when it was run. These events cannot call a control panel. The xml that they return will be merged with that of a control panel. Unlike the previous type, they will be called only if the manager function has been successfully finished.
  • (final="yes") Independent handlers that start before or after a function has been executed and do not affect its result. Such handlers can themselves call the control panel's functions.
  • (priority="hi") will start first (prior to the handlers for which this attribute is not set). We recommend using this attribute if the handler edits form metadata.

Consider the following tags when merging xml:

  • error - an error occurred while processing an event. No tags will be processed after this tag.
  • redirect - redirect. Content of this tag will be redirected to client in the JavaScript format. It is used when creating Installation Wizards, which provide step-by-step instructions on how to install and configure a control panel. For example: location='ispmgr?func=usrparam' will open the form with user parameters.
  • ok - redefines the value of the ok tag.
  • param - these tags will be ignored.

A customer CGI-program has the same input as a control panel. It sends a correct XML to STDOUT.

The XML handler will receive an XML with description of forms, tables and messages. It should send an XML to STDOUT, which will replace the one used by a control panel. The input XML may be returned as well.

To locate a user who called a control panel's function that made your event to be executed, use the REMOTE_USER environment variable. Make sure that this user is authorized.

To add your event handler, you need to create a file ispmgr_mod_name.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
  <handler name="myhandler" type="cgi">
    <event after="yes">eventname</event>
  </handler>
</mgrdata>

and place it into /usr/local/ispmgr/etc/

myhandler - name of your program. Locate it in the /usr/local/ispmgr/addon directory

eventname - name of an event. You can get a complete list of events with the eventlist control panel function, for example, using mgrctl:

/usr/local/ispmgr/sbin/mgrctl eventlist


Example

Following is an example that shows you how to use events in ISPmanager.

Suppose, you want a user to get to your home page (for example, ispsystem.com) upon logged out.

To do that, you need to create the following XML document that will describe your logon event handler:

<?xml version="1.0" encoding="UTF-8"?>
<mgrdata>
	<handler name="redirect" type="xml">
		<event after="yes">logon</event>
	</handler>
</mgrdata>

Create the handler addon/redirect:

#!/bin/sh
 
if [ $SESSION_LEVEL -ne 0 ]; then
	echo '<?xml version="1.0"?>'
	echo '<doc><redirect>location="http://ispsystem.com"</redirect></doc>'
else
	cat
fi
Was this helpful? Yes | No
Views
Personal tools