This document describes how event hooks work in the Translate extension;
how to add hooks for an event; and how to run hooks for an event.

For a more comprehensive guide to hooks, navigate to your root MediaWiki
directory, and then find /docs/hooks.txt.

== Rationale ==

Hooks allow us to decouple optionally-run code from code that is run for
everyone. It allows MediaWiki hackers, third-party developers and local
administrators to define code that will be run at certain points in the mainline
code, and to modify the data run by that mainline code. Hooks can keep mainline
code simple, and make it easier to write extensions. Hooks are a principled
alternative to local patches.

== Writing hooks ==

=== PHP hooks ===
For a guide to PHP hooks, navigate to your root MediaWiki
directory, and then find docs/hooks.txt.

=== JavaScript hooks ===
JavaScript hooks for the Translate extension are a little different. To use
them, declare a dependency on ext.translate.hooks:

 $wgResourceModules['...'] = array(
 	'scripts' => '...js',
 	'dependencies' => array( 'ext.translate.hooks' ),
 );

And then in that module use:
 mw.translateHooks.add( name, hookFunction );

where name is a string, but hookFunction is not (unlike in the case of PHP hooks)
but rather a function reference. Return values from JavaScript hooks are ignored.

== Events and parameters ==

This is a list of known events and parameters; please add to it if you're going
to add events to the Translate extension.

<!--
Post processing step to format in wiki
^;([^ ]+): >>> ;<nowiki>\1<nowiki>:
-->

=== PHP events ===

;Translate:MessageGroupStats:isIncluded: Controls whether message group is shown for a given language in language or message group statistics. Mostly used internally by Translate to hide discouraged groups and groups restricted to certain languages.
 string          $groupId: Message group id
 string          $code: Language code

;SpecialTranslate::executeTask: You can output the default task output
 RequestContext  $context: For adding output, accesing current interface language etc.
 TranslateTask   $task = null: Current task if any
 MessageGroup    $group
 array           $options: Active options

;TranslateBeforeAddModules: Provides an opportunity to load extra modules
 array          &$modules: List of resource loader module names

;TranslateEventMessageGroupStateChange: Event triggered when a message group workflow state is changed in a language
 MessageGroup    $group: Message group instance
 string          $code: Language code
 string          $oldState
 string          $newState

;TranslateEventTranslationEdit: Event triggered when a translation is created or changed
 MessageHandle   $handle

;TranslateEventTranslationReview: Event triggered when a translation is proofread
 MessageHandle   $handle

;TranslateFormatMessageBeforeTable: Provides an opportunity to manipulate the display of translation strings (messages) in the main table
 string         &$message: The message that will be displayed
 TMessage        $m: Object representing the source object, useful for $m->original() and $m->translation()
 MessageGroup    $group: The source message group
 string          $targetLanguage: The language for which translations are being shown
 array          &$extraAttribs: An array of attributes that will be added to the table row

;TranslateGetBoxes: Provides an opportunity to add or remove "boxes" (translation helpers) from the translation interface
 MessageGroup    $group: The message group being worked on
 MessageHandle   $handle: An object representing the translation page (e.g. 'MediaWiki:Example/qqq')
 array          &$boxes: An associative array to be appended to (format: 'name' => 'some HTML string')

;TranslateGetExtraInputs: Provides an opportunity to add extra form inputs to to the default translation editor
 string         &$translation: The translation as it stands
 string         &$extraInputs: The extra input space, ready for HTML to be appended

;TranslateGetSpecialTranslateOptions: Provides an opportunity for overriding task values
 array          &$defaults: Associative array of default values
 array          &$nondefaults: Associative array of nondefault (override) values

;Translate:GettextFFS:headerFields: Allows to customize headers of exported Gettext files per group. Certain X-headers nor Plural-Forms cannot be customized.
 array          &$headers: List of prefilled headers. You can remove, change or add new headers.
 MessageGroup    $group: Message group instance
 string          $code: Language code

;Translate:newTranslation: Event triggered when non-fuzzy translation has been made
 MessageHandle   $handle
 int             $revisionId
 string          $text: Content of the new translation
 User            $user: User who created or changed the translation

;TranslatePostInitGroups: Hook to register new message groups to Translate. Manual cache clear may be needed to have this hook executed.
 array          &$groups: Map of message group id to message group instance
 array          &$deps: List of dependencies as supported by DependecyWrapper class from MediaWiki
 array          &$autoload: List of autoloaded classes. Key is the name of the class and value is filename.

;TranslatePrefillTranslation: Provides an opportunity for a new translation to start not from as a carte blanche (the default) but from some prefilled string
 string         &$translation: The translation string as it stands
 MessageHandle   $handle: The current MessageHandle object

=== JavaScript events ===

;afterRegisterFeatures: Provides an opportunity to register event handlers, etc., whenever a new form is opened.
 jQuery          form: The new form

;afterSubmit: Provides an opportunity to modify a Translate translation form immediately after it is submitted
 jQuery          form: The form that has just been submitted

;beforeSubmit: Provides an opportunity to modify a Translate translation form immediately before it is submitted
 jQuery          form: The form being submitted
