j※このページは翻訳中です。協力者を求めています。

イベント

コアをハックせずにconcrete5の既存の挙動に別の機能を追加したい場合に、イベントを使うことができます。

事例

サイトのページタイプがそれ自身に関連づけられた別の情報を持っているとします。そのタイプのページを削除した場合、そのページに関連づけられた別の情報を、別のデータベーステーブルから削除したいとします。その場合、すぐに思いつく手段としてconcrete5のPage::delete()メソッドを変更したいと思うかもしれませんが、それはアップグレードを難しくするため、良くない手段です。その代わりに、concrete5がページを削除する処理にフックして、あなた自身のコードを実行させるのが良い手段です。

イベントリスト

現在、次に上げるイベントをフックして使うことができます（注：最新の情報は常にconcrete5.orgのEventsページを確認してください）：

on_start

最も最初の方で発火するイベントです。いくつかのオブジェクト（Collectionなど）はまだ使えません。

on_before_render

ページのレンダリングが開始される直前に発火します。このイベントにフックされた関数は、引数としてレンダリングされるページが渡されます。

on_render_complete

ページのレンダリングが終了した直後に発火します。このイベントにフックされた関数は、引数としてレンダリングされたページが渡されます。

on_group_delete

グループが削除された際に発火します。falseを返すことでキャンセルできます。このイベントにフックされた関数は、引数として削除されるグループが渡されます。

on_page_update

ページが更新された際に発火します。このイベントにフックされた関数は、引数として更新されるページが渡されます。

on_page_move

ページが移動した時に発火します。このイベントにフックされた関数は３つの引数を持ちます：移動中のページ、古い親ページ、新しい親ページです。

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.)

5.4.2.2で追加されたイベント

次のイベントは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

5.5で追加されたイベント

次のイベントは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


5.6.1時点の全てのイベントの一覧

ユーザーイベント

  • 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

プライベートメッセージイベント

  • on_private_message_delete
  • on_private_message_marked_as_read
  • on_private_message_marked_not_new
  • on_private_message_over_limit

ページイベント

  • 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

ジョブイベント

  • on_job_execute
  • on_job_install
  • on_job_install
  • on_job_uninstall
  • on_before_job_execute

グループイベント

  • on_group_add
  • on_group_delete
  • on_group_update

地域イベント

  • on_get_countries_list
  • on_get_states_provinces_list

コンポーザーイベント

  • on_composer_delete_draft
  • on_composer_publish
  • on_composer_save_draft

ファイルイベント

  • 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

出力イベント

  • on_before_render
  • on_render_complete 

ブロックイベント

  • on_block_load

サイトイベント

  • on_start

イベントにフックする方法

これらのイベントにフックする方法はとてもシンプルです。

次のコードをあなたのサイトの config/site.php ファイルに追加してください。

define('ENABLE_APPLICATION_EVENTS', true);

注：上のコードはconcrete5のバージョン5.4以下の場合に必要です

「site_events.php」ファイルを config/ ディレクトリーに設置してください。

設置したファイル無いで、次のようなコードでイベントの拡張を定義することができます。

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

引数

  • $event - 実行するイベント（例："on_user_add"）。
  • $class - 実行したいメソッドを含むクラス名。
  • $method - イベントが発生した際に実行したいメソッド名。
  • $filename - 実行したいメソッドを含むクラスを含むファイル。絶対パスか、サイトからの相対パスで記述します。
  • $params - メソッドに引き渡したい追加のパラメーターを指定できます。
  • $priority - 登録されたイベント内で実行される順番（ひとつのイベントに複数の拡張がフックされた場合に有効になります）。

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.