Making your own plugins

With the new plugin system of phpFanList 3 it's even easier to create your own plugins.

How to?

Plugins should contain 2 parts: a function that actually handles the work of the plugin and secondly a call to the AddPlugin function to add your defined function to the list of functions to execture. Let's take the countryflags plugin as an example:

<?php 
	function CountryFlags($member) {
	}

	AddPlugin('show_members_country', 'CountryFlags');
?>

Note: plugins are PHP files, so they should start with <?php and end with ?>.

As you can see, there are 2 parts: the function to handle the work, in this case: "CountryFlags" and the call to the AddPlugin function to add the plugin on a certain event. In this example the event is "show_members_country" (more on events later). What this means is that your function CountryFlags will be used when show_members_country occurs.

Parameters

The function you define has 2 important parts: the parameters (if any) it takes in and the result it returns. Depending on the event, your function needs to take a parameter. In the example you need the parameter $member because you get the current member object of which you can display the country.

Returning value

The second important part is what the function returns. A function can either return nothing or can return text. Returning nothing is done as follows:

<?php 
	function CountryFlags($member) {
		return false;
	}

	AddPlugin('show_members_country', 'CountryFlags');
?>

or

<?php 
	function CountryFlags($member) {
		return NULL;
	}

	AddPlugin('show_members_country', 'CountryFlags');
?>

Returning text on the other hand, can be done like this:

<?php 
	function CountryFlags($member) {
		if (!is_null($member->country)) { // Check for country set
			return $member->country;
		} else {
			return 'No country';
		}
	}

	AddPlugin('show_members_country', 'CountryFlags');
?>

Events

An event can best be viewed as something that can occur on a page. As in the example above the event was show_members_country, this means when the member's country is shown. By using the AddPlugin function, you can override the default behavior of this event and create your own, like displaying a flag instead of the country's name.

There are a few events available that you can use in your plugins:

show_affiliates
Occurs when affiliates are shown with the ShowAffiliates function.
show_members_country
Occurs when the member's country is shown in the member list.
Parameter (object): $member
show_members_custom
Occurs when the member's custom field is shown in the member list.
Parameter (object): $member
show_members_id
Occurs when the member's id is shown in the member list.
Parameter (object): $member
show_members_mail
Occurs when the member's e-mail address is shown in the member list.
Parameter (object): $member
show_members_name
Occurs when the member's name is shown in the member list.
Parameter (object): $member
show_members_url
Occurs when the member's url is shown in the member list.
Parameter (object): $member
show_news
Occurs when news items are shown with the ShowNews function.
show_news_content
Occurs when the content of a single news is shown.
Parameter (object): $newsitem
show_news_item
Occurs when a single news item is shown.
Parameter (object): $newsitem
show_news_title
Occurs when the title of a single news items is shown.
Parameter (object): $newsitem

Guidelines

Finally, there are a few guidelines that are best to follow:

  1. A plugin should be standalone. Which means that when you remove a certain plugin from phpFanList, it doesn't break other plugins.
  2. phpFanList supposes that plugins are located in the plugins directory. However, the plugin diretory isn't at the same location for every fanlisting, not even relative to the fanlisting. It is therefore best to use the PHPFANLIST_PLUGINS constant when you're using URLs.
  3. The filename of the plugin should be something.plugin.php (where something is the name of your plugin). This so that the admin can find your plugin.