Search:

# CWIS Developers Documentation

# CWIS Event Callbacks

These events can be hooked to callbacks via ApplicationFramework::HookEvent() (using the global ApplicationFramework object `$AF`) or through the Plugin::HookEvents() method for plugins.

## Event Types

There are four event types: DEFAULT, CHAIN, FIRST, and NAMED. The primary difference between the event types is what happens with the return values from the event handler callbacks.

DEFAULT - The default event type. Any handler return values are ignored.

CHAIN - Result chaining event type. For this type the parameter array to each event handler is the return value from the previous handler, and the final return value is sent back to the event signaller. This event type might be used for tasks like filtering text before it's displayed.

FIRST - First response event type. For this type event handlers are called until one returns a non-NULL result, at which point no further handlers are called and that last result is passed back to the event signaller. This event type might commonly be used for events like user authentication.

NAMED - Named result event type. Return values from each handler are placed into an array with the handler (function or class::method) name as the index, and that array is returned to the event signaller. (The array index for handlers that are class methods is the class name plus "::" plus the method name.)

## Hookable CWIS Events

Event parameters are passed to the event handlers as an associative array, with the listed parameter names as the index.

### User Account Events

EVENT_USER_ADDED
Type: DEFAULT
Parameters: UserId, Password
This event is signalled after a new user has been created but before the user has verified their account. It is not signalled when user accounts are manually imported. The password is in cleartext (unencrypted).

EVENT_USER_VERIFIED
Type: DEFAULT
Parameters: UserId
This event is signalled immediately after a new user has verified ("activated") their account.

EVENT_USER_DELETED
Type: DEFAULT
Parameters: UserId
This event is signalled immediately before a user account is deleted.

EVENT_USER_PASSWORD_CHANGED
Type: DEFAULT
Parameters: UserId, OldPassword, NewPassword
This event is signalled immediately after a user password is changed. OldPassword and NewPassword contain the old and new password in cleartext (unencrypted).

EVENT_USER_EMAIL_CHANGED
Type: DEFAULT
Parameters: UserId, OldEmail, NewEmail
This event is signalled immediately after a user's email address is changed. OldEmail and NewEmail contain the old and new email addresses.

EVENT_USER_LOGIN
Type: DEFAULT
Parameters: UserId, Password
This event is signalled immediately after a user logs in. Password is the password the user entered in cleartext (unencrypted).

EVENT_USER_LOGIN_RETURN
Type: CHAIN
Parameters: ReturnPage
This event is signalled after a user successfully logs in. ReturnPage is the page or URL to which the user will return after the login.

EVENT_USER_LOGOUT
Type: DEFAULT
Parameters: UserId
This event is signalled immediately before a user explicitly logs out. It is not signalled when users are automatically logged out because of an inactivity timeout.

EVENT_USER_LOGOUT_RETURN
Type: CHAIN
Parameters: ReturnPage
This event is signalled after a user logs out. ReturnPage is the page or URL to which the user will return after logging out.

EVENT_USER_AUTHENTICATION
Type: FIRST
Parameters: UserName, Password
This event is signalled when a user attempts to log in. Handlers should return TRUE if the login with the specified user name and password should succeed, FALSE if it should fail, or NULL if they cannot be sure whether the login should succeed or fail. A handler should only return FALSE if there is some overriding reason to force the login to fail, since returning any value but NULL will prevent any subsequent handlers from attempting to authenticate the login.

### Search Events

EVENT_KEYWORD_SEARCH
Type: CHAIN
Parameters: Keywords
This event is signalled immediately before a keyword search is performed, including fielded searches that include a keyword search. Handlers must return the keyword string in their return value array, which is then used for the search. For fielded searches, this event is signalled before the fielded search is signaled.

EVENT_SEARCH_RESULTS
Type: CHAIN
Parameters: SearchResults
This event is signalled immediately after a search is performed. The sole parameter is an array of sorted search result values, with the Resource IDs as the index and the search result scores as the values. Handlers must return the search results as part of their return value array.

EVENT_SEARCH_COMPLETE
Type: DEFAULT
Parameters: AdvancedSearch, SearchParameters, SearchResults
This event is signalled immediately after EVENT_SEARCH_RESULTS. The AdvancedSearch parameter is `TRUE` for an advanced (fielded) search and `FALSE` otherwise. The SearchParameters parameter is the search parameters encoded for inclusion in a URL. (Methods of SavedSearch can be used to decode.) The SearchResults parameter is an array of sorted search result values, with the Resource IDs as the index and the search result scores as the values.

