This is the documentation for concrete5 version 5.6 and earlier. View Current Documentation

Events

Use concrete5's events when you wish to include extra functionality based on things concrete5 already does, without hacking away at the core.

Example

A site's page type has some extra information associated with it. When you delete a page of this type, you want that extra information, in an extra database table, to go away as well. Obviously, you could modify the Page::delete() method in the concrete5 class, but that's ugly and leaves you with a system you can't easily upgrade. Instead, you really need to hook into concrete5's delete page routine, and run your own code, and be done with it.

Event List

Currently, the following events are available to hook into:

on_start

This is one of the first things that fires, it fires so early that several objects may not be available yet, (such as the collection object).

on_before_render

Fires immediately before rendering the entire page. If a function hooks into this event, the function is passed the page being rendered as the argument.

on_render_complete

Fires immediately after rendering the entire page. If a function hooks into this event, the function is passed the page being rendered as the argument.

on_group_delete

Fires when a group is deleted. Can be cancelled by returning false. If a function hooks into this event, the function is passed the group to be deleted as the argument.

on_page_update

Fires when a page is updated. If a function hooks into this event, the function is passed the page being updated as the argument.

on_page_move

Fires when a page is moved. Functions hooking into this event are passed three arguments: the first is the page being moved, the second is the old parent page, and the third is the new parent page.

on_page_duplicate

Fires when a page is copied. Functions hooking into this event are passed two arguments: the first is the new page, the second is the current page.

on_page_delete

Fires when a page is being deleted. Can be cancelled by returning -1. If a function hooks into this event, the function is passed the page to be deleted as the argument.

on_page_add

Fires when a page is being added. If a function hooks into this event, the function is passed the new page object as the argument. This happens immediately after a page is added.

on_page_view

Fires when a page is being viewed. If a function hooks into this event, the function is passed two arguments: the first is the page being viewed, the second is the user object viewing it. User object could be unregistered/anonymous. Note: if statistics are disabled this event will never fire.

on_page_version_approve

Fires when a page's version is approved. Passes an additional page object, containing the approved version.

on_user_add

Fires when a user is being added. Functions hooking into this event receive the newly added UserInfo object as their one argument.

on_user_delete

Fires when a user is being deleted. Can be cancelled by returning false. If a function hooks into this event, the function is passed the user to be deleted as the argument (a UserInfo object.)

on_user_update

Fires when a user is being updated. If a function hooks into this event, the function is passed the user to be updated as the argument (a UserInfo object.) IMPORTANT NOTE - When hooking into deletion events, if your function returns -1, the deletion will NOT continue. In this way, you can use custom code to stop people from deleting content.

on_user_login

Fires when a user logs in via the /login page (NOTE: this does NOT fire when a user is logged in programmatically.)

New Events For 5.4.2.2

The following events have just been added to 5.4.2.2:

on_file_set_password

on_file_add

on_file_download

on_file_version_add

on_file_version_duplicate

on_file_version_update_title

on_file_version_update_tags

on_file_version_update_description

on_file_version_approve

on_file_version_deny

on_user_enter_group

on_user_exit_group

on_user_friend_add

on_user_friend_remove

New Events for 5.5

The following events have been added in version 5.5.

on_user_validate

on_user_logout

on_user_activate

on_user_deactivate

on_before_job_execute

on_job_execute

on_job_install

on_job_uninstall


Full List of Events as of 5.6.1

User Events

  • on_user_activate
  • on_user_add
  • on_user_change_password 
  • on_user_change_password
  • on_user_deactivate
  • on_user_delete
  • on_user_enter_group
  • on_user_exit_group
  • on_user_friend_add
  • on_user_friend_remove
  • on_user_login
  • on_user_logout
  • on_user_update
  • on_user_validate

Private Message Events

  • on_private_message_delete
  • on_private_message_marked_as_read
  • on_private_message_marked_not_new
  • on_private_message_over_limit

Page Events

  • on_page_add
  • on_page_body_index
  • on_page_delete
  • on_page_duplicate
  • on_page_get_icon
  • on_page_move
  • on_page_output
  • on_page_update
  • on_page_urlify
  • on_page_version_add
  • on_page_version_approve
  • on_page_version_refresh_cache

Job Events

  • on_job_execute
  • on_job_install
  • on_job_install
  • on_job_uninstall
  • on_before_job_execute

Group Events

  • on_group_add
  • on_group_delete
  • on_group_update

Locale Events

  • on_get_countries_list
  • on_get_states_provinces_list

Composer Events

  • on_composer_delete_draft
  • on_composer_publish
  • on_composer_save_draft

File Events

  • on_file_add
  • on_file_added_to_set
  • on_file_download
  • on_file_removed_from_set
  • on_file_set_password
  • on_file_version_add
  • on_file_version_approve
  • on_file_version_deny
  • on_file_version_duplicate
  • on_file_version_update_description
  • on_file_version_update_tags
  • on_file_version_update_title

Render Events

  • on_before_render
  • on_render_complete 

Block Events

  • on_block_load

Site Events

  • on_start

Hooking into Events

Hooking into these events is pretty simple.

Add the following to your config/site.php file.

define('ENABLE_APPLICATION_EVENTS', true);

*NOTE: the above code is only need for concrete5 versions less than 5.4

Add a file named "site_events.php" to your config/ directory.

Within this file, you define events using the method

Events::extend($event, $class, $method, $filename, $params = array(), $priority = 5);

Additional Arguments

  • $event - event to run (e.g. "on_user_add").
  • $class - Class Name that contains the method you would like to run.
  • $method - Method you would like to run when event occurs.
  • $filename - File that contains the class that contains the method. Can be an absolute path or relative to the current site.
  • $params - any additional parameters you would like passed to your function.
  • $priority - Order in which the registered events are run (only applies if there are multiple extends to a single event).

Example

Let's say you would like to setup an additional row in a special database table whenever anyone adds a user. This could happen through the dashboard, or through front-end registration, and you really don't want to fork concrete5, so events are the best way to move forward with this requirement.

It's already obvious you need to hook into the "on_user_add" event. Next, choose a name for the function that will be run when doing so. How about "setupUserJoinInfo" ? Next, choose where this function will live - it has to be a class. How about just created a new class named "ApplicationUser" and a file for it in the models directory, named "models/application_user.php".

If all this is the case, this is the line you would write in your site_events.php file:

	Events::extend('on_user_add', 'ApplicationUser', 'setupUserJoinInfo', 'models/application_user.php');

Then, within your ApplicationUser class, simply define

	public function setupUserJoinInfo($ui) { 		// $ui is the newly created user 	}

Then you'd simply grab whatever information about the newly created user you needed, and place that information in the join table (likely a userID, etc...)

Hooking into Page Type Events

While the above syntax gives you a lot of control over how your event hooks get run, there is an even easier way to define page-type level events. Events::extendPageType(). The syntax for extending page type events is

Events::extendPageType($handle, $event]);

As you see here, you don't need to define any filenames or method names to be run when using this syntax. In this example, any event you hook into at the page type level will automatically run for those particular page types, using the event name in that page type's controller as the automatically run method.

Example

Let's say you want to run some custom code every time a page of a certain type is added. If the page type you want to extend is named "discussion_post," you'd simply add

	Events::extendPageType('discussion_post', 'on_page_add');

Then, make sure that controllers/page_types/discussion_post.php exists, and that "on_page_add" is a function inside it.

If you want to extend all the page-level events for a particular page type, you don't need to add them all with Events::extendPageType. Instead, simply leave the event blank.

Note: extending events at the page type level is a great way to only extend page-level events for the particular page types that require it.

Loading Conversation