Plugin Contexts

From Sit

Jump to: navigation, search
SiT! Manual SiT! Manual Developers Guide → Plugin Contexts Chapter 6
Plugin contexts are points during SiT's normal execution where your plugin code can be executed. Your plugin should be developed to have a function for each Plugin Context where you would like additional code to execute. You need to register a hook for each of your plugin functions so that your function can be executed at a particular plugin context.

In your plugin call the function plugin_register() to set up your hook.

Note: Since plugin context names have changed in version 3.90 this page presents two lists of contexts, make sure you are using the correct list.

Contents

3.6x and earlier

Warning.png The information in this article (or section) relates to SiT! v3.69 and earlier. Later versions may have removed this functionality.

This is the list of contexts available in SiT! v3.6x and in earlier versions, where appropriate the version number that the context was added is shown.

  • activity_types - Adds additional types to the calendar activity types
  • about - Add to the about page
  • add_user_form - Add to the end of the add user form (Added in 3.66)
  • ajaxdata_add_action - Add custom ajax data request actions (Added in 3.60)
  • automata - Perform an action each time auto.php is run
  • add_user_form - Add to the add user form
  • billing_approve_form - Add to the billing approve form
  • cfgvar - Add a plugin config variable (Added in v3.60)
  • config_form - Add to the configuration form (Added in 3.60)
  • config_after_save - Perform an action after the configuration is saved (Added in 3.90)
  • config_save - Perform an action when the configuration is saved (Added in 3.60)
  • contact_details - Add to the contact details table
  • contract_add_form - Add to the contract add form (Added in 3.65)
  • contract_add_form_more - Add to the 'more' section of the contract add form (Added in 3.65)
  • contract_add_save - Perform an action after a contract is added (Added in 3.65)
  • contract_edit_form - Add to the contract edit form (Added in 3.65)
  • contract_edit_form_more - Add to the 'more' section of the contract edit form (Added in 3.65)
  • contract_edit_save - Perform an action after a contract is edited (Added in 3.65)
  • cp_menu - Add to the control panel menu page (Removed as of v3.90)
  • define_menu - Modify existing menu entries
  • edit_contact_form - Add to the edit contact form
  • edit_escalation_path_form - Add to the edit escalation path form (Added in v3.63)
  • edit_escalation_path_save - Perform an action after the edit escalation path form is saved (Added in v3.63)
  • edit_incident_form - Add to the edit incident form
  • edit_profile_form - Add to the edit profile form
  • edit_site_form - Add to the edit site form
  • edit_site_save - Perform an action after a site is saved
  • emailtemplate_list - Add to the email template list
  • email_arrived - Perform an action after an inbound email arrives but before attachments are processed (Added in v3.50)
  • feedback_reports_menu - Add to the feedback reports menu
  • feedback_browse - Add to the bottom of the browse feedback page (Added in v3.60)
  • feedback_browse_viewresponse - Add to the bottom of the browse feedback response page (Added in v3.60)
  • feedback_browse_endpage_extend - Extending the page after the browse form, and before the footer (Added in v3.63)
  • holdingqueue_rowshade - Takes a parameter ($update) which passes the updateid, returns a css class to colour a row in the holding queue
  • holiday_ack - Perform an action after holiday has been approved/disapproved
  • holiday_cancelled - Perform an action after holiday is cancelled (each day). (Added in v3.45)
  • holiday_chart_cal - Add to the top of the holiday chart page
  • holiday_chart_day_am - ???
  • holiday_chart_day_pm - ???
  • html_head - Inside the HTML <head> section of htmlheader.inc.php (Added in v3.66)
  • incident_html_head - Inside the HTML <head> section of incident_html_top.inc.php (Added in v3.66)
  • inboundemail_customer_visibility_update - After an email has arrived and an entry has been added to the update log. (Added in v3.63)
  • incident_add_form_top - At the top of the add incident page before the form (Added in v3.90)
  • incident_add_reassign - Runs after a new incident has been opened and assigned for the first time (Added in 3.66)
  • incident_closed - Perform an action after an incident is closed
  • incident_closing - Perform an action before the 'close incident' window is closed (Added in v3.45)
  • incident_closing_form1 - Add to the form that is displayed when closing an incident (To be added in v3.50p1)
  • incident_created - Perform an action after an incident is created
  • incident_created_contract - Perform an action after an incident is created and logged against a contract
  • incident_created_site - Perform an action after an incident is created and logged against a site
  • incident_created_suggest_user - Runs when a new incident has been opened and the incident is to be assigned, this runs after the in built suggest user but before assignment, setting the $suggested_user variable will allow you to override the default assignment (Added in 3.66)
  • incident_details - Add to the incident details page
  • incident_details_phone - Add after the phone number of the customer on the incident details page
  • incident_details_menu - Add to the incident details menu.
  • incident_details_mobile - Add after the mobile number of the customer on the incident details page
  • incident_details_summary - Adds additional content to the details area of the incident details page (Added in 3.??)
  • incident_details_update_content_row - ???
  • incident_details_updatehead_content_row - ???
  • incident_edited - Perform an action after an incident is updated
  • incident_email_form1 - Add to the form that is displayed before sending an email from an incident (Added in v3.50)
  • incident_email_form2- Add to the form that is displayed while sending an email from an incident (Added in v3.50)
  • incident_email_tofield_autocomplete- Add to the form that is displayed while sending an email from an incident, directly below the 'cc' field, for adding autocomplete (Added in v3.60)
  • incident_email_ccfield_autocomplete - Add to the form that is displayed while sending an email from an incident, directly below the 'to' field, for adding autocomplete (Added in v3.60)
  • incident_html_head - Adds additional content to the head tags of the incident details page (Added in 3.66)
  • incident_html_top_menu_closed_incident - Add additional menu items to the incident details page for open incidents (Added in 3.66)
  • incident_html_top_menu_open_incident - Add additional menu items to the incident details page for closed incidents (Added in 3.66)
  • incident_reassign - Runs when an incident has been reassigned sucessfully (Added in 3.66)
  • incidents_content_between_my_and_expertise - Add content between the 'my incidents' and expertise queues (Added in 3.66)
  • new_incident_form - Add to the new incident form
  • noticetemplate_list - Add to the list of notice templates table
  • portal_header_menu - Add to the portal header menu
  • portal_html_head - Inside the HTML <head> section of portalheader.inc.php (Added in v3.66)
  • pre_incident_closed - Perform an action before the incident is closed
  • save_contact_form - Perform an action when the edit contact form is saved
  • save_profile_form - Perform an action when the edit profile form is saved
  • search_contacts - Search through contacts
  • search_incidents - Search through incidents
  • search_kb - Search through the knowledgebase
  • search_sites - Search through sites
  • search_user_results - Search through user results
  • site_created - Perform an action after a site is created
  • site_details - Add to the site details page
  • statistics_table_overview - Add to the statistics table
  • trigger_actions - Add a trigger action
  • trigger_actions_defined - ???
  • trigger_types - Extend the list of available triggers
  • trigger_variables - Extend the list of available trigger variables
  • user_created - Perform an action after a user has been created
  • user_profile_edit_before_backup_switchover - Perform an action before switching incidents to the users backups when changing status
  • triggername - Any trigger name can be used as a plugin context (see Triggers for more information)

