CWIS Developer 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_REAL_NAME_CHANGED
Type: DEFAULT
Parameters: UserId, OldRealName, NewRealName
This event is signalled immediately after a user's real name is changed. OldRealName and NewRealName contain the old and new real names.

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_FIELDED_SEARCH
Type: CHAIN
Parameters: SearchGroups, User, SavedSearch
This event is signalled immediately before a search is performed, both for regular searches (keyword or Advanced) and for saved search mailings. The User parameter indicates the user for which the search is being performed (if known). The primary purpose for this event is to modify the search parameters (e.g. add values that restrict what shows up in the search results), and changes to only the SearchGroups parameter are used. If a saved search is not associated with the search being performed, the SavedSearch parameter will be NULL.

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.

EVENT_SEARCH_EXTERNAL
Type: NAMED
Parameters: SearchGroups, StartingResult, NumberOfResults, SortByField, SortDescending
This event is signalled immediately before a keyword or fielded search (triggered by a user) is run. Each handler should return NULL or a string that contains an HTML representation of its external search results. The HTML representation should make use of the CSS cw-search classes to provide a similar look as the default CWIS search results.


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_HTML_INSERTION_POINT
Type: DEFAULT
Parameters: PageName, Location, Context
This event is signalled within HTML content file to indicate opportunities to insert HTML into the output. Location is a string, defined by the HTML file(s) that signal, that describes the location on the page where the insertion point occurs, primarily from a functional standpoint (e.g. "Buttons Top"). The use and content of Context is completely up to the individual HTML signaller, but a typical example might include a metadata field ID, for a location that reoccurs for every field displayed on a page.

EVENT_IMAGE_URL_FILTER
Type: CHAIN
Parameters: Url, ImageSize
This event is signalled when a URL for an Image object is retrieved. ImageSize will be one of "Full", "Preview", or "Thumbnail". Only changes to Url are recognized on return.

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

EVENT_FILTER_RESOURCE_BROWSE_LIST
Type: CHAIN
Parameters: SchemaId, ResourceIds
This event is signaled before a resource browsing page is displayed. The ResourceIds parameter contains an array of ResourceIds that will be displayed on the browsing pages.


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_DUPLICATE
Type: DEFAULT
Parameters: DuplicateResource, SourceResource
This event is signalled immediately after a resource is duplicated.

EVENT_RESOURCE_MODIFY
Type: DEFAULT
Parameters: Resource
This event is signalled immediately after an resource is modified.

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

EVENT_RESOURCE_FILE_ADD
Type: DEFAULT
Parameters: Field, Resource, File
This event is signalled immediately after a file is added to a resource.

EVENT_RESOURCE_FILE_DELETE
Type: DEFAULT
Parameters: Field, Resource, File
This event is signalled immediately before a file is deleted from a resource.

EVENT_RESOURCE_VIEW_PERMISSION_CHECK
Type: CHAIN
Parameters: Resource, User, CanView, Schema
This event is signalled when a check is made as to whether a specific user has permission to view an existing resource. Only changes to CanView are recognized on return. For performance reasons, this event is signaled once on each pageload for each resource and user, with the result of this call cached and used for all subsequent permissions checks. This event is usually used to apply additional restrictions (or remove existing restrictions) to resource viewing access.

EVENT_RESOURCE_EDIT_PERMISSION_CHECK
Type: CHAIN
Parameters: Resource, User, CanEdit, Schema
This event is signalled when a check is made as to whether a specific user has permission to edit an existing resource. Only changes to CanEdit are recognized on return. For performance reasons, this event is signaled once on each pageload for each resource and user, with the result of this call cached and used for all subsequent permissions checks. This event is usually used to apply additional restrictions (or remove existing restrictions) to resource editing access.

EVENT_RESOURCE_SHOW_RATING
Type: CHAIN
Parameters: Resource, Rating, ShowRating
This event is signalled when a check is made as to whether a specific resource rating should be displayed. Only changes to ShowRating are recognized on return. This event is not signalled if resource ratings are disabled.


Metadata Events

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. 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_FIELD_SEARCH_FILTER
Type: CHAIN
Parameters: Search, Field
This event is signalled immediately before a field search is performed for displaying results for metadata fields that use incremental search on the resource editing page. Only changes to Search are recognized on return. The Search parameter is either a search string or an array of search groups, depending on whether the field is a reference, controlled name, or tree field, and the Field parameter is a MetadataField object.

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

EVENT_APPEND_HTML_TO_FIELD_DISPLAY
Type: CHAIN
Parameters: Field, Resource, Context, Html
This event is signalled immediately after a field value or an HTML form element for a resource field has been displayed. Only changes to Html are recognized on return. The Field and Resource parameters are MetadataField and Resource objects, respectively, while the Context parameter is set to either DISPLAY, EDIT_COMPLETE_DISPLAY, or EDIT, depending on the context in which the field is displayed.

EVENT_FIELD_VIEW_PERMISSION_CHECK
Type: CHAIN
Parameters: Field, Resource, User, CanView
This event is signalled when a check is made as to whether a specific user has permission to view a specific metadata field. Only changes to CanView are recognized on return. For performance reasons, this event is signaled once on each pageload for each reasource and user, with the result of this call cached and used for all subsequent permissions checks. This event is usually used to apply additional restrictions (or remove existing restrictions) to field access.

EVENT_FIELD_AUTHOR_PERMISSION_CHECK
Type: CHAIN
Parameters: Field, Resource, User, CanAuthor
This event is signalled when a check is made as to whether a specific user has permission to author (provide an initial value for) a specific metadata field. Only changes to CanAuthor are recognized on return. For performance reasons, this event is signaled once on each pageload for each reasource and user, with the result of this call cached and used for all subsequent permissions checks. This event is usually used to apply additional restrictions (or remove existing restrictions) to field access.

EVENT_FIELD_EDIT_PERMISSION_CHECK
Type: CHAIN
Parameters: Field, Resource, User, CanEdit
This event is signalled when a check is made as to whether a specific user has permission to edit (modify an existing value for) a specific metadata field. Only changes to CanEdit are recognized on return. For performance reasons, this event is signaled once on each pageload for each reasource and user, with the result of this call cached and used for all subsequent permissions checks. This event is usually used to apply additional restrictions (or remove existing restrictions) to field access.

EVENT_CNAME_REMAPPED
Type: DEFAULT
Parameters: OldControlledNameId, NewControlledNameId
This event is signalled immediately before a controlled name is remapped.


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


Plugin Events

EVENT_PLUGIN_CONFIG_CHANGE
Type: DEFAULT
Parameters: PluginName, ConfigSetting, OldValue, NewValue
This event is signalled when a configuration setting for a plugin has changed. PluginName is the name of the plugin that had a configuration setting changed. ConfigSetting is the name of the configuration setting that changed. OldValue is the old configuration setting value. NewValue is the new configuration setting value.

EVENT_PLUGIN_EXTEND_EDIT_RESOURCE_COMPLETE_ACCESS_LIST
Type: CHAIN
Parameters: AllowList
This event is signaled when EditResourceComplete page tries to decide whether a referer is allowed; AllowList is then being passed to each hooked plugins so they can add their pages' regexes to the list, so EditResourceComplete can be redirected from these pages.


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.