CalendarScript - Calendar Documentation: Plug-ins

Concept

Plugins allow a developer to extend or customize the functionality of CalendarScript without modifying the distributed code or files. Entirely new functions can be added to the script and distributed to others, enabling CalendarScript to become very modular and flexible.

A Plugin is simply a directory containing files that conform to the Plugin specifications (below). Once a Plugin is installed and enabled, the application will look for Perl subroutines, template files, etc within files in this directory. Everything needed for a Plugin to operate is contained in one single directory.

An example Plugin is included in the distribution which gives you an idea of what can be done and how simple it is. This Plugin doesn't do anything useful, but is provided as a reference to get a Plugin developer started.

What Plugins Can Do

A Plugin can do any of the following, in any combination:

Add a new option to the Admin main menu and drop-down navigation menu, and define which permissions are required in order for the option to be visible.
Add a new type of permission which can be assigned to users in the User Permissions screen.
Add a new display template to the Admin application. For example, to provide some type of new functionality.
Over-ride an existing display template. For example, to change how the Schedule Event screen looks and behaves without modifying the distribution template.
Add new code to the Admin application to process a custom command.
Over-ride the functionality of an included command (such as login or add_event) by either executing some code before the defult action, executing code after the default action has been done, or completely replacing the default action.
Over-ride functionality of the calendar display program

The Basics

As mentioned before, a plugin is just a directory which contains files. This allows a Plugin to be distributed as a zip file which can simply be unzipped in calendarscript/plugins/ and instantly be available through the admin interface. There are no code changes or configuration file changes necessary - once the files are unzipped into the correct directory, the plugin will be available to be activated.

Each plugin has its own directory, and these directory names must be unique. Inside this directory one file is required - readme.txt. This file contains information about the plugin which will be shown in the Manage Plugins screen in the admin interface. The example plugin shows the format of the file:

# Example Plugin
name:Test Plugin
description:This is a test plugin...
author:Matt Kruse
author_email:matt@calendarscript.com
url:http://www.CalendarScript.com/

Lines beginning with # are comments and are ignored. The other lines are simply a field title and its value, separated by a colon (:). The only required field is 'name'. The others will be displayed in the Manage Plugins screen to provide more information to the user, if they are supplied.

Adding Permissions

A plugin may wish to add functionality that is only available to users with certain permissions. For example, you may wish to add a screen to the admin application, and restrict the screen to only certain users. To do this, the plugin needs to add a new permission to the User Permissions screen in the admin application, so that users may be granted this permission.

This is accomplished by adding a file to your plugin directory named permissions_list.txt. It can contain one or more specific permissions to be added to the application. The format of the file is tab-separated values like this example:

#type	name	description
GLOBAL	SOME_ACTION	Perform some action specific to a template

The first field is either 'GLOBAL' or 'LOCAL' which determines which section of the permissions screen the permission shows up as.
The second field is a unique identifier for the specific permission. This field can then be used in templates and actions to determine if the current user has this permission enabled or not.
The last field is the description of the permission. This is what will be displayed in the permissions screen.

Adding Admin Menu Options

If a plugin adds a new screen to the admin application, you will probably want to add an option to the Main Menu and the command drop-down list to navigate to your new screen. This is done by adding the file 'command_list.txt' to your plugin's directory. The format of the file is tab-separated values like this example:

#category   title   description   link   permissions_required
Calendar   Plugin Test   
An Example   template=test.html   GLOBAL:SOME_ACTION