3.90 and later

Warning.png The information in this article (or section) relates to SiT! v3.90 and later. Earlier versions may not have this functionality.

v3.90 introduces a new naming scheme for plugin contexts which means that most plugins written for versions prior to 3.90 will need updating.

Bug.png A bug has been reported that affects this functionality: Make plugin hooks consistent

Convention:

  • <page name> - Add content to the page in the most appropriate place for custom content
  • <page_name>_content - Add more content to the page in the next appropriate place for custom content (usually underneath existing data)
  • <page name>_form - Placed at the end of the form inside the form table but before the buttons
  • <page name>_form_more - Placed at the end of the collapsible form section (more/advanced), where there is one, inside the form table but before the buttons
  • <page name>_submitted - Placed after form data has been submitted (and validated) but before it is saved to the database or actioned upon
  • <page name>_saved - Placed after form data has been saved successfully but before confirmation is output or the page is redirected.
  • <table_name>_table - Placed at the end of a table of data but before it is closed
  • <event name>_action - Code to be executed when a specific event occurs

How to use contexts

Broom icon32.png This is a draft article (or section) and is a work-in-progress.
Please help us and our readers by clicking the edit link above and expanding/improving this text.

For contexts matching the page name

These contexts allow you to add content to the page in the most appropriate place for the page shown, usually this is immediately below the page title.

example code: 

function myplugin_foobar()
{
    echo "<h3>Some example output with lots of foo and a little bar</h3>";
    echo "<p>foo / bar</p>";
}

plugin_register('example_context', 'myplugin_foobar');

For contexts ending with _content

These contexts allow you to add content to the page in the next appropriate place for the page shown, usually this is immediately below the page data.

example code: 

function myplugin_foobar()
{
    echo "<p><strong>Note:</strong> Please foo when entering bar into the example form.</p>";
}

plugin_register('example_context_content', 'myplugin_foobar');

For contexts ending with _form

These contexts allow you to add a table row to a form. Forms have tables with two columns, the first column is a table header and the second column is a table cell.

