Difference between revisions of "Gallery3:Developer Handbook:Event Hooks" - Gallery Codex
Personal tools

Difference between revisions of "Gallery3:Developer Handbook:Event Hooks"

From Gallery Codex

m (item_moved)
(Other Events)
 
(22 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<div style="float:right;">__TOC__</div>
 
<div style="float:right;">__TOC__</div>
  
 +
<span style="color:#0000c0">'' '''Disclaimer:''' I am not one of the Gallery 3 developers.  I have written a couple of modules and have made one of them ([[Gallery3:Modules:emboss|emboss]]) available as a 3rd party Gallery 3 contribution.  The following is simply what I have been able to weasel out of the code by reading through it.  If you find anything that is incorrect, PLEASE feel free to either make the corrections yourself or [mailto:mikemayer67@vmwishes.com contact me] and I will make the changes.''</span>
  
The following is ''currently'' a work in progress.  <span style="color:#808080">(I will remove this statement when I think I'm done).</span>
+
The [[Gallery3:Developer_Handbook:Gallery3_Modules|Gallery3 Modules]] page provides a list of all nearly all of the event hooks defined by Gallery 3, but does not provide any details about what triggers these hooks or the arguments provided to the hooks.  The following is an attempt to tackle this omission.  I have attempted to group the events in a somewhat logical order... but they don't necessarily fit cleanly into any categorization.  If you have a suggestion for a better way of laying them out, please feel free to let me know.
 
+
<span style="color:#0000c0">'' '''Disclaimer:''' I am not one of the Gallery 3 developers.  I have written a couple of modules and have made one of them ([[Gallery3:Modules:emboss|emboss]]) available as a 3rd party Gallery 3 contribution.  The following is simply what I have been able to weasel out of the code by reading through it.  If you find anything that is incorrect, PLEASE feel free to either make the corrections yourself or contact me and I will make the changes.''</span>
+
 
+
The [[Gallery3:Developer_Handbook:Gallery3_Modules|Gallery3 Modules]] page provides a list of all (''most?'') of the event hooks defined by Gallery 3, but does not provide any details about what triggers these hooks or the arguments provided to the hooks.  The following is an attempt to tackle this omission.  I have provided them in alphabetical order.  If someone wants to try to regroup them in a logical way, knock yourself out!.
+
  
 
Each of the following hook description follows a similar (exact?) pattern, showing when the hook is triggered, what arguments are sent to the handler function, an example stack trace (or two), and a list of the modules that I could find that currently implement a handler for the hook.
 
Each of the following hook description follows a similar (exact?) pattern, showing when the hook is triggered, what arguments are sent to the handler function, an example stack trace (or two), and a list of the modules that I could find that currently implement a handler for the hook.
Line 166: Line 163:
  
 
=Form Population Events=
 
=Form Population Events=
 +
Most of the events in this section follow a common pattern.  In particular, they come in pairs: one event (''xxx_form'') is sent while the form is being constructed ('''''after''' all of the nominal fields have been added''), and the other (''xxx_form_completed'') is sent after the nominal action driven by the form has '''completed'''.  Note that the completed event is only sent if the form has been successfully validated.
  
 
==add_photos_form==
 
==add_photos_form==
 
* '''When triggered'''
 
* '''When triggered'''
 
::User (with administrative privileges) selects "Add photos" from the "Add" menu.
 
::User (with administrative privileges) selects "Add photos" from the "Add" menu.
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$album
 
::$album
Line 185: Line 182:
 
==add_photos_form_completed==
 
==add_photos_form_completed==
 
* '''When triggered'''
 
* '''When triggered'''
::After a photo has been successfully loaded in response to a user (with administrative privileges) selecting "Add photos" from the "Add" menu; called after the uploader form has been validated and the photo saved.
+
::After a photo has been successfully loaded in response to a user (with administrative privileges) selecting "Add photos" from the "Add" menu.
 
* '''Arguments'''
 
* '''Arguments'''
 
::$item
 
::$item
Line 200: Line 197:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User (with administrative privileges) selects "Add an album" from the "add" menu
 
::User (with administrative privileges) selects "Add an album" from the "add" menu
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$parent
 
::$parent
Line 234: Line 230:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User initiates a new comment by clicking on the "Add a Comment" button
 
::User initiates a new comment by clicking on the "Add a Comment" button
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added, and '''before''' captcha_protect_form event is sent)
+
:::''This event does not have the paired comment_add_form_completed event''
 +
:::''This event will be immediately followed with a captcha_protect_form event
 
* '''Arguments'''
 
* '''Arguments'''
 
::$form
 
::$form
Line 248: Line 245:
 
* '''When triggered'''
 
* '''When triggered'''
 
:*During construction of an "add comment" form in response to a user hitting the "Add a comment" button, prior to displaying the form.
 
:*During construction of an "add comment" form in response to a user hitting the "Add a comment" button, prior to displaying the form.
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added '''and''' comment_add_form event has been sent)
 
 
:*During construction of a "contact" form in response to a user attempting to contact another user via their profile.
 
:*During construction of a "contact" form in response to a user attempting to contact another user via their profile.
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added '''and''' user_profile_contact_form event has been sent)
+
:::''This event does not have the paired captha_protect_form_completed event
 +
:::''This event will be sent immediately following the associated add_comment_form or user_profile_contact_form event''
 
* '''Arguments'''
 
* '''Arguments'''
 
::$form
 
::$form
Line 268: Line 265:
 
:*User (with administrative privileges) selects "Edit photo" from the "Photo options" menu or a photo context menu.
 
:*User (with administrative privileges) selects "Edit photo" from the "Photo options" menu or a photo context menu.
 
:*User (with administrative privileges) selects "Edit movie" from the "Movie options" menu or a movie context menu.
 
:*User (with administrative privileges) selects "Edit movie" from the "Movie options" menu or a movie context menu.
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$item
 
::$item
Line 318: Line 314:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User (with administrative privileges) selects "Theme options" from the "Admin/Appearance" menu
 
