Description of basic plugin tasks
1. Introduction
2. Understanding Cotonti plugins
3. Downloading and unpacking a plugin
4. Using Administration panel to install a plugin
5. Plugin configuration, parts and hooks
6. Setting plugin permissions
7. Adding TPL tags to your skins
8. Pause and Uninstall options
This little "howto" will shortly describe the management of Cotonti third party plugins.
What is a "plugin"?
Intuitively, this is php code which "plugs into" Cotonti additional features or functionality.
What are plugins for?
Sometimes you'll need something very specific for your site to support, like for example image gallery or a blog system. The plugin size and complexity depends only on plugin maker's invention, you will find the plugins that are either very small (covering only one needed functionality) or very big (like sophisticated media galleries).
Are there Cotonti plugins available already?
Yes, you can download many of them here.
Cotonti is build in such a way that it can be extended through the plugin system. Just as in every system, the plugins must obey some specific rules in able to be installed and included into the website engine correctly. It concerns the plugin structure, the specific folder in which plugin files should be placed and also post-installation routines.
It's also nice to know that plugins itself can be built very differently. Some of them can be in a form of standalone page, another will add functionalities to already existing Cotonti subsystems, other will require running additional sql, which will create extra tables in the database.
What do I need to install plugin?
You will need:
1. A good unpacking program (e.g. Winrar, Winzip and others)
2. A good FTP client (e.g. Putty, Total Commander)
3. Basic knowledge about file editing (Considering you already installed Cotonti, this is not a problem :-) )
4. Sometimes: basic MySQL knowledge and management
You can download many plugins here. Then, navigate to the directory in which the plugin package was downloaded, and unpack it.
Usually in the unpacking result you'll see either a folder named as a plugin, or the folder + installation guide and license documents. In either way, the most interesting for you is the main plugin folder.
Check the contents of a plugin folder. Sometimes you'll find there a "doc" subcategory containing installation instructions, or a "readme.txt", "install.txt" or other form of plugin documentation. Also, there might be a file in which required sql queries are written.
The plugin folder must be copied into the "plugins" directory, located in Cotonti root.
In fresh Cotonti install, the contents of /plugins directory would look like this:
You can see many existing plugins there. In our example, we will install the "Userpages" plugin.
So, in your FTP, connect to your webhost, navigate to /plugins directory and copy the whole "userpages" plugin folder there.
Then, you need to log into your Cotonti website and enter the Administration area. Navigate to "Extensions" section, and find your newly uploaded plugin on the list:
The name of the plugin folder is also the "code" of the plugin. It's best to search the plugin by code since sometimes the plugin full name might be extended.
As you can see, our newly copied plugin has the flag "Not installed". In order to install plugin, click on the plugin name, and there, in the "Options" section, click "Install".
Cotonti will show you installation progress screen: after it's done, click "Click here to continue...".
After you click "Click here to continue...", you'll be shown a plugin information screen. You can access it anytime later.
The most interesting parts are highlighted by a red frame.
1. Configuration
It seems that this plugin requires setting up configuration. It's nice to check it out as sometimes you'll find many interesting features there. Go to "Configuration" by clicking the "Edit" link just next to the "hammer icon", and play with possible configuration options.
2. Plugin Parts and hooks
As you can see, this plugin consists of two parts: the ajax part (responsible for fancy ajax behaviour), and the main part, being hooked up to users.details Cotonti system part. By "being hooked up" I mean that the plugin code is called in specific places in the system, called "hooks". You can find them easily by viewing system files in system/core Cotonti directory.
Usually plugins come up with default set of permissions, but generally you should never install a plugin and let it function without checking the permissions. Permissions set right means control over website. Every plugin has its own permission table, you can access it by clicking the little "user icon" in the "Rights" menu (refer to the screenshot above).
Let's take a look at permission table of our newly installed plugin:
We can see basic permissions for basic usergroups available on the site. If you have added custom usergroups earlier, they will also be shown on the list.
The permission legend is described below:
Read - means that user from a group can view the plugin. If you uncheck this permission for e.g. Members, this group will not be able to view the plugin and will be presented by a blank field (in case of plugin tags) or a "permission denied" error message (if a plugin is a standalone page)
Write - means that user can add content to a plugin. Not all plugins make use of this permission.
Admin - means total control over a plugin. Not all plugins make use of this permission, but generally you'd like to have it unchecked wherever possible.
Our example plugin requires a "Tag" to be added to Cotonti theme file. In the plugin information screen (refer to the screenshot above in "Plugin configuration, parts and hooks" section), at the bottom of the page, you can see which Tag should be added where. In our case, we need to add the {USERS_DETAILS_USERPAGES} tag to the TPL file named users.details.tpl.
In order to do so, copy the Tag to the clipboard (select the text and press Ctrl+C, for example), navigate to /themes/YourTheme/ directory in Cotonti root and find there users.details.tpl file. Edit it in your favourite text editor and paste the Tag wherever you want it to appear. In my case, I would create an additional table row and insert the tag there:
And that's all! Your plugin additional functionality can be viewed in user details page. :)
There are two plugin management options, useful in different situations.
Pause all - It will pause the output of a plugin, but won't delete configuration entries. It's a temporary solution for e.g. testing purposes. You can Unpause the plugin anytime later, instantly.
Un-install - It will delete all configuration entries and remove the plugin and all of its data from the system.
Caution: it will NOT remove the plugin files physically.
Note that you lose your plugin configuration entries, which sometimes is quite complex. For testing purposes or temporary disabling plugin, the "Pause" functionality is recommended.
Of course, if you uninstalled plugin but changed your mind, you can install it again.
Nice article, thanks a lot!