### User Interface Events

EVENT_PAGE_LOAD
Type: DEFAULT
Parameters: PageName
This event is signalled at the beginning of the page load process, before the PHP file for the page is loaded. The PageName parameter is the base name for the page being loaded (e.g. "FullRecord" for FullRecord.php). This event is signalled before EVENT_PHP_FILE_LOAD, so any modifications to the page name by handlers hooked to EVENT_PHP_FILE_LOAD will not be reflected in the PageName parameter to this event.

EVENT_PHP_FILE_LOAD
Type: CHAIN
Parameters: PageName
This event is signalled immediately before the PHP file for a page is loaded. The PageName parameter is the base name for the page being loaded (e.g. "FullRecord" for FullRecord.php). The returned value for PageName can be a modified base name, which will be used to select a PHP file to be loaded, or the full name (with path) of a file, which will be loaded instead of the PHP file. This event is intended to be used when possible modification of the PHP file name is needed. To just hook an event onto pages being loaded, use EVENT_PAGE_LOAD.

EVENT_HTML_FILE_LOAD
Type: CHAIN
Parameters: PageName
This event is signalled immediately before the HTML content file for a page is loaded. The PageName parameter is the base name for the page being loaded (e.g. "FullRecord" for FullRecord.html). The returned value for PageName can be a modified base name, which will be used to select an HTML file to be loaded, or the full name (with path) of a file, which will be loaded instead of the HTML content file. This event is intended to be used when possible modification of the HTML file name is needed. To just hook an event onto pages being loaded, use EVENT_PAGE_LOAD.

EVENT_HTML_FILE_LOAD_COMPLETE
Type: DEFAULT
Parameters: (none)
This event is signalled immediately after the HTML content file for a page is loaded.

EVENT_IN_HTML_HEADER
Type: DEFAULT
Parameters: (none)
This event is signalled (at least in the default UI) within the HTML header, to allow code to be added between the `<head>` and `</head>` tags. NOTE: This event being signalled is dependent on the implementer of the active UI including a call to ApplicationFramework::SignalEvent() in their `StandardPageStart.html`.

EVENT_COLLECTION_ADMINISTRATION_MENU
Type: NAMED
Parameters: (none)
This event is signalled as the Collection Administration menu is displayed. Handlers should return an array with the URLs for any menu options they want to add as the indexes, and the labels for those menu options as the values. If the URLs do not include `.php` somewhere within them, then the URL will be assumed to be the name of a plugin PHP or HTML page, and a link will be generated to load that page when the menu option is selected.

EVENT_USER_ADMINISTRATION_MENU
Type: NAMED
Parameters: (none)
This event is signalled as the User Administration menu is displayed. Handlers should return an array with the URLs for any menu options they want to add as the indexes, and the labels for those menu options as the values. If the URLs do not include `.php` somewhere within them, then the URL will be assumed to be the name of a plugin PHP or HTML page, and a link will be generated to load that page when the menu option is selected.

EVENT_SYSTEM_ADMINISTRATION_MENU
Type: NAMED
Parameters: (none)
This event is signalled as the System Administration menu is displayed. Handlers should return an array with the URLs for any menu options they want to add as the indexes, and the labels for those menu options as the values. If the URLs do not include `.php` somewhere within them, then the URL will be assumed to be the name of a plugin PHP or HTML page, and a link will be generated to load that page when the menu option is selected.

EVENT_SYSTEM_INFO_LIST
Type: NAMED
Parameters: (none)
This event is signalled as the System Administration menu is displayed. Handlers should return an array with any system info lines they want to add, with the line labels (left side) for the array index and the line values (right side) for the array values. Labels should not include a final ":". Values can include HTML code.

EVENT_MODIFY_PRIMARY_NAV
Type: CHAIN
Parameters: NavItems
This event is signalled as the primary navigation menu is displayed. The NavItem parameter contains an associative array with navigation item labels as the indexes and navigation item links as the values. Nav item links that consist of only letters, numbers, and underscores will have `index.php?P=` prepended to them. This event is only supported for user interfaces that signal the event. (All interfaces distributed with the base CWIS package signal this event.)