::User (with administrative privileges) selects "Theme options" from the "Admin/Appearance" menu
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$form
 
::$form
Line 344: Line 339:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User (with administrative privileges) selects "Add a new User" from the "Admin/Users & Groups" page
 
::User (with administrative privileges) selects "Add a new User" from the "Admin/Users & Groups" page
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$user
 
::$user
Line 375: Line 369:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User selects the "Change email" button on their user profile page (''accessed by clicking on their login name'').   
 
::User selects the "Change email" button on their user profile page (''accessed by clicking on their login name'').   
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$user
 
::$user
Line 407: Line 400:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User selects the "Change password" button on their user profile page (''accessed by clicking on their login name'').   
 
::User selects the "Change password" button on their user profile page (''accessed by clicking on their login name'').   
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$user
 
::$user
Line 439: Line 431:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User selects the "Edit" button on their user profile page (''accessed by clicking on their login name'').   
 
::User selects the "Edit" button on their user profile page (''accessed by clicking on their login name'').   
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$user
 
::$user
Line 470: Line 461:
 
* '''When triggered'''
 
* '''When triggered'''
 
::User (with administrative privileges) begins editting user info on the "Admin/Users & Groups" page
 
::User (with administrative privileges) begins editting user info on the "Admin/Users & Groups" page
:::This hook is invoked while the edit form is being created ('''after''' all the nominal fields have been added)
 
 
* '''Arguments'''
 
* '''Arguments'''
 
::$user
 
::$user
Line 500: Line 490:
 
* '''When triggered'''
 
* '''When triggered'''
 
::During construction of a "contact" form in response to a user attempting to contact another user via their profile.
 
::During construction of a "contact" form in response to a user attempting to contact another user via their profile.
:::This hook is invoked while the form is being created ('''after''' all the nominal fields have been added and '''before''' the captcha_protect_form event has been sent)
+
:::''This event does not have the paired user_profile_contact_form_completed event''
 +
:::''This event will be immediately followed with a captcha_protect_form event
 
* '''Arguments'''
 
* '''Arguments'''
 
::$form
 
::$form
Line 511: Line 502:
 
::''none''
 
::''none''
  
=Content Update Events=
+
=Content Modification Events=
 
==comment_created==
 
==comment_created==
 
* '''When triggered'''
 
* '''When triggered'''
Line 912: Line 903:
 
* '''Implementing Modules'''
 
* '''Implementing Modules'''
 
::gallery
 
::gallery
 +
 +
==show_user_profile==
 +
* '''When triggered'''
 +
::User profile page is being populated
 +
* '''Arguments'''
 +
::$event_data
 +
:::''stdClass with named arguments { user=>$user, content=>array() }''
 +
* '''Stack trace'''
 +
::http://(site)/gallery3/user_profiles/show/$id
 +
::└─User_Profile_Controller::show($id)
 +
:::└─module::event("show_user_profile",$event_data)
 +
* '''Implementing Modules'''
 +
::comment
 +
::gallery
 +
::notification
 +
::rest
  
 
=User Login/Authorization Events=
 
=User Login/Authorization Events=
Line 1,115: Line 1,122:
 
::slideshow
 
::slideshow
  
=XXX=
+
=Other Events=
 +
 
 +
The events in this section are those that I couldn't get my head around.  I found them in the code, but cold not really figure out what user action triggers them.
 +
I would love for someone who does understand these to either fill in the details (and possibly categorize them appropriately) or [mailto:mikemayer67@vmwishes.com contact me] with the info so that I can make the updates.
 +
 
 +
==before_combine==
 +
* '''When triggered'''
 +
::Called from within Gallery_View_Core::get_combined '''before''' the data in the combine_queue has been processed into a single content item.
 +
* '''Arguments'''
 +
::$combine_data
 +
:::''stdClass object''
 +
::::└─''contents = view's combine_queue[$type][$group] attribute''
 +
* '''Stack trace'''
 +
::(theme view (admin|page).html.php)
 +
::└─Gallery_View_Core::get_combined($type,$group="core")
 +
:::└─after_combine($combine_data)
 +
* '''Implementing Modules'''
 +
::''none''
  
 
==after_combine==
 
==after_combine==
Line 1,144: Line 1,168:
 
::notification
 
::notification
 
::tag
 
::tag
 
==before_combine==
 
* '''When triggered'''
 
::Called from within Gallery_View_Core::get_combined '''before''' the data in the combine_queue has been processed into a single content item.
 
* '''Arguments'''
 
::$combine_data
 
:::''stdClass object''
 
::::└─''contents = view's combine_queue[$type][$group] attribute''
 
* '''Stack trace'''
 
::(theme view (admin|page).html.php)
 
::└─Gallery_View_Core::get_combined($type,$group="core")
 
:::└─after_combine($combine_data)
 
* '''Implementing Modules'''
 
::''none''
 
  
 
==identity_provider_changed==
 
==identity_provider_changed==
Line 1,164: Line 1,174:
 
* '''Arguments'''
 
* '''Arguments'''
 
::$current_provider
 
::$current_provider
:::''IdentityProvider_Core - value of the identify_provider setting for gallery prior to changing the provider''
+
:::''IdentityProvider - value of the identify_provider setting for gallery prior to changing the provider''
 
::$new_provider
 
::$new_provider
:::''IdentityProvider_Core - value of the identify_provider setting for gallery after changing the provider''
+
:::''IdentityProvider - value of the identify_provider setting for gallery after changing the provider''
 
* '''Stack trace'''
 
* '''Stack trace'''
 
::IdentityProvider_Core::change_provider($new_provider)
 
::IdentityProvider_Core::change_provider($new_provider)
Line 1,192: Line 1,202:
  
  
==show_user_profile==
 
* '''When triggered'''
 
::User profile page is being populated
 
* '''Arguments'''
 
::$event_data
 
:::''stdClass with named arguments { user=>$user, content=>array() }''
 
