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:
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:
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.# Example Plugin name:Test Plugin description:This is a test plugin... author:Matt Kruse author_email:[email protected] url:http://www.CalendarScript.com/
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:
The first field is either 'GLOBAL' or 'LOCAL' which determines which section of the permissions screen the permission shows up as.#type name description GLOBAL SOME_ACTION Perform some action specific to a template
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:
The first field is the category under which the new command option will appear. For example, 'Calendar' or 'Events' or 'Calendar Options'.#category title description link permissions_required Calendar Plugin Test
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:
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().