EVENT_MODIFY_SECONDARY_NAV
Type: CHAIN
Parameters: NavItems
This event is signalled as the secondary navigation menu (if any) is displayed. The NavItem parameter contains an associative array with navigation item labels as the indexes and navigation item links as the values. Nav item links that consist of only letters, numbers, and underscores will have `index.php?P=` prepended to them. This event is only supported for user interfaces that signal the event. (All interfaces distributed with the base CWIS package signal this event except the Low Vision interface.)

### Resource Events

EVENT_RESOURCE_CREATE
Type: DEFAULT
Parameters: Resource
This event is signalled when a new Resource object is created (at the end of the constructor). It could be used to (for example) automatically fill in certain values for any new resources.

EVENT_RESOURCE_ADD
Type: DEFAULT
Parameters: Resource
This event is signalled immediately after a resource is added (actually, immediately after a temporary resource record is converted to permanent status).

EVENT_RESOURCE_DELETE
Type: DEFAULT
Parameters: Resource
This event is signalled immediately before a resource is deleted.

EVENT_FIELD_DISPLAY_FILTER
Type: CHAIN
Parameters: Field, Resource, Value
This event is signalled immediately before a field value for a resource is displayed. Only changes to Value are recognized on return, however as with all CHAIN events, all parameters should still be return in an array so that any other hooked event handlers will execute correctly. This event only applies to fields of types Text, Number, Date, Timestamp, URL, Point, Paragraph, and Flag. The Field and Resource parameters are MetadataField and Resource objects, respectively, while Value is in whatever non-object format is returned by Resource::Get().

EVENT_PRE_FIELD_EDIT_FILTER
Type: CHAIN
Parameters: Field, Resource, Value
This event is signalled immediately before a field value for a resource is presented for editing. Only changes to Value are recognized on return, however as with all CHAIN events, all parameters should still be return in an array so that any other hooked event handlers will execute correctly. This event only applies to fields of types Text, Number, Date, Timestamp, URL, Point, Paragraph, and Flag. The Field and Resource parameters are MetadataField and Resource objects, respectively, while Value is in whatever non-object format is returned by Resource::Get(). This event is often used in conjunction with EVENT_POST_FIELD_EDIT_FILTER to convert a value between the stored format and a format more desirable for editing.

EVENT_POST_FIELD_EDIT_FILTER
Type: CHAIN
Parameters: Field, Resource, Value
This event is signalled immediately after a field value for a resource has possibly been edited. Only changes to Value are recognized on return, however as with all CHAIN events, all parameters should still be return in an array so that any other hooked event handlers will execute correctly. This event only applies to fields of types Text, Number, Date, Timestamp, URL, Point, Paragraph, and Flag. The Field and Resource parameters are MetadataField and Resource objects, respectively, while Value is in whatever non-object format is returned by Resource::Get(). This event can be used to normalize the format of values entered for a specific field.

### Periodic Events

For periodic events, more than the indicated period may elapse between calls to methods hooked to the event, as periodic execution is dependent on system activity. All periodic events are called as soon as possible after the first time they are hooked.

EVENT_HOURLY
Type: DEFAULT
Parameters: LastRunAt
This event is signalled hourly (every 60 minutes). LastRunAt is the date and time the event was last executed, in MySQL format (YYYY-MM-DD HH:MM:SS).

EVENT_DAILY
Type: DEFAULT
Parameters: LastRunAt
This event is signalled daily (every 24 hours). LastRunAt is the date and time the event was last executed, in MySQL format (YYYY-MM-DD HH:MM:SS).

EVENT_WEEKLY
Type: DEFAULT
Parameters: LastRunAt
This event is signalled weekly (every 7 days). LastRunAt is the date and time the event was last executed, in MySQL format (YYYY-MM-DD HH:MM:SS).

EVENT_MONTHLY
Type: DEFAULT
Parameters: LastRunAt
This event is signalled approximately monthly (every 30 days). LastRunAt is the date and time the event was last executed, in MySQL format (YYYY-MM-DD HH:MM:SS).

EVENT_PERIODIC
Type: NAMED
Parameters: LastRunAt
Methods hooked to this event are called X minutes after the previous call, where X is the value returned by that previous call. This allows event handlers to set their own desired period between invocations. LastRunAt is the date and time the event was last executed, in MySQL format (YYYY-MM-DD HH:MM:SS).

### Miscellaneous Events

EVENT_OAIPMH_REQUEST
Type: DEFAULT
Parameters: RequesterIP, QueryString
This event is signalled when responding to an OAI-PMH request. The QueryString parameter contains the portion of the URL with the GET parameters pertaining to the OAI-PMH query.