* '''Stack trace'''
 
::http://(site)/gallery3/user_profiles/show/$id
 
::└─User_Profile_Controller::show($id)
 
:::└─module::event("show_user_profile",$event_data)
 
* '''Implementing Modules'''
 
::comment
 
::gallery
 
::notification
 
::rest
 
  
  
 
[[Category:Gallery 3:Developer Handbook|Event Hooks]]
 
[[Category:Gallery 3:Developer Handbook|Event Hooks]]

Latest revision as of 10:01, 30 October 2012

Contents

Disclaimer: I am not one of the Gallery 3 developers. I have written a couple of modules and have made one of them (emboss) available as a 3rd party Gallery 3 contribution. The following is simply what I have been able to weasel out of the code by reading through it. If you find anything that is incorrect, PLEASE feel free to either make the corrections yourself or contact me and I will make the changes.

The Gallery3 Modules page provides a list of all nearly all of the event hooks defined by Gallery 3, but does not provide any details about what triggers these hooks or the arguments provided to the hooks. The following is an attempt to tackle this omission. I have attempted to group the events in a somewhat logical order... but they don't necessarily fit cleanly into any categorization. If you have a suggestion for a better way of laying them out, please feel free to let me know.

Each of the following hook description follows a similar (exact?) pattern, showing when the hook is triggered, what arguments are sent to the handler function, an example stack trace (or two), and a list of the modules that I could find that currently implement a handler for the hook. Note that the stack traces are not necessarily the only scenarios; they are simply those that I could find by walking backward through the code. Note too that the location of the handler is well-defined for any given module (i.e. module/example/helpers/example_events.php) and thus are not spelled out for each hook.

