API

Article Index

We are keen to construct the gallery on a way that it is accplicable universally. For this it is necessary to integrate other components, modules und plugins which aren't written by us (e.g. Community Builder, AlphaUserPoints or JComments to just mention a few).
For some, we already developed additional add-ons which establish a connection between the particular third party extension and JoomGallery. You can find them in our downloads and here is a small summary of all of them.

Since we aren't able to create JoomGallery add-ons for every available extension or some of you have a special intent JoomGallery offers a huge API, which you may use. So this article is mainly interesting for the developers among you.

If you have decided to write your own extension for JoomGallery you will find below a full description of the JoomGallery API.
Examining already existent extensions may also help you for your own development.

The API of JoomGallery is divisible into three main areas:

  • Interface class
    The interface class offers - once included in your extension - many useful functions in order to 'communicate' with the gallery and to query information or output images.
  • Module positions
    Inside JoomGallery, several module positions are built-in which you may use like the module positions of your template. Additionally they may be loaded very individually.
  • Plugin events
    For the diverse tasks the gallery executes or while displaying the views different events are triggered to which your plugins may react und influence the gallery.

Interface class

In order to use the interface class it needs to be included in your extension first. This happens with the follwing code:

$file = JPATH_ROOT.DS.'components'.DS.'com_joomgallery'.DS.'interface.php';
if(!file_exists($file))
{
JError::raiseError(500, 'JoomGallery seems not to be installed');
}
else
{
require_once $file;
$interface = new JoomInterface();
}

The variable '$interface' now holds the interface object (provided that JoomGallery is installed).

By now you are able to use the functions the interface provides.
A call looks like this, for example:

$interface->getPageHeader();

or like this if something you need is returned by the function:

$images = $interface->getPicsOfUser($userid);

The funktion 'getPageHeader' will be important if your extension shall output images or the like and you want to use the style definitions of the gallery, because it loads the CSS files of JoomGallery.

Please have a look at the interface class on your own ('components/com_joomgallery/interface.php'). There are descriptions in the header of every function, which list what the function does, what it returns possibly and which parameters it needs.

At this point only the function 'addConfig()' shall be mentioned additionally. With this one, you are able to configure the interface. For example, you may define the method which will be used to open an image:

$interface->addConfig('openimage', 6);

The number 6 is mapped with Slimbox, other assignments are listed below:

0 => Default view
1 => New window
2 => JavaScript window
3 => DHTML Container
5 => Thickbox3
6 => Slimbox
12 => additional plugins

If 'openimage' isn't set, the interface will use the correspondent setting of JoomGallery's configuration manager ('Entering Detail View' in tab 'Category View' -> 'General Settings').

Further options are 'group', 'limit' or 'type', for example.


Module positions

For the module positions of the gallery, there is a separate article in the documentation which you can find here: Module positions.

You may also add your own module positions at any point inside the gallery with the help of template overrides by using the following code:

<?php $this->loadModules('positionname'); ?>

With this, the new module positions can be used with suffixes right like the already integrated ones. Please note, that you have to specify the prefix 'jg_' in module manager also with this positions ('jg_positionname'), but please omit it in the function call.


Plugin events

Developers among you know that there are different plugin types in Joomla, e.g. content plugins, user plugins or system plugins.

Of course, you may write JoomGallery extensions for this types which use the interface class, for example, like the content plugin 'JoomPlu'.

In this section of the API documentation, however, we want to concentrate on plugin events which are triggered solely by JoomGallery and its extensions. For this, JoomGallery accesses an additional plugin type which is called 'joomgallery'.

So if you want to create a plugin which is able to influence the gallery, the 'install' element of the correspondant XML install file should look like this:

<install version="1.5" type="plugin" group="joomgallery" method="upgrade">

For the general constitution of a plugin, please have a look at one or more of the example plugins which are delivered with Joomla.

In the following, there is a list with all plugin events currently built-in JoomGallery:

onJoomBeforeComment

