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