== Extension Point : ''IPreferencePanelProvider'' ==
||'''Interface'''||''IPreferencePanelProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#IPreferencePanelProvider 0.11]||
||'''Module'''||''trac.prefs''||'''Source'''||[source:trunk/trac/prefs/api.py api.py]||
The ''IPreferencePanelProvider'' allows adding panels to Trac's preferences dialog.
== Purpose ==
Trac provides a [wiki:TracDev/ReleaseNotes/0.11#UserPreferences user preferences] system. Plugins can participate in this system by implementing the IPreferencePanelProvider. This allows a unified web UI where all preferences are configured in the same place, the preferences dialog.
When a user browses to the preferences dialog, all implementations are called to provide any implemented panels, which are shown as tabs. When the user activates a tab the respective implementation is called to render the page corresponding to that tab.
== Usage ==
Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
The implementation has to render a panel by returning a template file name and a data dictionary to be used by that template. (See [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.web.chrome.ITemplateProvider ITemplateProvider] and [wiki:TracDev/PluginDevelopment/ExtensionPoints/trac.web.api.IRequestHandler IRequestHandler])
The panel template should {{{}}} to provide the consistent common UI to all preference panels. Including this will also add a "Save changes" button if the template contains no forms of its own. Note that the {{{IPreferencePanelProvider}}} still has to implement any actual save functionality!
Saving preferences is usually handled by storing the value with an appropriate unique key in the [wiki:TracDev/TracSession session]. With the default "Save changes" button this means checking for {{{req.method == 'POST'}}} (and possibly {{{req.args['action']=='save'}}} if there are other ''POST'' usages?)
== Examples ==
The following example provides a simple scratchpad text area in the preferences. Any entered text is stored in the session. In a real preference panel, the saved preference value should of course be read from the session by some other (part of the) component to configure some of its functionality.
{{{#!python
from trac.core import *
from trac.prefs import IPreferencePanelProvider
class ScratchpadPreferencePanel(Component):
implements(IPreferencePanelProvider)
# IPreferencePanelProvider methods
def get_preference_panels(self, req):
yield ('scratchpad', _('Scratchpad'))
def render_preference_panel(self, req, panel):
if req.method == 'POST':
new_content = req.args.get('scratchpad_textarea')
if new_content:
req.session['scratchpad'] = new_content
add_notice(req, _('Your Scratchpad text has been saved.'))
req.redirect(req.href.prefs(panel or None))
return 'prefs_scratchpad.html', {
'scratchpad_text': req.session.get('scratchpad', 'your text')
}
}}}
The accompanying ''prefs_scratchpad.html'':
{{{#!xml
Scratchpad
}}}
== Available Implementations ==
* [source:trunk/trac/prefs/web_ui.py#L84 trac.prefs.web_ui.PreferencesModule][[br]]
Defines most of Trac's core preference panels.
* [source:trunk/trac/mimeview/pygments.py#L123 trac.mimeview.pygments.PygmentsRenderer][[br]]
Defines the ''Syntax Highlighting'' preference panel for TracSyntaxColoring with [http://pygments.pocoo.org/ Pygments].
* In third-party plugins:
* [th:wiki:AccountManagerPlugin AccountManagerPlugin][[br]]
Defines an ''Account'' panel for account/password management.
* [th:wiki:AnnouncerPlugin AnnouncerPlugin][[br]]
Advanced implementation with pluggable announcer preference boxes.
== Additional Information and References ==
* [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.prefs.api.IPreferencePanelProvider-class.html epydoc]
* [http://www.edgewall.org/docs/trac-trunk/html/api/trac_prefs.html#trac.prefs.IPreferencePanelProvider API Reference]
* [query:status=!closed&keywords=~userpreferences Tickets relating to userpreferences]
* #9673: Proposal for linking preferences and TracIni options
* #6002: Ticket with a patch defining a {{{get_session_option}}} helper method
* #9162: Ticket with a patch to split the core {{{IPreferencePanelProviders}}} from the {{{PreferencesModule}}}
* #9313: Ticket about documenting preference session saving