If you want to just change the look and feel of your CWIS site, then you're probably better off creating a new interface, rather than a plugin. If you want to add a specific feature or modify a specific bit of CWIS functionality, then a plugin may be the right choice.
The base name is used for the name of the PHP file that will contain your plugin. So for our ListSubscriber plugin the plugin file name would be ListSubscriber.php
.
Once you've created your plugin file, it should be placed in the /local/plugin
directory in your CWIS installation.
class ListSubscriber extends Plugin { function Register() { $this->Name = "State University Library Mailing List Subscription Plugin"; $this->Version = "1.0"; $this->Description = "This plugin will add new users to the StateLib " ." mailing list when they verify their CWIS account, and remove" ." them if their account is deleted."; $this->Author = "John Doe"; $this->Url = "http://library.state.edu/cwisdev/listsubscriberplugin.html"; $this->Email = "jdoe@state.edu"; $this->Requires = array( "CWISCore" => "1.9", ); } };
The only attributes that must be set are Plugin::$Name and Plugin::$Version, but assigning values to the others is strongly encouraged, particularly if you may be sharing your plugin with others. The Plugin::$Name attribute should contain a human-readable name for your plugin.
The Plugin::$Requires attribute is used to specify the minimum versions of other plugins that your plugin must have to run. The CWISCore
plugin can be required to ensure that your plugin is running under at least the specified version of CWIS. Specific descriptions of the other attributes can be found in the documentation for the Plugin class.
To hook into specific events, you'll add an implementation of the Plugin::HookEvents() method to your plugin class:
function HookEvents() { return array( "EVENT_USER_VERIFIED" => "AddUserToMailingList", "EVENT_USER_DELETED" => "RemoveUserFromMailingList", ); }
This method is called when your plugin is loaded, and allows you specify methods of your plugin class to be run at specific times, depending on the event type. With CHAIN events, for example, you might modify data before it's saved or before it's displayed, or with a FIRST event like EVENT_USER_AUTHENTICATION
you might connect CWIS to your own mechanism for authenticating user logins.
A list of the events currently available to hook onto can be found on the CWIS Event Callbacks page. This list will expand with each new version of CWIS, based on feedback from plugin authors about what other events they may want to hook onto. Plugins may also define their own events, for others to hook onto, by implementing a Plugin::DeclareEvents() method.
There are often values associated with an event that may be needed by plugins that want to hook into that event. For example, with the EVENT_USER_AUTHENTICATION
event it's very useful to have the login name and password that the user entered. These values are passed to the hooked methods as parameters, according to the parameter list defined for that event.
So for our ListSubscriber plugin, the method in our ListSubscriber
class to add a user might look something like this:
function AddUserToMailingList($UserId) { $UserToAdd = new User($UserId); $MLMngr = new MyMailingListManager(); if ($MLMngr->IsSubscribedToList($UserToAdd->Get("Email")) == FALSE) { $MLMngr->AddSubscriber($UserToAdd->Get("Name"), $UserToAdd->Get("Email")); } }
The parameters sent by each event are listed and described on the CWIS Event Callbacks page. It's important to make sure the method you hook accepts the right list of parameters and returns the right values, so that the code that signalled the event and any other plugins hooked onto the event execute correctly.
That covers the basics of how to implement a simple CWIS plugin. More advanced information can be found on the Advanced CWIS Plugin Implementation section and in the documentation for the base Plugin class.
If you have questions that aren't answered here, please sign up for the CWIS Users Discussion List and post them there. Other users may be able to provide help or insight, or may even already have a plugin available that already does what you need!