Finally, I am not as comfortable with writing themes as I am with writing modules (not that I'm terribly proficient there either). I suspect the stack trace often begins within a theme implementation. When I could figure this out, I identified it. When I could not, I began the stack trace up as far as I could crawl backward through the php code.

Menu Population Events

admin_menu

  • When triggered
During population of the content of the Admin menu
  • Arguments
$menu
Menu object representing the admin menu
$theme
Theme_View object
  • Stack trace
(site_menu event hook)
└─gallery_event_Core::site_menu($menu,$theme,$item_css_selector)
└─module::event("admin_menu",$admin_menu,$theme)
or
Admin_View_Core::admin_menu()
└─module::event("admin_menu",$menu,$this)
  • Implementing Modules
akismet
comment
digibug
fancybox
g2_import
gallery
recaptcha
server_add
tag
thumbnav
user
watermark

album_menu

  • When triggered
During population of the content of the "Album options" menu
  • Arguments
$menu
Menu object representing the album menu
$theme
Theme_View object'
  • Stack trace
(theme view (sidebar).html.php)
└─Album_View_Core::album_menu()
└─module::event("album_menu",$menu,$this)
  • Implementing Modules
slideshow

context_menu

  • When triggered
During population of the content of the context menu
  • Arguments
$menu
Menu object representing the context menu
$theme
Theme_View object
$item
Item object representing the object to which the context menu applies
$css_selector
The css selector associated with the thumb style (nominally .g-thumbnail)
  • Stack trace
(theme view (album).html.php
└─Theme_View_Core::context_menu($item, $thumbnail_css_selector)
└─module::event("context_menu", $menu, $this, $item, $thumbnail_css_selector)
  • Implementing Modules
digibug
gallery
organize

movie_menu

  • When triggered
During population of the content of the "movie options" menu
  • Arguments
$menu
Menu object representing the movie menu
$theme
Theme_View object'
  • Stack trace
(theme view (sidebar).html.php)
└─movie_View_Core::movie_menu()
└─module::event("movie_menu",$menu,$this)
  • Implementing Modules
none

photo_menu

  • When triggered
During population of the content of the "photo options" menu
  • Arguments
$menu
Menu object representing the photo menu
$theme
Theme_View object'
  • Stack trace
(theme view (sidebar).html.php)
└─photo_View_Core::photo_menu()
└─module::event("photo_menu",$menu,$this)
  • Implementing Modules
comment
slideshow

site_menu

  • When triggered
During population of the content of the site menu
  • Arguments
$menu
Menu object representing the site menu
$theme
Theme_View object
$css_selector
The css selector associated with the menu
  • Stack trace
(theme view ( ).html.php)
└─Theme_View_Core::album_menu()
└─module::event("site_menu",$menu,$this)
  • Implementing Modules
digibug
gallery
keeporiginal
notification
organize
server_add

tag_menu

  • When triggered
During population of the content of a tag menu
  • Arguments
$menu
Menu object representing the tag menu
$theme
Theme_View object
$css_selector
The css selector associated with the menu
  • Stack trace
(theme view ( ).html.php)
└─Theme_View_Core::tag_menu()
└─module::event("tag_menu",$menu,$this)
  • Implementing Modules
slideshow

user_menu

  • When triggered
During population of the content of the user menu
  • Arguments
$menu
Menu object representing the user menu
$theme
Theme_View object
  • Stack trace
(theme view (page|admin).html.php)
└─Theme_View_Core::user_menu()
└─module::event("user_menu",$menu,$this)
  • Implementing Modules
gallery

Form Population Events

Most of the events in this section follow a common pattern. In particular, they come in pairs: one event (xxx_form) is sent while the form is being constructed (after all of the nominal fields have been added), and the other (xxx_form_completed) is sent after the nominal action driven by the form has completed. Note that the completed event is only sent if the form has been successfully validated.

add_photos_form

  • When triggered
User (with administrative privileges) selects "Add photos" from the "Add" menu.
  • Arguments
$album
Item_Model object populated with information about the album into which the photo will be added
$form
Forge object populated with the uploadify.html and uploadify_buttons.html views
  • Stack trace
Uploader_Controller::add_photos($id)
└─Uploader_Controller::_get_add_form($album)
└─module::event("add_photos_form",$album,$form)
  • Implementing Modules
tag

add_photos_form_completed

  • When triggered
After a photo has been successfully loaded in response to a user (with administrative privileges) selecting "Add photos" from the "Add" menu.
  • Arguments
$item
Item_Model object populated with information about the photo which was just added
$form
Forge object populated with the uploadify.html and uploadify_buttons.html views
  • Stack trace
Uploader_Controller::add_photos($id)
└─module::event("add_photos_form_completed",$item,$form)
  • Implementing Modules
tag

album_add_form

  • When triggered
User (with administrative privileges) selects "Add an album" from the "add" menu
  • Arguments
$parent
Item_Model object populated with information about the album into which the new album will be added
$form
Forge object populated within album_Core::get_add_form
  • Stack trace
Albums_Controller::create($parent_id)
└─album_Core::get_add_form($album)
└─module::event("album_add_form",$parent,$form)
or
Albums_Controller::form_add($album_id)
└─album_Core::get_add_form($album)
└─module::event("album_add_form",$parent,$form)
  • Implementing Modules
none

album_add_form_completed

  • When triggered
After a new album has been successfully created in response to a user (with administrative privileges) selecting "Add an album" from the "add" menu.
  • Arguments
$album
Item_Model object populated with information about the album which was just added
$form
Forge object populated within album_Core::get_add_form
  • Stack trace
Albums_Controller::create($parent_id)
└─module::event("album_add_form_completed",$album,$form)
  • Implementing Modules
none

comment_add_form

  • When triggered
User initiates a new comment by clicking on the "Add a Comment" button
This event does not have the paired comment_add_form_completed event
This event will be immediately followed with a captcha_protect_form event
  • Arguments
$form
Forge object populated within comment_Core::get_add_form
  • Stack trace
Comments_Controller::create($id)
└─comment_Core::get_add_form($album)
└─module::event("comment_add_form",$form)
  • Implementing Modules
none

captcha_protect_form

  • When triggered
  • During construction of an "add comment" form in response to a user hitting the "Add a comment" button, prior to displaying the form.
  • During construction of a "contact" form in response to a user attempting to contact another user via their profile.
This event does not have the paired captha_protect_form_completed event
This event will be sent immediately following the associated add_comment_form or user_profile_contact_form event
  • Arguments
$form
Forge instance being constructed
  • Stack trace
user_profile_Core::get_contact_form($user)
└─module::event("captcha_protect_form",$form)
or
comment_Core::get_add_form($item)
└─module::event("captcha_protect_form",$form)
  • Implementing Modules
recaptcha

item_edit_form

  • When triggered
  • User (with administrative privileges) selects "Edit album" from the "Album options" menu or a album context menu.
  • User (with administrative privileges) selects "Edit photo" from the "Photo options" menu or a photo context menu.
  • User (with administrative privileges) selects "Edit movie" from the "Movie options" menu or a movie context menu.
  • Arguments
$item
Item_Model object representing the album, photo, or movie item to be modified.
$form
Forge object populated within album_Core::get_edit_form or
Forge object populated within photo_Core::get_edit_form or
Forge object populated within movie_Core::get_edit_form
  • Stack trace
Albums_Controller::update($album_id)
└─album::get_edit_form($album)
└─module::event("item_edit_form",$parent,$form)
or
Photos_Controller::update($album_id)
└─photo::get_edit_form($album)
└─module::event("item_edit_form",$photo,$form)
or
Movies_Controller::update($album_id)
└─movie::get_edit_form($album)
└─module::event("item_edit_form",$movie,$form)
  • Implementing Modules
tag

item_edit_form_completed

  • When triggered
  • After an album has been modified in response to a user (with administrative privileges) selecting "Edit album" from the "Album options" menu or an album context menu.
  • After a photo has been modified in response to a user (with administrative privileges) selecting "Edit photo" from the "Photo options" menu or a photo context menu.
  • After a movie has been modified in response to a user (with administrative privileges) selecting "Edit movie" from the "Movie options" menu or a movie context menu.
  • Arguments
$item
Item_Model object representing the album, photo, or movie which was just modified.
$form
Forge object populated within album_Core::get_edit_form or
Forge object populated within photo_Core::get_edit_form or
Forge object populated within movie_Core::get_edit_form
  • Stack trace
Albums_Controller::update($album_id)
└─module::event("item_edit_form_completed",$parent,$form)
or
Photos_Controller::update($album_id)
└─module::event("item_edit_form_completed",$photo,$form)
or
Movies_Controller::update($album_id)
└─module::event("item_edit_form_completed",$movie,$form)
  • Implementing Modules
tag

theme_edit_form

  • When triggered
User (with administrative privileges) selects "Theme options" from the "Admin/Appearance" menu
  • Arguments
$form
Forge object populated within Admin_Theme_Options_Controller::_get_edit_form_admin
  • Stack trace
Admin_Theme_Options_Controller::save
└─Admin_Theme_Options_Controller::_get_edit_form_admin()
└─module::event("theme_edit_form",$form)
  • Implementing Modules
none

theme_edit_form_completed

  • When triggered
After a theme has been successfully modified.
  • Arguments
$form
Forge object populated within Admin_Theme_Options_Controller::_get_edit_form_admin
  • Stack trace
Admin_Theme_Options_Controller::save
└─module::event("theme_edit_form_completed",$form)
  • Implementing Modules
none

user_add_form_admin

  • When triggered
User (with administrative privileges) selects "Add a new User" from the "Admin/Users & Groups" page
  • Arguments
$user
??? - this variable does not appear to be defined prior to posting the event
$form
Forge object populated within Admin_Users_Controller::_get_user_add_form_admin
  • Stack trace
Admin_Users_Controller::add_user
└─Admin_Users_Controller::_get_user_add_form_admin()
└─module::event("user_add_form_admin",$user,$form)
  • Implementing Modules
none

user_add_form_admin_completed

  • When triggered
After a new user has been added to the database in response to an administrative user selecting "Add a new User" on the "Admin/Users & Groups" page.
  • Arguments
$user
User_Model object defining the new user
$form
Forge object populated within Admin_Users_Controller::_get_user_add_form_admin
  • Stack trace
Admin_Users_Controller::add_user
└─module::event("user_add_form_admin_completed",$user,$form)
  • Implementing Modules
rest

user_change_email_form

Note that this event will be introduced when Pull #74 is introduced into the baseline

  • When triggered
User selects the "Change email" button on their user profile page (accessed by clicking on their login name).
  • Arguments
$user
User_Model object (should represent the active user)
$form
Forge object populated within User_Controller::_get_change_email_form
  • Stack trace
User_Controller::change_email($id)
└─User_Controller::_get_change_email_form($user)
└─module::event("user_change_email_form",$user,$form)
  • Implementing Modules
none

user_change_email_form_completed

  • When triggered
User selects the "Change email" button on their user profile page (accessed by clicking on their login name).
This hook is invoked after the change email form has been submitted.
Note that if the user fails to authenticate, a user_auth_failed event will be sent instead
  • Arguments
$user
User_Mode object
$form
Forge object populated within User_Controller::_get_change_email_form
  • Stack trace
User_Controller::change_email($id)
└─module::event("user_change_email_form_completed",$user,$form)
  • Implementing Modules
none

user_change_password_form

  • When triggered
User selects the "Change password" button on their user profile page (accessed by clicking on their login name).
  • Arguments
$user
User_Model object (should represent the active user)
$form
Forge object populated within User_Controller::_get_change_password_form
  • Stack trace
User_Controller::change_password($id)
└─User_Controller::_get_change_password_form($user)
└─module::event("user_change_password_form",$user,$form)
  • Implementing Modules
none

user_change_password_form_completed

  • When triggered
User selects the "Change password" button on their user profile page (accessed by clicking on their login name).
This hook is invoked after the change password form has been submitted.
Note that if the user fails to authenticate, a user_auth_failed event will be sent instead
  • Arguments
$user
User_Model object
$form
Forge object populated within User_Controller::_get_change_password_form
  • Stack trace
User_Controller::change_password($id)
└─module::event("user_change_password_form_completed",$user,$form)
  • Implementing Modules
none

user_edit_form

  • When triggered
User selects the "Edit" button on their user profile page (accessed by clicking on their login name).
  • Arguments
$user
User_Model object (should represent the active user)
$form
Forge object populated within User_Controller::_get_edit_form
  • Stack trace
User_Controller::update($id)
└─User_Controller::_get_edit_form($user)
└─module::event("user_edit_form",$user,$form)
  • Implementing Modules
none

user_edit_form_completed

  • When triggered
User selects the "Edit" button on their user profile page (accessed by clicking on their login name).
This hook is invoked after the change edit form has been submitted and the changes committed to the data.
  • Arguments
$user
User_Model object
$form
Forge object populated within User_Controller::_get_edit_form
  • Stack trace
User_Controller::update($id)
└─module::event("user_edit_form_completed",$user,$form)
  • Implementing Modules
none

user_edit_form_admin

  • When triggered
User (with administrative privileges) begins editting user info on the "Admin/Users & Groups" page
  • Arguments
$user
User_Model object - obtained via user::lookup($id)
$form
Forge object populated within Admin_Users_Controller::_get_user_edit_form_admin
  • Stack trace
Admin_Users_Controller::edit_user($id)
└─Admin_Users_Controller::_get_user_edit_form_admin($user)
└─module::event("user_edit_form_admin",$user,$form)
  • Implementing Modules
rest

user_edit_form_admin_completed

  • When triggered
User (with administrative privileges) modifies user info on the "Admin/Users & Groups" page... after updating the user in the database.
  • Arguments
$user
User_Model object defining the modified user
$form
Forge object populated within Admin_Users_Controller::_get_user_edit_form_admin
  • Stack trace
Admin_Users_Controller::edit_user($id)
└─module::event("user_edit_form_admin_completed",$user,$form)
  • Implementing Modules
none

user_profile_contact_form

  • When triggered
During construction of a "contact" form in response to a user attempting to contact another user via their profile.
This event does not have the paired user_profile_contact_form_completed event
This event will be immediately followed with a captcha_protect_form event
  • Arguments
$form
Forge object populated within user_profile_Core::get_contact_form
  • Stack trace
User_Profile_Controller::contact($id)
└─user_profile_Core::get_contact_form($user)
└─module::event("user_profile_contact_form",$form)
  • Implementing Modules
none

Content Modification Events

comment_created

  • When triggered
After a new comment has been created by a user and saved to the database.
  • Arguments
$comment
Comment_Model object (subclass of ORM)
  • Stack trace
Comment_Model_Core::save()
└─module::event("comment_created",$this)
  • Implementing Modules
akismet/helpers/akismet_event
notification/helpers/notification_event

comment_updated

  • When triggered
After an existing comment has been modified by a user and saved to the database.
  • Arguments
$original
User_Model (a subclass of ORM). Note that this is a clone of the comment from prior to the save as the "real" user has now been updated in the database
$comment
User_Model (a subclass of ORM). This is the comment after the save.
$comment
Comment_Model object (subclass of ORM)
  • Stack trace
Comment_Model_Core::save()
└─module::event("comment_updated",$this)
  • Implementing Modules
akismet
notification

item_before_create

  • When triggered
Before saving a new item to the database (one that had not currently been in the database).
  • Arguments
$item
Item_Model object to be saved to the database
  • Stack trace
Item_Model_Core::save()
└─module::event("item_before_create",$this)
  • Implementing Modules
none

item_created

  • When triggered
After saving a new item to the database (one that had not currently been in the database).
  • Arguments
$item
Item_Model object to be saved to the database. Note that the data_file attribute will have been set to null to avoid an infinite recursion.'
  • Stack trace
Item_Model_Core::save()
└─module::event("item_created",$this)
  • Implementing Modules
exif
g2_import
gallery
notification
search
tag

item_before_delete

  • When triggered
Before deleting an item from the database.
  • Arguments
$item
Item_Model object to be deleted from the database
  • Stack trace
Item_Model::delete()
└─module::event("item_before_delete",$this)
  • Implementing Modules
keeporiginal

item_deleted

  • When triggered
After deleting an item frim the database.
  • Arguments
$old
Item_Model object representing the object that was deleted.
  • Stack trace
Item_Model_Core::delete()
└─module::event("item_deleted",$old)
  • Implementing Modules
comment
exif
g2_import
gallery
notification
search
tag

item_index_data

  • When triggered
An album, photo, or movie item is created or updated. More specifically, when the search module event handler catches a item_created, item_updated, or item_related_update event.
  • Arguments
$item
Item_Model object that was passed as an argument to one of the event handlers listed above.
$data
An empty ArrayObject. The event handler should add something to this array
  • Stack trace
search_event_Core::item_created($item)
└─search_Core::update($item)
└─module::event("item_index_data",$item,$data)
or
search_event_Core::item_updated($original,$new)
└─search_Core::update($new)
└─module::event("item_index_data",$item,$data)
or
search_event_Core::item_related_update($item)
└─search_Core::update($item)
└─module::event("item_index_data",$item,$data)
  • Implementing Modules
comment
gallery
tag

item_moved

  • When triggered
While saving an existing item to the database (one that had not currently been in the database) that has been relocated to a new album since the last save to the database; called after item_begin_update and before item_updated.
  • Arguments
$item
Item_Model object to be saved to the database. Note that the data_file attribute will have been set to null to avoid an infinite recursion.
$old_parent
Item_Model object containing the information about the album in which the item used to be located.
  • Stack trace
Item_Model_Core::save()
└─module::event("item_moved",$this,$original->parent())
  • Implementing Modules
gallery
keeporiginal

item_related_update

  • When triggered
  • The tag module item_edit_form_completed event handler is invoked; called after any new tags have been added to the item to which the event applies, but before the tags are compacted.
  • A new tag is added to the database
  • An existing tag is deleted from the database
  • Arguments
$item
Item_Model object for which the tags were modified
  • Stack trace
tag_Core::item_edit_form_completed($item,$form)
└─module::event("item_related_update",$item)
  • Implementing Modules
search

item_before_update

  • When triggered
Before saving an existing item to the database (with changes).
  • Arguments
$item
Item_Model object to be saved to the database
  • Stack trace
Item_Model_Core::save()
└─module::event("item_before_update",$this)
  • Implementing Modules
none

item_updated

  • When triggered
After saving an existing item to the database (with changes).
  • Arguments
$original
Item_Model object representing the state of the object prior to the current update.
$item
Item_Model object to be saved to the database.
  • Stack trace
Item_Model_Core::save()
└─module::event("item_updated",$original,$this)
  • Implementing Modules
exif
gallery
keeporiginal
notification
search

item_updated_data_file

  • When triggered
After saving an existing item to the database (with changes) where the data_file attribute is not set to a null value; called after item_updated.
  • Arguments
$item
Item_Model object to be saved to the database. Note that the data_file attribute will have been set to null to avoid an infinite recursion
  • Stack trace
Item_Model_Core::save()
└─module::event("item_updated_data_file",$this)
  • Implementing Modules
none

Graphics Processing Events

graphics_composite

  • When triggered
Immediately prior to using the graphics package to overlay one image onto another.
  • Arguments
$input_file
"Source" image file which serves as the base for the composited image
$output_file
"Destination" image file where the final composited image will be saved
$options
Array of options passed to the graphics package composite method
$item
Item_Model object containing information about the item being modified by the graphics package. Note that this info is not used by the graphics package. It is simply provided for use by the composite event hooks.
  • Stack trace
gallery_graphics_Core::composite
└─module::event("graphics_composite",$input_file,$output_file,$options,$item)
  • Implementing Modules
none

graphics_composite_completed

  • When triggered
Immediately after using the graphics package to overlay one image onto another.
  • Arguments
$input_file
"Source" image file which serves as the base for the composited image
$output_file
"Destination" image file where the final composited image will be saved
$options
Array of options passed to the graphics package composite method
$item
Item_Model object containing information about the item being modified by the graphics package. Note that this info is not used by the graphics package. It is simply provided for use by the composite event hooks.
  • Stack trace
gallery_graphics_Core::composite
└─module::event("graphics_composite",$input_file,$output_file,$options,$item)
  • Implementing Modules
none

graphics_resize

  • When triggered
Immediately prior to using the graphics package to resize an image.
  • Arguments
$input_file
"Source" image file which is to be resized
$output_file
"Destination" image file where the resized image will be saved
$options
Array of options passed to the graphics package resize method
$item
Item_Model object containing information about the item being resized by the graphics package. Note that this info is not used by the graphics package. It is simply provided for use by the composite event hooks.
  • Stack trace
gallery_graphics_Core::resize
└─module::event("graphics_resize",$input_file,$output_file,$options,$item)
  • Implementing Modules
none

graphics_resize_completed

  • When triggered
Immediately after using the graphics package to resize an image.
  • Arguments
$input_file
"Source" image file which is to be resized
$output_file
"Destination" image file where the resized image will be saved
$options
Array of options passed to the graphics package resize method
$item
Item_Model object containing information about the item being resized by the graphics package. Note that this info is not used by the graphics package. It is simply provided for use by the composite event hooks.
  • Stack trace
gallery_graphics_Core::resize
└─module::event("graphics_resize",$input_file,$output_file,$options,$item)
  • Implementing Modules
none

graphics_rotate

  • When triggered
Immediately prior to using the graphics package to rotate an image.
  • Arguments
$input_file
"Source" image file which is to be rotated
$output_file
"Destination" image file where the rotated image will be saved
$options
Array of options passed to the graphics package rotate method
$item
Item_Model object containing information about the item being rotated by the graphics package. Note that this info is not used by the graphics package. It is simply provided for use by the composite event hooks.
  • Stack trace
gallery_graphics_Core::rotate
└─module::event("graphics_rotate",$input_file,$output_file,$options,$item)
  • Implementing Modules
keeporiginal

graphics_rotate_completed

  • When triggered
Immediately after using the graphics package to rotate an image.
  • Arguments
$input_file
"Source" image file which is to be rotated
$output_file
"Destination" image file where the rotated image will be saved
$options
Array of options passed to the graphics package rotate method
$item
Item_Model object containing information about the item being rotated by the graphics package. Note that this info is not used by the graphics package. It is simply provided for use by the composite event hooks.
  • Stack trace
gallery_graphics_Core::rotate
└─module::event("graphics_rotate",$input_file,$output_file,$options,$item)
  • Implementing Modules
keeporiginal

User/Group Modification Events

group_created

  • When triggered
User (with administrative privileges) creates a new group on the Users/Groups page... after adding the group to the database.
  • Arguments
$group
Group_Model (a subclass of ORM)
  • Stack trace
Group_Model_Core::save()
└─module::event("group_created",$this)
  • Implementing Modules
gallery

group_before_delete

  • When triggered
User (with administrative privileges) deletes a group on the Users/Groups page... prior to actually performing the deletion.
  • Arguments
$group
Group_Model (a subclass of ORM)
  • Stack trace
Group_Model_Core::delete($id=null)
└─module::event("group_before_delete",$this)
  • Implementing Modules
none

group_deleted

  • When triggered
User (with administrative privileges) deletes a group on the Users/Groups page... after performing the deletion.
  • Arguments
$group
Group_Model (a subclass of ORM). Note that this is a clone of the actual group as the "real" group has now been deleted from the database
  • Stack trace
Group_Model_Core::delete($id=null)
└─module::event("group_deleted",$old)
  • Implementing Modules
none

group_updated

  • When triggered
User (with administrative privileges) modifies an existing group on the Users/Groups page... after updating the group in the database.
  • Arguments
$original
Group_Model (a subclass of ORM). Note that this is a clone of the group from prior to the save as the "real" group has now been updated in the database
$group
Group_Model (a subclass of ORM). This is the group after the save.
  • Stack trace
Group_Model_Core::save()
└─module::event("group_updated",$original,$this)
  • Implementing Modules
none

user_created

  • When triggered
User (with administrative privileges) creates a new user on the Users/Groups page... after adding the user to the database.
  • Arguments
$user
User_Model (a subclass of ORM)
  • Stack trace
User_Model_Core::save()
└─module::event("user_created",$this)
  • Implementing Modules
none

user_before_delete

  • When triggered
User (with administrative privileges) deletes a user on the Users/Groups page... prior to actually performing the deletion.
(It appears that the event handler cannot block the deletion. It can simply note it and take any action it needs to based on this information.)
  • Arguments
$user
User_Model object (a subclass of ORM).
  • Stack trace
Admin_Users_Controller::delete_user($id)
└─User_Model_Core::delete($id=null)
└─module::event("user_before_delete",$this)
  • Implementing Modules
notification

user_deleted

  • When triggered
User (with administrative privileges) deletes a user on the Users/Groups page... after performing the deletion.
  • Arguments
$user
User_Model object (a subclass of ORM). Note that this is a clone of the actual user as the "real" user has now been deleted from the database
  • Stack trace
Admin_Users_Controller::delete_user($id)
└─User_Model_Core::delete($id=null)
└─module::event("user_deleted",$old)
  • Implementing Modules
comment
gallery
notification

user_updated

  • When triggered
User (with administrative privileges) modifies an existing user on the Users/Users page... after updating the user in the database.
  • Arguments
$original
User_Model (a subclass of ORM). Note that this is a clone of the user from prior to the save as the "real" user has now been updated in the database
$user
User_Model (a subclass of ORM). This is the user after the save.
  • Stack trace
User_Model_Core::save()
└─module::event("user_updated",$original,$this)
  • Implementing Modules
gallery

show_user_profile

  • When triggered
User profile page is being populated
  • Arguments
$event_data
stdClass with named arguments { user=>$user, content=>array() }
  • Stack trace
http://(site)/gallery3/user_profiles/show/$id
└─User_Profile_Controller::show($id)
└─module::event("show_user_profile",$event_data)
  • Implementing Modules
comment
gallery
notification
rest

User Login/Authorization Events

user_auth

  • When triggered
A user has reauthenticated their login information or updated key user profile information (e.g. password or email address).
  • Arguments
$user
User_Model object representing the authenticated user
  • Stack trace
User_Controllers::change_email($id)
└─module::event("user_auth",$user)
or
User_Controllers::change_password($id)
└─module::event("user_auth",$user)
or
Reauthenticate_Controllers::auth()
└─module::event("user_auth",$user)
or
  • Implementing Modules
gallery

user_auth_failed

  • When triggered
A user failed to authenticate their login information (e.g. wrong password). Note that either this event or user_auth will be sent during attempts to validate userid/password, but not both.
  • Arguments
$name
Userid that failed to authenticate
  • Stack trace
Login_Controllers::_auth($url)
└─module::event("user_auth_failed",$name)
or
User_Controllers::change_email($id)
└─module::event("user_auth_failed",$user)
or
User_Controllers::change_password($id)
└─module::event("user_auth_failed",$user)
or
Reauthenticate_Controllers::auth()
└─module::event("user_auth_failed",$user)
or
  • Implementing Modules
gallery

user_login

  • When triggered
A user succesfully logs into Gallery3
  • Arguments
$user
User_Model object representing the user that just logged in
  • Stack trace
Login_Controller::_auth($url)
└─auth_Core::login($user)
└─module::event("user_login",$user)
or
identity_Core::load_user
└─auth_Core::login($user)
└─module::event("user_login",$user)
or
Rest_Controller::index
└─auth_Core::login($user)
└─module::event("user_login",$user)
  • Implementing Modules
gallery

user_login_failed

  • When triggered
Incorrect user/password provided when attempting to connect using REST
  • Arguments
$username
string containing the login userid that failed connection
  • Stack trace
Rest_Controller::index
└─module::event("user_login_failed",$username)
  • Implementing Modules
none

user_logout

  • When triggered
A user logs out from Gallery3
  • Arguments
$user
user_Model object representing the user that just logged out
  • Stack trace
Logout_Controller::index()
└─auth_Core::logout()
└─module::event("user_logout",$user)
  • Implementing Modules
none

user_password_change

  • When triggered
User selects the "Change password" button on their user profile page (accessed by clicking on their login name).
This hook is invoked after the changed password has been saved, the user_change_password_form_completed, and the user_auth event sent
  • Arguments
$user
User_Model object
  • Stack trace
abc
└─Users_Controller::change_password($id)
└─module::event("user_password_change",$user)
  • Implementing Modules
none


Gallery Framework Events

gallery_ready

  • When triggered
Called when the Gallery is fully initialized
  • Arguments
none
  • Stack trace
gallery_Core::ready()
└─module::event("gallery_ready");
  • Implementing Modules
none

gallery_shutdown

  • When triggered
Called right before the Kohana framework shuts down.
  • Arguments
none
  • Stack trace
gallery_Core::shutdown
└─module::event("gallery_shutdown")
  • Implementing Modules
none

legal_movie_extensions

  • When triggered
A call is made to legal_file::get_movie_extensions
  • Arguments
$wrapper
stdClass object with the extensions attributes initialized to a an array of "known" movie extensions
  • Stack trace
legal_file_Core::get_movie_extensions()
└─module::event("legal_movie_extensions",$wrapper);
  • Implementing Modules
none

legal_movie_types

  • When triggered
A call is made to legal_file::get_movie_types
  • Arguments
$wrapper
stdClass object with the extensions attributes initialized to a an array of "known" MIME movie types
  • Stack trace
legal_file_Core::get_movie_types()
└─module::event("legal_movie_types",$wrapper);
  • Implementing Modules
none

legal_photo_extensions

  • When triggered
A call is made to legal_file::get_photo_extensions
  • Arguments
$wrapper
stdClass object with the extensions attributes initialized to a an array of "known" photo extensions
  • Stack trace
legal_file_Core::get_photo_extensions()
└─module::event("legal_photo_extensions",$wrapper);
  • Implementing Modules
none

legal_photo_types

  • When triggered
A call is made to legal_file::get_photo_types
  • Arguments
$wrapper
stdClass object with the extensions attributes initialized to a an array of "known" MIME photo types
  • Stack trace
legal_file_Core::get_photo_types()
└─module::event("legal_photo_types",$wrapper);
  • Implementing Modules
none

module_change

  • When triggered
User (with administrative privileges) makes a change to the list of active modules in the Admin>Modules page.
  • Arguments
$changes
stdClass with two defined attributes (activate and deactivate) containing arrays of the modules to be activated or deactivated
  • Stack trace
(Admin/Modules update button is pressed --- and a change has been made in the module list)
└─Admin_Module_Controllers::do_save()
└─module::event("module_change",$changes)
  • Implementing Modules
slideshow

pre_deactivate

  • When triggered
User (with administrative privileges) clicks on the Update button in the Admin/Modules page; called for each module that has had its active state modified.
  • Arguments
$data
stdClass with two named elements { module=>$module_name, messages=>array() }
  • Stack trace
Admin_Modules_Controller::confirm()
└─module::can_deactivate($module_name)
└─module::event("pre_deactivate",$data)
  • Implementing Modules
slideshow

Other Events

The events in this section are those that I couldn't get my head around. I found them in the code, but cold not really figure out what user action triggers them. I would love for someone who does understand these to either fill in the details (and possibly categorize them appropriately) or contact me with the info so that I can make the updates.

before_combine

  • When triggered
Called from within Gallery_View_Core::get_combined before the data in the combine_queue has been processed into a single content item.
  • Arguments
$combine_data
stdClass object
└─contents = view's combine_queue[$type][$group] attribute
  • Stack trace
(theme view (admin|page).html.php)
└─Gallery_View_Core::get_combined($type,$group="core")
└─after_combine($combine_data)
  • Implementing Modules
none

after_combine

  • When triggered
Called from within Gallery_View_Core::get_combined after the data in the combine_queue has been processed into a single content item.
  • Arguments
$combine_data
stdClass object
└─contents = concatenation of the view's combine_queue[$type][$group] attribute
  • Stack trace
(theme view (admin|page).html.php)
└─Gallery_View_Core::get_combined($type,$group="core")
└─after_combine($combine_data)
  • Implementing Modules
none

batch_complete

  • When triggered
The batch_Core::stop method is while the value of the session batch_level attribute is 0
  • Arguments
none
  • Stack trace
(various functions that use batch::start()/batch::stop())
└─batch_Core::stop()
└─module::event("batch_complete");
  • Implementing Modules
gallery
notification
tag

identity_provider_changed

  • When triggered
 ??? - I'm not sure what an identity provider is...
  • Arguments
$current_provider
IdentityProvider - value of the identify_provider setting for gallery prior to changing the provider
$new_provider
IdentityProvider - value of the identify_provider setting for gallery after changing the provider
  • Stack trace
IdentityProvider_Core::change_provider($new_provider)
└─module::event("identity_provider_changed",$current_provider,$new_provider)
  • Implementing Modules
comment
gallery
notification

info_block_get_metadata

  • When triggered
After a call has been made to the info_block_Core::get method with "metadata" as the block_id.
This hook is invoked immediately before returning from the get method.
  • Arguments
$block
Block object containing info about the current album, photo, or movie
$item
Item object representing the item to which the current page applies"
  • Stack trace
info_block_Core::get("metadata",$theme);
└─module::event("info_block_get_metadata",$block,$theme->item)
  • Implementing Modules
tag