Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.prefs.api.IPreferencePanelProvider


Ignore:
Timestamp:
Jun 5, 2011, 9:11:47 PM (13 years ago)
Author:
Peter Suter
Comment:

—

Legend:

Unmodified
Added
Removed
Modified

  • TracDev/PluginDevelopment/ExtensionPoints/trac.prefs.api.IPreferencePanelProvider

    v1 v1  
     1== Extension Point : ''IPreferencePanelProvider'' ==
     2
     3||'''Interface'''||''IPreferencePanelProvider''||'''Since'''||0.11||
     4||'''Module'''||''trac.prefs''||'''Source'''||[source:trunk/trac/prefs/api.py api.py]||
     5
     6
     7The ''IPreferencePanelProvider'' allows adding panels to Trac's preferences dialog.
     8
     9== Purpose ==
     10
     11Trac provides a 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.
     12
     13When 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.
     14
     15== Usage ==
     16
     17Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     18
     19The 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])
     20
     21The panel template should {{{<xi:include href="prefs.html" />}}} 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!
     22
     23Saving 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?)
     24
     25== Examples ==
     26
     27The 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.
     28
     29{{{#!python
     30from trac.core import *
     31from trac.prefs import IPreferencePanelProvider
     32
     33class ScratchpadPreferencePanel(Component):
     34
     35    implements(IPreferencePanelProvider)
     36
     37    # IPreferencePanelProvider methods
     38
     39    def get_preference_panels(self, req):
     40        yield ('scratchpad', _('Scratchpad'))
     41
     42    def render_preference_panel(self, req, panel):
     43        if req.method == 'POST':
     44            new_content = req.args.get('scratchpad_textarea')
     45            if new_content:
     46                req.session['scratchpad'] = new_content
     47                add_notice(req, _('Your Scratchpad text has been saved.'))
     48            req.redirect(req.href.prefs(panel or None))
     49
     50        return 'prefs_scratchpad.html', {
     51            'scratchpad_text': req.session.get('scratchpad', 'your text')
     52        }
     53}}}
     54
     55The accompanying ''prefs_scratchpad.html'':
     56{{{#!xml
     57<!DOCTYPE html
     58    PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     59    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
     60<html xmlns="http://www.w3.org/1999/xhtml"
     61      xmlns:py="http://genshi.edgewall.org/"
     62      xmlns:xi="http://www.w3.org/2001/XInclude">
     63  <xi:include href="prefs.html" />
     64  <head>
     65    <title>Scratchpad</title>
     66  </head>
     67  <body>
     68    <p><label>A Scratchpad text field:
     69      <textarea rows="10" cols="40" name="scratchpad_textarea">
     70        $scratchpad_text
     71      </textarea>
     72    </label></p>
     73  </body>
     74</html>
     75}}}
     76
     77== Available Implementations ==
     78
     79  * [source:trunk/trac/prefs/web_ui.py#L84 trac.prefs.web_ui.PreferencesModule][[br]]
     80    Defines most of Trac's core preference panels.
     81  * [source:trunk/trac/mimeview/pygments.py#L123 trac.mimeview.pygments.PygmentsRenderer][[br]]
     82    Defines the ''Syntax Highlighting'' preference panel for TracSyntaxColoring with [http://pygments.pocoo.org/ Pygments].
     83  * In third-party plugins:
     84   * [th:wiki:AccountManagerPlugin AccountManagerPlugin][[br]]
     85     Defines an ''Account'' panel for account/password management.
     86   * [th:wiki:AnnouncerPlugin AnnouncerPlugin][[br]]
     87     Advanced implementation with pluggable announcer preference boxes.
     88
     89== Additional Information and References ==
     90
     91 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.prefs.api.IPreferencePanelProvider-class.html epydoc]
     92 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_prefs.html#trac.prefs.IPreferencePanelProvider API Reference]
     93 * [query:status=!closed&keywords=~userpreferences Tickets relating to userpreferences]
     94 * #9673: Proposal for linking preferences and TracIni options
     95 * #6002: Ticket with a patch defining a {{{get_session_option}}} helper method
     96 * #9162: Ticket with a patch to split the core {{{IPreferencePanelProviders}}} from the {{{PreferencesModule}}}
     97 * #9313: Ticket about documenting preference session saving