The first field is the category under which the new command option will appear. For example, 'Calendar' or 'Events' or 'Calendar Options'.
The second field is the title of the command option. This is the text that will become the link in the Main Menu, and what will appear in the drop-down menu.
The third field is the description of the command option. This is optional, and will appear after the title in the Main Menu only.
The fourth field is the link to be executed for the command option. Except for very rare conditions, this will be in the format 'template=file.html'. This means that the admin template 'file.html' will be loaded when the command option is selected.
The final field defines which permissions the user must have in order for this command option to appear in their menu. If left blank, all users will see the added command option. Otherwise, you can specify a comma-separated list of permissions in the format [GLOBAL|LOCAL]:PERMISSION. If the user has any of the permissions listed, the option will be available to them. A common scenario will be to add a new permission using the permissions_list.txt file, and then add a command option which requires that permission in order to be executed.

Adding And Overriding Templates

If your plugin adds a new template file for display in the admin application, simply include the HTML file in the plugin directory. It will automatically be found when the screen is requested. You can add any number of templates required by your plugin.

You may also over-ride existing templates in the admin application. Simply create a template file with the same name as a template file in the calendarscript/templates/Admin/English directory. The file will be detected, and your template will be used instead of the default template file. This way you can add custom functionality to the application without actually changing the default distribution files. For example, you may wish to create a plugin which changes the Schedule Event screen to allow for a different interface, or limit the scheduling possibilities for users.

Adding Custom Functionality

The true power of plugins comes from their ability to change the underlying functionality of the CalendarScript application, and to add new functionality. This is done by writing Perl code and placing it in files with specific filenames, containing subroutines with specific names.

Inside the CalendarScript application are embedded a variety of "hooks". That is, places in the application where external functionality can be plugged in and executed. A plugin can define functionality for any of these "hooks" which will be executed when they are encountered.

The main admin application code consists mostly of code to execute for various commands which are sent from the templates. For example, 'login' or 'add_event' or 'delete_user'. Your plugin can supplement the default functionality by doing one of the following:

Execute some code before the default command-processing code, and then let the default code continue to execute.
Execute some code before the default command-processing code, and choose not to execute the default code.
Execute some code after the default command-processing code has completed.

This type of functionality is probably best explained through an example, and for this example the 'add_event' command will be used. If you examine the code in calendar_admin.pl, you'll see the 'add_event' section, and also where the &handleCustomFunction() "hooks" are located. The following are examples of how the above three types of hooks would be implemented:

Your plugin may customize the adding of events by doing certain validation checks before allowing the event to be saved. For example, checking to see if there is any other event with the same name or at the same location. You would therefore need your plugin to perform some action before the event is added, and based on some result either continue with adding the event or abort the rest of the add_event functionality.

The command name is 'add_event' so the "hook" in this situation is named 'before_add_event'. In your plugin's directory, create a file named 'before_add_event.pl' and in it define a subroutine named 'before_add_event()'. This file will be processed before the event is added, and the before_add_event() subroutine will be called. You may perform any functionality in this subroutine that you wish.

Your subroutine should return either true (1) or false (0). If it returns true, then this tells CalendarScript that everything has been taken care of, and the rest of the add_event processing code should NOT be executed. If it returns false, then it means that the subroutine has not taken care of everything, and the rest of the processing should continue. In this way, your plugin can completely override a piece of the functionality in the CalendarScript application, or it can supplement it.
Another possibility is that you may want to send an email when an event is added. For this functionality, you would want to add code to be executed after the add_event processing code is complete and the event was actually added. In this situation, the hook is named 'after_add_event'. The file you would create is called 'after_add_event.pl' and the subroutine name is called after_add_event(). The return value of this subroutine doesn't matter, because there is no more additional code to be conditionally executed.

To find out exactly which hooks are available and when they are executed, examine the source code in the application.

Finally, you can define a custom command in your template, and define the subroutine required to process that command. This way, you can add totally new functionality rather than hooking into an existing command-processing routine.
An example would be a plugin which adds entirely new functionality to the application, defines a template to get user input, and then defines a custom command to do something with that input.
If your command name is 'add_stuff' for example, then the hook name becomes 'command_add_stuff'. Therefore, the plugin would need to have a file named 'command_add_stuff.pl' and define the subroutine &command_add_stuff().