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
ページが移動した時に発火します。このイベントにフックされた関数は3つの引数を持ちます:移動中のページ、古い親ページ、新しい親ページです。
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.