Hooks

Hooks are a powerful tool that allow your component to 'hook into' the Nestor engine at various stages of the Page Build process, as well as any place in the code where a hook has been inserted. A hook is configured within a component class and designates a class and method to call when the hook is invoked within the system. In the Nestor system, a class/method pairing is known as a procedure.

During the Page Build process, the procedure/hook associations are loaded into a hooks array that’s added to the global $site object. The Hooks Definition and Load Process flow chart shows the end-to-end process of defining a hook and loading into the system for use.

Read the Add a Hook section in Extended Component Development to learn how to associate a procedure with a hook in the Nestor system.

Hooks invoked during the Page Build Process

The following flow charts depict when the major system hooks are invoked during the Page Build process. You can use these charts to design your own component hooks if you need to influence the build process at any point. Hooks are shown as green boxes. Note that some hooks receive parameters to route to the designated procedures, and some change the value of passed parameters and send the changed value back into the method from which the hook is invoked. Each hook representation in the flow chart details how parameters are processed by the hook procedure.

1. Page Build process – shows the high level process, hooks displayed are invoked during the instantiation of the $site, $user and $page objects.
2. Build Component Array process – shows the detailed process of building the component array, with hooks invoked by get_components and get_subcomponents methods of the Page class.
3. Build Content process – depicts the hooks invoked during the complex interaction between classes (primarily Page and Component) to render the page content.

Hooks defined in the Core Engine Classes

The following section lists the hooks found in core engine classes, as well as some other standard component classes. Each hook should follow a standard nomenclature to make it easier to trace their origin and function:

[Class-name]_[method-name]_[brief-description]

This list is not exhaustive for the entire system, as any Component has the ability to create hooks.

at_user_login

• Can be used to perform function using current user ID
• called in User::login and User::__construct after user object is created
• arguments passed: user_id
• no return value

at_user_logout

• Can be used to perform function using current user ID
• called in User::logout at the very end, after session info is cleared
• arguments passed: user_id
• no return value

alternative_user_login

• Can be used to create an alternative method to login if there is no user session or persistent login set
• called in User::__construct after performing auto login for user with a session or persistent login
• arguments passed: $user
• no return value

create_component_before

• can be used to reverse auto create or alter any of the $input when a component is created
• called from Component::create_component
• arguments passed: $input used to create component
• return $input array

delete_extirpate_component

• can be used to alter $components array before deletion of members. $components array consists of sub-components of either the component being extirpated, or sub-components of one of its descendants
• called from Component::extirpate_component
• arguments passed: $component_id (parent ID of $components), $components (sub-components of current parent)
• return $components

input_sanitize_textarea

• Can be used to sanitized form input from a text area
• Called from Input::page_requested_url if originating form field was a textarea
• arguments passed: $value of text
• return $value

media_after_display

• Can be used to perform a function on a mediatype component after its display and edit_media_component methods are called
• Called from Media::as_content
• arguments passed: $each_component (media player being displayed), $vce
• no return

media_before_display

• Can be used to perform a function on a mediatype component before its display method is called
• Called from Media::as_content
• arguments passed: $each_component (media player being displayed), $vce
• no return

media_create_component

• Can be used to alter the input for a new media component before it’s created
• Called from Media::create and Mediaplupload:create
• arguments passed: $input used to create media component
• return $input array

media_component_created

• Called after a new media component is created
• Called from Media::create
• arguments passed: $input used to create media component, $response array
• return $response

media_file_uploader

• Can be used to add content before the file upload button
• Called from Media::add_file_uploader
• arguments passed: $recipe_component, $vce
• return $content_media that is added to the page

media_update_component

• Called from Media::update before update_component method is called
• arguments passed: $input used for update
• return $input

media_delete_component

• Called from Media::delete before delete_component method is called
• arguments passed: $input used for delete
• return $input

page_add_recipe

• called when recipe is added to $page in get_components and get_sub_components
• Called from Page::get_components
• arguments passed: $page->recipe and recipe found in current component
• return recipe, which is assigned to $page

page_build_content

• called for each component at the beginning of Build Content process
• called from Page::build_content
• arguments passed: $each_component from $components array, $linked
• no return value

page_build_content_callback

• Called before recursive call to build_content for current component
• Called in Page::build_content
• Arguments passed: $sub_components from current component
• returns $sub_components

page_construct_object

• called in Page::__construct after requested_component object is pulled from db
• arguments passed: $requested_component, $vce
• no return value

page_get_components

• Called in Page::get_components before recursive call back to get_components
• arguments passed: $requested_component, $components, $page
• no return

page_get_sub_components

• Called in Page::get_sub_components before building full sub_components tree
• arguments passed: $requested_components
• return $requested_components

page_requested_components

• can be used to reverse auto create or alter any of the $input when a component is created
• called from Component::create_component
• arguments passed: $input used to create component
• return $input array

page_requested_components

• Can be used to alter $requested_component at the beginning of get_components method
• Called at start of Page::get_components, after call to db to get requested component object
• arguments passed: $requested_component
• return $requested_component

page_requested_url

• Called in Page::__construct after $requested_url is cleaned up and sanitized
• arguments passed: $requested_url, $vce
• no return

recipe_attributes

• Adds fields on recipe page after Recipe Name
• called in ManageRecipes::as_content
• arguments passed: $vce->user
• returns string of HTML content with additional attributes, to be added to Manage Recipe page

recipe_components_each

• Components::recipe_components

requested_sub_components

• Called at start of Page::get_sub_components, after call to db to get array of sub components
• arguments passed: $requested_components
• return $requested_components

site_hook_initiation

• The earliest hook that can be used
• called in Site:__construct
• arguments passed: $hooks array
• no return value

site_javascript_dependencies

• can be used to alter the site->javascript_dependencies array
• called in Site::__construct after javascript & CSS files are added to site
• arguments passed: $site, $site->javascript_dependencies
• return javascript_dependencies array

site_mail_transport

• can be used to route mail message to a different transport method
• if it exists, is called in VCE::mail instead of PHP mailer call
• arguments passed: $vce, $attributes
• return status of message call

site_media_link

• can be used to alter path to which media is uploaded
• called in Site::media_link after $media_link path is built
• arguments passed: $fileinfo arrray, $this
• returns $media_link

site_object_construct

• Can be used to modify the site object
• called in Site::__construct
• arguments passed: $site object
• no return value

user_attributes

• Used to add additional user attributes
• called in: ManageUsers::as_content, UserRegistration::as_content, UserSettings::as_content
• arguments passed: $user_info array
• returns string of HTML content with additional user attributes, to be added to Manage Users page