API

Article Index

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:
    $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]

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:
    $message['from']      => 'E-mail address of the sender'
    $message['fromname'] => 'Name of the sender'
    $message['recipient'] => 'ID of the recipient'
    $message['subject'] => 'Subject of the message'
    $message['body'] => 'Text of the message'
    $message['mode'] => 'The mode used by the messenger'

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:
    $message['from']      => 'E-mail address of the sender'
    $message['fromname'] => 'Name of the sender'
    $message['recipient'] => 'E-mail address of the recipient'
    $message['subject'] => 'Subject of the message'
    $message['body'] => 'Text of the message'
    $message['mode'] => 'The mode used by the messenger'

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:
    $tag->npicid  => 'ID of the image the name tag was added to'
    $tag->nuserid => 'ID of the user for whom the name tag was added'
    $tag->by => 'ID of the user who created the name tag'
    $tag->nuserip => ' IP of the visitor who created the name tag'
    $tag->ndate => 'Current point in time'
    $tag->nxvalue => 'X-coordinate of the name tag's position'
    $tag->nyvalue => 'Y-coordinate of the name tag's position'
    $tag->nzindex => 'Z-index of the name tag (for overlapping)'

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.