== Extension Point : ''IRequestHandler'' ==
||'''Interface'''||''IRequestHandler''||'''Since'''||0.9||
||'''Module'''||''trac.web''||'''Source'''||[source:trunk/trac/web/api.py api.py]||
A ''IRequestHandler'' implementation handles web requests.
== Purpose ==
As a web-based system, Trac naturally needs to [TracDev/RequestHandling handle web requests]. The main work to implement the various different pages is delegated to IRequestHandler implementations.
== Usage ==
Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
Each IRequestHandler is called to ''match'' a web request. The first matching handler is then used to ''process'' the request.
Matching a request usually means checking the `req.path_info` string (the part of the URL relative to the Trac root URL) against a specific string prefix or regular expression.
As this matching is potentially executed for each handler for each request it is somewhat performance sensitive. Avoid spending more time than absolutely necessary.
Processing a request can include basically anything. Commonly template data is prepared and returned together with a (HTML) template file name, which is then rendered and sent to the web browser.
It can also include parsing request parameters, permission checks, database queries and updates, dynamic content generation, alternative MIME types, calling external tools, adding !JavaScript and CSS files, sending custom HTTP headers etc.
Using template files requires that some (but not necessarily the same) component implements [../trac.web.chrome.ITemplateProvider ITemplateProvider] appropriately.
To get the common Trac layout (with logo, navigation bars etc.) HTML templates should ``, and to actually activate a navigation bar item the IRequestHandler component should also implement [../trac.web.chrome.INavigationContributor INavigationContributor].
Instead of implementing IRequestHandler and handling the main part of a request, it's also possible to implement [../trac.web.api.IRequestFilter IRequestFilter] or [../trac.web.api.ITemplateStreamFilter ITemplateStreamFilter] to preprocess and postprocess requests or filter template streams of other request handlers.
== Examples ==
A IRequestHandler can be occasionally useful in isolation, though usually it is accompanied by implementations of other interfaces. Hence the following example is best understood in context of the ComponentModuleExamples.
In Trac, [TicketComponent components] do not have their own page (besides the admin panel). The following example implementation changes this:
{{{
#!python
import re
from trac.core import *
from trac.ticket import model
from trac.web import IRequestHandler
class ComponentModule(Component):
implements(IRequestHandler)
# IRequestHandler methods
def match_request(self, req):
match = re.match(r'/component/(.+)$', req.path_info)
if match:
req.args['name'] = match.group(1)
return True
def process_request(self, req):
name = req.args.get('name')
data = {'component': model.Component(self.env, name)}
return 'component.html', data, None
}}}
The accompanying ''component.html'' template (provided by an appropriate [../trac.web.chrome.ITemplateProvider ITemplateProvider] implementation):
{{{#!xml
Component $component.name
Component $component.name
Owner: $component.owner
$component.description
}}}
== Available Implementations ==
Almost every Trac module implements IRequestHandler (and many more exist in third-party plugins).
== Additional Information and References ==
* [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.web.api.IRequestHandler-class.html Epydoc API Reference]
* See also [../trac.web.chrome.ITemplateProvider ITemplateProvider], [../trac.web.chrome.INavigationContributor INavigationContributor], [../trac.web.api.IRequestFilter IRequestFilter], [../trac.web.api.ITemplateStreamFilter ITemplateStreamFilter]
* Related tickets:
* #8509 use precompiled regex for `match_request`
* #11519 `is_valid_default_handler` class attribute
=== API History ===
* 0.9 introduced the interface.
* 0.11 added a class attribute `jquery_noconflict` that determines if jQuery should be activated in no-conflict mode. ([6715], see also #5954)
* [wiki:TracDev/ApiChanges/1.1#InTrac1.1.2 1.1.2] added a class attribute `is_valid_default_handler` that determines if the class can be set as the `[trac]` `default_handler`. ([12624])