example code: 

function myplugin_foobar()
{
    echo "<tr><th>Field title</th><td><input type='text' size='10' name='myplugin_custom_field' /></td></tr>";
}

plugin_register('example_context_form', 'myplugin_foobar');

For contexts ending with _form_more

These contexts allow you to add a table row to the 'more' section of a form. The 'more' section is usually hidden until the user clicks a link. Forms have tables with two columns, the first column is a table header and the second column is a table cell.

example code: 

function myplugin_foobar()
{
    echo "<tr><th>Field title</th><td><input type='text' size='10' name='myplugin_custom_field' /></td></tr>";
}

plugin_register('example_context_form_more', 'myplugin_foobar');

For contexts ending with _submitted

These contexts are executed after a form is submitted and allow you to manipulate form variables before they are saved. In order to use form variables your plugin must first make them global.

example code: 

function myplugin_foobar()
{
    global $example_field_var;

    if ($example_field_var == 'foo')
    {
        $example_field_var = 'bar');
    }
}

plugin_register('example_context_submitted', 'myplugin_foobar');

For contexts ending with _saved

These contexts are executed after form data has been successfully saved in the database, this can be useful if you want to act upon the data after it has been stored (for example to store some of the data in your plugins' own database table).

example code: 

function myplugin_foobar()
{
    global $example_field_var;

    $sql = "INSERT INTO `myplugin_table` (`foobar` = '{$example_field_var}')";
    mysql_query($sql);
}

plugin_register('example_context_saved', 'myplugin_foobar');

For contexts ending with _table

These contexts allow you to add a data table row. Pay close attention to the number and type of the columns in the table as your plugin will need to match this.

example code: 

function myplugin_foobar()
{
    echo "<tr><td>Example</td><td>Foo</td><td>Bar</td></tr>";
}

plugin_register('example_context_table', 'myplugin_foobar');

For contexts ending with _action

These contexts are executed when a specific even occurs.

example code: 

function myplugin_foobar()
{
    global $example_var;
    $bar = clean_int($example_var);

    $sql = "UPDATE `myplugin_table` SET (`foo_count` = `foo_count` +1') WHERE `bar` = '{$bar}'";
    mysql_query($sql);
}

plugin_register('example_context_action', 'myplugin_foobar');


Available on every page

  • page_start - At the very top of the page, just after the <body> tag (Added in v3.90)
  • page_end - At the very bottom of the page just before the </body> tag(Added in v3.90)
  • after_page - Perform an action before the HTML page is output (Added in 3.90)
  • before_page - Perform an action before the HTML page is output (Added in 3.90)

Available on specific pages

  • billing_matrix
  • billing_matrix_edit
    • billing_matrix_edit_form
    • billing_matrix_edit_submitted
    • billing_matrix_edit_saved
  • billing_matrix_new
    • billing_matrix_new_form
    • billing_matrix_new_submitted
    • billing_matrix_new_saved
  • config
    • config_fieldset
    • config_submitted
    • config_saved
  • contact_delete
    • contact_delete_form
    • contact_delete_submitted
    • contact_delete_saved
  • contact_details
    • contact_details_table
  • contact_edit
    • contact_edit_form
    • contact_edit_submitted
    • contact_edit_saved
  • contact_new
    • contact_new_form
    • contact_new_submitted
    • contact_new_saved
  • contacts
  • contract_delete_contact
    • contract_delete_contact_form
    • contract_delete_contact_submitted
    • contract_delete_contact_saved
  • contract_details
  • contract_new_contact
    • contract_new_contact_form
    • contract_new_contact_submitted
    • contract_new_contact_saved
  • contract_new
    • contract_new_form
    • contract_new_form_more
    • contract_new_submitted
    • contract_new_saved
  • contracts
  • edit_backup_users
    • edit_backup_users_form
    • edit_backup_users_submitted
    • edit_backup_users_saved
  • edit_user_skills
    • edit_user_skills_form
    • edit_user_skills_submitted
    • edit_user_skills_saved
  • escalation_path_edit
    • escalation_path_edit_form
    • escalation_path_edit_submitted
    • escalation_path_edit_saved
  • feedback_browse
  • forgotpwd
  • help
  • holding_queue
  • holiday_request
  • holidays
    • holiday_list_table
  • inbox
  • incident_close
    • incident_close_form
    • incident_close_submitted
    • incident_close_saved
  • incident_edit
    • incident_edit_form
    • incident_edit_submitted
    • incident_edit_saved
  • incident_new
    • incident_new_form
    • incident_new_submitted
    • incident_new_saved
  • incidents
  • index
  • inventory
  • inventory_edit
    • inventory_edit_form
    • inventory_edit_submitted
    • inventory_edit_saved
  • inventory_new
    • inventory_new_form
    • inventory_new_submitted
    • inventory_new_saved
  • inventory_view
    • inventory_view_content
  • kb
  • kb_article
  • kb_article_submitted
  • kb_article_saved
  • kb_view_article
  • main
    • dashboard_table
  • manage_user_dashboard
    • manage_user_dashboard_submitted
    • manage_user_dashboard_saved
  • notifications
  • products
  • release_notes
    • release_notes_content
  • reseller_new
    • reseller_new_form
    • reseller_new_submitted
    • reseller_new_saved
  • search
    • search_form
    • search_form_submitted
    • search_incidents_table
    • search_sites_table
    • search_users_table
    • search_contacts_table
    • search_kb_table
  • site_new
    • site_new_form
    • site_new_form_more
    • site_new_submitted
    • site_new_saved
  • site_edit
    • site_edit_form
    • site_edit_submitted
    • site_edit_saved
  • site_delete
    • site_delete_form
    • site_delete_submitted
    • site_delete_saved
  • site_details
    • site_details_table
  • site_types
  • sites
  • skills_matrix
  • statistics
    • statistics_content
  • status
    • status_content
  • tasks
  • task_edit
    • task_edit_form
    • task_edit_submitted
    • task_edit_saved
  • task_new
    • task_new_form
    • task_new_submitted
    • task_new_saved
  • templates
    • templates_form
    • templates_submitted
    • templates_saved
    • templates_variables_content
  • user_profile_edit
    • user_profile_edit_form
    • user_profile_edit_submitted
    • user_profile_edit_saved
  • user_new
    • user_new_form
    • user_new_submitted
    • user_new_saved
  • users
  • vendors

Special contexts

These contexts need special handling

  • triggername - Any trigger name can be used as a plugin context (see Triggers for more information)
  • ajaxdata_action -
  • auto - Perform an action each time auto.php is run (This could be every minute)
  • define_menu
  • define_portal_menu
  • email_arrived_action
  • cfgvar
  • trigger_actions_defined - Passes parameters, including $paramarray and $action

Converting your plugin from 3.6x to 3.90+

Broom icon32.png This is a draft article (or section) and is a work-in-progress.
Please help us and our readers by clicking the edit link above and expanding/improving this text.

If your plugin uses any of the contexts listed in the first column of the table below, you will need to change it to use the context listed in the second column for your plugin to be compatible with v3.90 or later.

Plugin context changes
3.6x Context (old) 3.90+ Context (new)
add_user_form user_new_form
ajaxdata_add_action ajaxdata_action
automata auto
billing_approve_form  ?
config_after_save config_saved
config_save config_submitted
contact_details contact_details_table
contract_add_form contract_new_form
contract_add_form_more contract_new_form_more
contract_add_save contract_add_saved
cp_menu removed in v3.90
edit_contact_form contact_edit_form
edit_escalation_path_form escalation_path_edit_form
edit_escalation_path_save escalation_path_edit_saved
edit_incident_form incident_edit_form
edit_profile_form user_profile_edit_form
edit_site_form site_edit_form
edit_site_save site_edit_saved
emailtemplate_list templates_variables_content
email_arrived email_arrived_action
feedback_reports_menu removed in v3.90
feedback_browse_viewresponse
feedback_browse_endpage_extend
holdingqueue_rowshade removed in v3.90
holiday_ack
holiday_cancelled
holiday_chart_cal
html_head before_page
inboundemail_customer_visibility_update
incident_add_form_top incident_new
incident_closed incident_close_saved
incident_closing incident_close_saved
incident_closing_form1 incident_close_form
incident_created incident_new_saved
incident_created_contract removed in v3.90
incident_created_site removed in v3.90
incident_details_phone
incident_details_menu
incident_details_mobile
incident_edited incident_edit_saved
incident_email_form1
incident_email_form2
incident_email_tofield_autocomplete
incident_email_ccfield_autocomplete
portal_header_menu removed in v3.90
pre_incident_closed incident_close_submitted
new_incident_form removed in v3.90
noticetemplate_list removed in v3.90
save_contact_form contact_new_saved
save_profile_form user_profile_edit_saved
search_contacts search_contacts_table
search_incidents search_incidents_table
search_kb search_kb_table
search_sites search_sites_table
search_user_results search_users_table
site_created site_new_saved
site_details site_details_table
statistics_table_overview statistics_content
trigger_actions
trigger_types
trigger_variables
user_created user_new_saved

See Also

Retrieved from "http://sitracker.org/wiki/Plugin_Contexts"
Personal tools
project