Koha Plugin Hooks

From Koha Wiki
Jump to navigation Jump to search

We call plugin hooks to the places in Koha where the installed plugins are queried to check which ones implement specific methods. For example, there are hooks in the OPAC to allow plugins to inject JavaScript code in the templates in runtime.

This is accomplished by requiring plugins to implement specific methods in order to provide the functionality. For example, in order to inject API routes using plugins, Koha does this: 

    if ( C4::Context->config("enable_plugins") )
    {
        # plugin needs to define a namespace
        @plugins = Koha::Plugins->new()->GetPlugins(
            {
                method => 'api_namespace',
            }
        );
    }

    foreach my $plugin ( @plugins ) {
        $spec = inject_routes( $spec, $plugin, $validator );
    }

So it queries for plugins that implement the api_namespace method, and then (somehow) uses that method from the resulting plugins list.

A good reference is the Kitchen Sink plugin which implements every hook.

Implemented hooks

Method Use Description First version Last changed Bug
report Must be launched from plugins home page Run a report. 3.12.00 Bug 7804
tool Must be launched from plugins home page Run a tool page. 3.12.00 Bug 7804
to_marc tools/stage-marc-import.pl Convert arbitrary files to MARC from record staging tool. 3.18.00 Bug 12412
edifact admin/edi_accounts.pl Add a vendor to EDIFACT module 3.22.00 Bug 15630
opac_online_payment opac/opac-account*.pl Add a payment method 17.11.00 Bug 19173
intranet_catalog_biblio_enhancements_toolbar_button catalogue/detail.pl Add a button to toolbar of biblio record detail page 17.11.13 Bug 20968
api_namespace + api_routes Koha/REST/Plugin/PluginRoutes.pm Allows the extension of the Koha API via plugins. This can allow for custom vendor integrations and prototyping of new routes. 17.11.13 Bug 21116
static_routes Koha/REST/Plugin/PluginRoutes.pm Allows plugin authors to serve static files through the API without the requirement to tweak the Apache configuration files. 19.05.08 Bug 22835
opac_head + opac_js Koha::Template::Plugin::KohaPlugins for koha-tmpl/opac-tmpl/bootstrap/en/includes/doc-head-close.inc Adds CSS/Javascript to OPAC. Applies on all pages. 17.11.11 Bug 20181
intranet_head + intranet_js Koha::Template::Plugin::KohaPlugins for koha-tmpl/intranet-tmpl/prog/en/includes/doc-head-close.inc Adds CSS/Javascript to Staff interface. Applies on all pages. 17.11.11 Bug 21352
after_biblio_action C4::Biblio This method targets the use case in which you want to do some actions when CRUD operations on bibliographic records take place. For example, notifying an external system of the change. The actions should be done asynchronously to avoid performance hits. This method could add tasks to a task queue. 19.11.00 Bug 22709
after_item_action C4::Items This method targets the use case in which you want to do some actions when CRUD operations on items take place. For example, notifying an external system of the change. The actions should be done asynchronously to avoid performance hits. This method could add tasks to a task queue. 19.11.00 Bug 22709
check_password Koha::Patron This method is called when a password is added or updated. It can be used to implement custom checking of password strength. Please note that it can only be used for this, not for checking passwords when a user tries to log in. Plain text password and borrowernumber are passed to the check_password method. (It is also used to implement support for the Norwegian national patron database, as a plugin.) 19.11.00 Bug 22706
intranet_catalog_biblio_tab catalogue/detail.pl This method should return an array of hashrefs that contain the keys title and content. This will have the effect of adding new tabs to the intranet biblio detail view. content key can contain HTML. To make this work, you need to "use Koha::Plugins::Tab;" in your main plugin .pm. See the example plugin provided on the bug. 19.11.00 Bug 23050
opac_online_payment_threshold koha-tmpl/opac-tmpl/bootstrap/en/includes/account-table.inc This method is called when OPAC displays all payment plugins. A number should be returned, that represents the minimum allowed payment. If the amount that the patron will pay is lower than the threshold then payment is not allowed. This value may optionally depend on a specific library or any other environment condition. 19.11.00 Bug 23213
before_send_messages process_message_queue.pl This allows plugins to pre-process messages in the message queue before they are sent. 19.11.06 Bug 24183
ill_availability_services Koha/Illrequest/Availability.pm Enables ILL availability plugins to intercept the request creation process and, using the supplied metadata, search for and display possible relevant items from whichever availability plugins are installed. 20.05.00 Bug 23173
opac_detail_xslt_variables opac-detail.pl Returns a hashref with key => value, that gets merged to the one passed to XSLTParse4Display (refer to the bug for an example usage, and the KitchenSink plugin for an example hook implementation) 20.05.03 Bug 25961
opac_results_xslt_variables opac-search.pl Returns a hashref with key => value, that gets merged to the one passed to searchResults (refer to the the bug for an example usage, and the KitchenSink plugin for an example hook implementation) 20.05.03 Bug 25961
after_hold_create C4/Reserves.pm Called after a hold has been placed. 20.11.00 Bug 24031
after_circ_action C4/Circulation.pm Called at the end of AddRenewal (Bug 25855), AddIssue and AddReturn (Bug 21468). 20.11.00 Bug 25855, Bug 21468
cronjob_nightly plugins_nightly.pl The hook is called whenever the plugins_nightly cronscript is run. It allows for regular background jobs to be executed on a daily basis. 20.11.03 Bug 25245
item_barcode_transform Anywhere in Koha that item barcodes are scanned in ( circulation.pl, returns.pl, etc ).
 Accepts a scanned item barcode, returns a barcode they may or may not have been modified by the plugin. Refer to BarcodeTransformer plugin for an example of usage.
 21.11.00 Bug 26351
