What is a plugin?

A plugin is a programme that interacts with software, in this case phpMySport, so as to increase that software’s functionality. By creating your own plugin, or by installing an existing plugin, you can considerably increase phpMySport’s capabilities. For example, you can integrate photo galleries, RSS feeds or even go over the news management already included in phpMySport and make some improvements.

Do you wish to create your own plugin? If so, please read the following instructions carefully. After studying the file hierarchy of a plugin, we’ll go step-by-step through the creation process before wrapping up with a concrete example.

File hierarchy of a plugin

PhpMySport’s "plugin" directory

PhpMySport has a directory "plugin/" in which downloaded or created plugins must be placed.

In the figure we see the plugin directory tree containing 2 plugins labelled "link" and "my_plugin".

Structure of a plugin

A plugin comprises 3 file types.

The first are vital and constitute the heart of the plugin. They are involved with the comprehension, functioning and integration of the plugin within phpMySport. The second are optional and depend solely on the needs of the plugin. Lastly, the third type deals with introducing the new functionality proposed by the plugin.

Necessary files

• conf.php : plugin configuration file
• include.php : file that links the plugin and phpMySport
• install.php : plugin installation assistant
• lg_xxxx_yy.php : language file for plugin xxxx
• tpl_xxxx.php : file listing the template pages used
• read_me.txt : description of the plugin
• index.html : empty file to secure the plugin

We’ll now go over in detail "conf.php", "install.php" and "include.php".

The file " conf.php "

As indicated by its name, "conf.php" contains information on the plugin configuration. It also acts as a link between phpMySport and the plugin. The variables it contains are used to detect and integrate it into the software.

Be careful then and do not modify the names of the variables used, otherwise phpMySport will be unable to detect your plugin!

Here is the basic information that " conf.php " must contain:

Variable	Example value(s)	Description
$plugin_name	My plugin	Plugin name
$plugin_idurl	Myplugin	ID used for the URL. Must be a word with no spaces or special characters.
$plugin_root	ROOT."/plugin/my_plugin"	Path to the plugin directory. Last character must not be a forward slash " / ".
$plugin_install	0 or 1	Indicates whether the plugin has been installed (1) or not (0).
$plugin_active	0 or 1	Indicates whether the plugin is active (1) or not (0).
$plugin_lang	array("fr","en")	Array containing the list of languages into which the plugin has been translated. A language is indicated by a two-letter abbreviation.
$plugin_page_admin	array("install","form")	Array containing the list of pages that are protected and reserved for the site administrator. Often this involves the installation file as well as forms for the addition and/or modification of data.

The file "install.php"

The file "install.php" is an installation file and is required for the easy installation of the plugin by future users. Most notably, it is used to:

• Execute SQL requests to modify the database, if necessary.
• Modify the plugin configuration file " conf.php " so as to activate it. During this stage, the variables $plugin_install and $plugin_active are set to value 1.

The file is accompanied by a template file, the latter producing a visual assistant for the user during plugin installation.

Note: future versions will most likely require an uninstall file.

The file "include.php"

The file "include.php" plays two roles:

• It makes use of the plugin common files: the language file, SQL requests, the list of template pages used and, if required, the functions and classes used.
• It allows inclusion of the .php file corresponding to the page called. The latter is stored in the variable $_GET[‘v1’].

Optional files

• sql_xxxx.php : all SQL requests used by the plugin
• bdd.txt : SQL requests necessary for plugin installation

Other files that introduce new functionality

There can be one or more of them. Their names are essentially unconstrained but should reflect the action they perform. For example, a file named "item_list.php" would correspond to a list of "item" elements.

Each such file is coupled to a template file of the same name but with extension .html. It is recommended that the template file and images used by the plugin be placed in a separate folder called "tpl". The list of template files must be indexed in "tpl_xxxx.php" files (where xxxx corresponds to the plugin name).

How does one create a new plugin?

Here are the various steps required to create a new plugin:

Step 1

In phpMySport’s "plugin/" folder, create a new directory with the name of your plugin. We will refer to this as the root folder of your plugin. In this new folder, create another folder called " tpl " where you will place the template pages of your plugin.

Step 2

As described previously, create all the files necessary to the correct working of your plugin (see the section File hierarchy of a plugin). Put them in the root folder of your plugin.

Step 3

If information has to be stored or archived, you may need to make use of phpMySport’s database and make certain modifications. To this end, think about your data structure and create a file .txt containing the (those) SQL request(s) for table creation and/or modification. This file will be necessary for the plugin installation. Note that you may also make use of one or more XML files in place of the database.

Step 4

One-by-one create those files that introduce the new functionality of your plugin. In these PHP files, it is strongly recommended to use phpMySport’s variables, constants and functions. If needed, you can implement your own functions. These files should be sufficiently commented and respect phpMySport’s development methodology. Remember to use the convert_url() function, the $page variable and to indicate the template file via which they are associated. Don’t forget to create the corresponding template files in the " tpl/ " folder, and to index and declare them in your page’s code.

Step 5

So you’re in the midst of implementing your plugin? You probably want to check the result of your code … for that:

• Execute your SQL request to modify the database (if necessary)
• Activate your plugin by setting the "$plugin_install" and "$plugin_active" variables to 1.

Open your web browser and enter the URL of your phpMySport site. The name of your plugin will appear in the main menu of the software.

Step 6

That’s it; your plugin is finally working? All that remains is for you to make it known and to diffuse it so that other phpMySport users can install it. To that end, go to the official phpMySport site, then category "extension" where you’ll find practical information on how to distribute your plugin.

Click here to see an example of a plugin creation (link)