Description:

  • This event is triggered before storing a passed comment (providing that JoomGallery's own comment system is used).

Parameter:

  • Object which holds the data of the sent comment (this object can be changed because a reference is passed):
    $comment->cmtpic    => 'ID of image which is commented'
    $comment->cmtip => 'IP of visitor who wrote the comment'
    $comment->userid => 'ID of logged-in user (0 if guest)'
    $comment->cmtname => 'Name of the visitor (only if guest and if configured)'
    $comment->cmttext => 'Text of the comment'
    $comment->cmtdate => 'Current point in time'
    $comment->published => '1 if the comment is published, 0 otherwise'
    $comment->approved => '0 if the comment has to be approved, 1 otherwise'

Return value:

  • By returning boolean false storing the comment is prevented. Otherwise please return true.

onJoomAfterComment

Description:

  • This event is triggered after storing a passed comment (providing that JoomGallery's own comment system is used).

Parameter:

  • Object which holds the data of the stored comment:
    $comment->cmtpic    => 'ID of image which is commented'
    $comment->cmtip => 'IP of visitor who wrote the comment'
    $comment->userid => 'ID of logged-in user (0 if guest)'
    $comment->cmtname => 'Name of the visitor (only if guest and if configured)'
    $comment->cmttext => 'Text of the comment'
    $comment->cmtdate => 'Current point in time'
    $comment->published => '1 if the comment is published, 0 otherwise'
    $comment->approved => '0 if the comment has to be approved, 1 otherwise'

onJoomBeforeUpload

Description:

  • This event is triggered shortly before an image is uploaded from the frontend.

Parameter:

  • keine

Return value:

  • By returning boolean false uploading the image is prevented. Otherwise please return true.

onJoomAfterUpload

Description:

  • This event is triggered after an image was uploaded from the frontend and after successfully storing its data.

Parameter:

  • Object which holds the data of the new image:
    $image->id          => 'ID of the image'
    $image->imgtitle => 'Title of the image'
    $image->imgtext => 'Description of the image'
    $image->owner => 'ID of the logged-in user (the uploader)'
    $image->cmtdate => 'Current point in time'
    $image->published => '1 if the image is published, 0 otherwise'
    $image->approved => '0 if the image has to be approved, 1 otherwise'
    $image->imgfilename => 'New file name of the image'
    $image->ordering => 'Ordering number of the image'

onJoomBeforeVote

Description:

  • This event is triggered before storing a rating.

Parameter:

  • Object which holds the data of the rating:
    $vote->picid     => 'ID of the image which is rated'
    $vote->userid => 'ID of the logged-in user (0 if guest)'
    $vote->userip => 'IP of the visitor who rated the image'
    $vote->datevoted => 'Current point in time'
    $vote->vote => 'Number of the rating'
    [The content of this object will probably change soon].
  • Number of the rating [This parameter will probably be removed soon]

Return value:

  • By returning boolean false storing the rating is prevented. Otherwise please return true.

onJoomAfterVote

Description:

  • This event is triggered after storing a rating.

Parameter:

  • Object which holds the data of the rating:
    $interface->getPageHeader();
    0 [The content of this object will probably change soon].
  • Number of the rating [This parameter will probably be removed soon]

onJoomBeforeSendMessage

Description:

  • This event is triggered before a message is sent by the gallery (no e-mail).

Parameter:

  • Array which holds the data of the message to be sent:
    $interface->getPageHeader();
    1

Return value:

  • By returning boolean false storing the rating is prevented. This way, a third party extension may be used for sending the message. Otherwise please return true.

onJoomAfterAddFavourite

Description:

  • This event is triggered after a user added an image to his favourites.

Parameter:

  • ID of the added image.

onJoomAfterRemoveFavourite

Description:

  • This event is triggered after a user removed an image from his favourites.

Parameter:

  • ID of the removed image.

onJoomAfterClearFavourites

Description:

  • This event is triggered after a user has cleared the list of his favourites.

Parameter:

  • none

onJoomAfterDisplayThumb

Description:

  • This event is triggered by the view. The return value (should be a string) will be displayed near to a thumbnail inside 'ul' tags.

Parameter:

  • ID of the image the thumbnail belongs to.

Return value:

  • A string which will be displayed near to a thumbnail inside 'ul' tags.

onJoomAfterDisplayCatThumb

Description:

  • This event is triggered by the view. The return value (should be a string) will be displayed near to the thumbnail of a sub-category inside 'ul' tags.

Parameter:

  • ID of the category the thumbnail belongs to.

Return value:

  • A string which will be displayed near to a thumbnail inside 'ul' tags.

onJoomAfterSend2Friend

Description:

  • This event will be triggered after sending an e-mail via the send2friend form of the detail view.

Parameter:

  • Array which holds the data of the send e-mail:
    $interface->getPageHeader();
    2

onJoomAfterTag

Description:

  • This event is triggered after storing a name tag on an image.

Parameter:

  • Object which holds the data of the stored name tag:
    $interface->getPageHeader();
    3

onJoomDisplayIcons

Description:

  • This event is triggered by the view. The return value (should be a string) will be displayed near to the thumbnail and in the detail view of an image in the area of the icons.

Parameter:

  • ID of the image the thumbnail or the detail view belongs to.

Return value:

  • A string which will be displayed near to the thumbnail and in the detail view of an image in the area of the icons (for example like the star of the favourites or the disc for downloading an image).

onJoomDisplayUser

Description:

  • This event is triggered whenever a user name is displayed in the gallery. This way, it is possible to link a user name with its profile of another component by using a plugin.

Parameter:

  • ID of the user.
  • Boolean true, if according to the settings in the gallery the real names of the users should be displayed instead of the user names.
  • Context in which the user name is displayed, e.g. 'comment or 'nametag'.

Return value:

  • A string which will be displayed instead of the user name. This can be a linked user name, for example.

onJoomGetCaptcha

Description:

  • This event is displayed if a Captcha for spam protection can be used for an action in the gallery (at the moment only for commenting). A string should be returned which displays the Captcha.
  • The event will most probably be removed starting with JoomGallery 4.0 because the Captcha plugins of Joomla! will be used then.

Parameter:

  • none

Return value:

  • A string which displays the Catpcha that shall be used for spam protection.

onJoomCheckCaptcha

Description:

  • This event is triggered if a Captcha can be used for verifying in gallery that a user is human (at the moment only for commenting). For this, the plugins using this event should return an array which holds the result of the verification (in contrast to the event 'onJoomGetCaptcha' which is used for displaying the Captchas).
  • The event will most probably be removed starting with JoomGallery 4.0 because the Captcha plugins of Joomla! will be used then.

Parameter:

  • none

Return value:

  • An array with the key 'valid' which holds either boolean true or boolean false. If 'valid' is false the key 'error' may optionally hold an error message which will be displayed then.

onJoomGetLastComments

Description:

  • This event is triggered if the gallery asks for a certain number of last added comments. With this, third party extensions may include thier comments into the toplist of JoomGallery.

Parameter:

  • An array of objects which should be filled.
  • The number of comments that should be returned.

onJoomGetSmileys

Description:

  • This event is triggered if the gallery asks for all available smileys. The passed array may be extended or reduced arbitrarily.

Parameter:

  • An array which holds the already collected smileys.

onJoomOpenImage

Description:

  • This event is triggered whenever an image should be opened and if it is configured in gallery that plugins should handle the opening of images.

Parameter:

  • A string in which the plugin should write the new link to the image.
  • An object which holds the data of the image.
  • A string which holds the URL to the image which should be opened.
  • A string which holds the group name the image should be added to.
  • A string which holds the image type which should be opened ('thumb', 'img' or 'orig').

onJoomSearch

Description:

  • This event is triggered if something is searched in the gallery [not yet fully functional].

Parameter:

  • The string which was entered for searching.

Return value:

  • An array which holds further parameters for searching.

Joomla!®

Joom::Gallery is not affiliated with or endorsed by the Joomla! Project or Open Source Matters. The Joomla! name and logo is used under a limited license granted by Open Source Matters the trademark holder in the United States and other countries.