patron_barcode_transform Anywhere in Koha that patron barcodes (aka cardnumber) are input ( patron search, patron addition, patron edition, etc ).
 Accepts a scanned patron barcode, returns a barcode they may or may not have been modified by the plugin. 21.11.00 Bug 26352
after_authority_action C4::AuthoritiesMarc These hooks are called for each call of AddAuthority, ModAuthority or DelAuthority. 21.11.00 Bug 27173
after_hold_action Koha::Hold and C4::Reserves These hooks are triggered under several hold status changes. The 'action' is specified explicitly, depending on the context. Actions can be fill, cancel, suspend, and resume. In 22.11 following additional actions were added: transfer, waiting, and processing 22.05.00,21.11.04,21.05.12 Bug 30072, Bug 31894
background_tasks Koha::BackgroundJob Plugins can register background tasks 22.05 Bug 30410
after_recall_action Koha/Recalls.pm 22.11 Bug 31896
after_account_action Koha/Account.pm 22.11 Bug 31895
patron_generate_userid Koha::Patron Allow plugin to generate userid when creating patrons 23.05 Bug 32426
intranet_cover_images

opac_cover_images

detail.tt

results.tt

opac-detail.tt

opac-results.tt

Allows a plugin to implement a cover service for the staff interface and/or OPAC. See https://github.com/PTFS-Europe/koha-plugin-addBDSCovers for an example 23.05 Bug 32680
patron_consent_type opac/opac-patron-consent.pl, Koha::Patron This plugin adds a patron consent type for use on OPAC account page, tab Your consents. 23.11 Bug 31503
template_include_paths C4::Templates Adds the ability for plugins to add paths to Template::Toolkit's INCLUDE_PATH option 24.05 Bug 35070
before_biblio_action C4::Biblio Same as after_biblio_action but before data changes 24.05 Bug 29392 Bug 34943
auth_client_get_user Koha::Auth::Client This plugin hook allows to change patron data or define the patron based on the authenticated user. 24.05 Bug 36503
transform_prepared_letter C4::Letters::GetPreparedLetter Allows modification of letter data created by GetPreparedLetter before the letter data is returned to the caller 24.05 Bug 35568
framework_defaults_override Koha::UI::Form::Builder::Biblio ApplyFrameworkDefaults add plugin to add more fine grained defaults handling 24.05 Bug 36503

Under development hooks

Method Use Description First version Bug
addbiblio_check_record cataloguing/addbiblio.pl When saving a record, the hook is called with the MARC record as a parameter. If the hook returns anything, the return values are shown to the user, and saving the record is prevented.
Bug 24589
capture_raw_password Koha::Patron The hook is called whenever a password is created or edited. Necessary to implement support for the Norwegian National Patron Database as a plugin.
Bug 27309
checkpw C4::Auth Ability to add and use authentication plugins. Bug 20340
object_store_pre + object_store_post Koha::Object These hooks are called whenever a Koha::Object is stored (inserted or updated in database).
Bug 28173
before_authority_action C4::AuthoritiesMarc Same as after_authority_action but before data changes Bug 29392
before_index_action Koha/SearchEngine/Elasticsearch/Indexer.pm Hook before_index_action is with the action update.

This is run on the array reference to the biblio records that are about to be updated in the Elasticsearch index.

With this, a plugin can change the record so that it better suits the index without having to change the actual record in the database.

Bug 31897
elasticseach_to_document Koha::SearchEngine::Elasticsearch To complete Elasticsearch document generated by Koha from a biblio/authority record. Bug 36433

Plugin background jobs

For implementing plugin background jobs, look at this commit on the KitchenSink plugin.

In order to be able to register background jobs, plugins need to:

  • Have a namespace key on the metadata. Accessible through
$plugin->get_metadata->{namespace}
  • Implement a background_tasks method, that returns a hashref, mapping task codes to implementing classes:
sub background_tasks {
    return {
        foo => 'MyPlugin::Class::Foo',
        bar => 'MyPlugin::Class::Bar',
    };
}

CAVEAT #1: For the time being, there's no default template implemented for job detail views for plugin tasks.

CAVEAT #2: When installing a plugin that uses the background_tasks hook, it is best to restart the background_jobs_worker.pl processes as they cache plugin code and background job mappings.


Developer handbook

Retrieved from "https://wiki.koha-community.org/w/index.php?title=Koha_Plugin_Hooks&oldid=34306"