Extension management in Cotonti

Description of basic Extension management tasks

This page is not translated yet. Showing original version of page. You can sign up and help with translating.

#1. Contents

1. Introduction
2. Understanding Cotonti Extensions
3. Downloading and unpacking an Extension
4. Using Administration panel to install a Extension
5. Extension configuration, parts and hooks
6. Setting Extension permissions
7. Adding TPL tags to your theme files
8. Pause and Uninstall options

#2. Introduction

This little "howto" (almost the same for Genoa and Siena branch) will shortly describe the management of Cotonti third party Extensions

What is a "Extension"?

Intuitively, this is php code which "extends" Cotonti with additional features or functionality.

Note: Historically there are two type of Extensions able to be installed in Cotonti. It's a Modules and a Plugins. There is no big difference one from another for end-user or Site Administrator, so here we do not going deeper to any specific, but describe common parts of it.

More specific info about Extension types you can found in «Introduction to extension development» article.


What are Extensions for?

Sometimes you'll need something very specific for your site to support, like for example image gallery or a blog system. The Extension size and complexity depends only on Extension developers, you will find the Extension that are either very small (covering only one needed functionality) or quite big (like sophisticated media galleries).

Are there Cotonti Extension available already?

Yes, you can download many of them here.

#3. Understanding Cotonti Extensions

Cotonti is build in such a way that it can be extended through the plugin/modules system. Just as in every system, the Extension must obey some specific rules in able to be installed and included into the website engine correctly. It concerns the Extension structure, the specific folder in which plugin files should be placed and also post-installation routines.

It's also nice to know that Extension 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 Extension?

You will need:
1. An unpacking program (e.g. unrar, unzip ot other)
2. Some FTP client (e.g. Putty, Total Commander, FileZilla)
3. Basic knowledge about file editing (considering you already installed Cotonti, this is not a problem)

#4. Downloading and unpacking an Extension

You can download many Extensions here. Then, navigate to the directory in which the Extension package was downloaded, and unpack it.

Usually in the unpacking result you'll see either a folder named as a Extension, 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.

Note: Depend on Extension type (Plugin or Module) unpack content should be placed in corresponding folder (Plugins or Modules respectively), located in root. This is most tricky part of install process, so be attentive to inspect its type. Often this info specified in Extension docs file or Extension description page on this site.

 

Below you get step-by-step instruction on example of instaloing a some Plugin.

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.

#5. Using Administration panel to install an Extension

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 "codename" (plugin-slug) of the plugin. It's best to search the plugin by it's slug 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 title, and there, in the "Options" section, click "Install".

Cotonti will show you installation progress log. 

#6. Extension configuration, parts and hooks

After install is done without errors you can see plugin information screen. You can access it anytime later.


The most interesting parts are highlighted by a orange frame.
 

#6.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 page by clicking the "Configuration" button, and play with possible configuration options (see certain Extension docs for description).
 

#6.2. Extension Parts and Hooks

As you can see, this plugin consists of one Part: the main part, being «hooked» up to users.details.tags.ajax Cotonti system part. By "being hooked up" I mean that the plugin code is called in specific places in the system, called "hooks". More detailed info about it located in «Hooks» article.

#7. Setting Extension permissions

Usually Extensions comes up with default set of permissions (set by its developer), but generally you should never install a plugin and let it function without checking the permissions. Permissions set right means control over website. Every Extension has its own permission table, you can access it by clicking the «Rights» button (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.

See more info in related articles: «Users and Groups», « What is Cotonti ACL System?».

#8. Adding TPL tags to your themes

Our example Plugin to be invoked on Site requires a «Tag» to be added to Cotonti theme template file. In the plugin information screen (refer to the screenshot above in "Ext ension 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. 

More info about templates and its TAGs see here and here.

#9. Pause and Uninstall options

There are two Extension management options, useful in different situations.

Pause all - It will pause the output of an Extension, but won't delete configuration entries. It's a temporary solution for e.g. testing purposes. You can Unpause the Extension anytime later, instantly.

Un-install - It will delete all configuration entries and remove the Extension and all of its data from the system.

Note: it will NOT remove the Extension files physically. But removes all Extension working data such as cache files, related SQL tables, structures, etc.

Note that you lose your Extension configuration entries, which sometimes is quite complex. For testing purposes or temporary disabling Extension, the "Pause" functionality is recommended.
Of course, if you uninstalled Extension but changed your mind, you can install it again.


1. Trustmaster  2009-07-31 03:12
Nice article, thanks a lot!
2. tensh  2009-07-31 03:20
No problem ^^ My pleasure!
3. musiconly  2009-07-31 03:34
great job tensh!
Alleen geregistreerde gebruikers kunnen reacties plaatsen.