[[PageOutline(2-5,Contents,pullout)]]

= Create a Trac plugin skeleton given a list of interfaces

== Description

This Python package will create a Trac plugin skeleton given a name and a list of interfaces it is to communicate with. The console script, {{{create-trac-plugin}}}, front-ends TracPluginTemplateScript and creates the basic layout of the plugin using [http://pythonpaste.org/script/ PasteScript]. Then the basic contents of the [t:TracDev/ComponentArchitecture component] are generated by looking through the selected interfaces and filling out the imports needed and signatures for the methods used.

The {{{create-trac-component}}} console script front-ends [source:createpluginscript/anyrelease/create_trac_plugin/create_component.py create_component.py], which can be used as as standalone piece without the rest of the package.

To list the interfaces available, simply run either of the console scripts without arguments:

{{{#!sh
$ create-trac-plugin 

Usage: 
 create-trac-plugin <name> [interface1] [interface2] [...] # to create a component with name
 create-trac-plugin # for usage and component list

Interfaces available:

IAdminPanelProvider
IAttachmentChangeListener
IAttachmentManipulator
IAuthenticator
IContentConverter
IDatabaseConnector
IEnvironmentSetupParticipant
IHTMLPreviewAnnotator
IHTMLPreviewRenderer
ILegacyAttachmentPolicyDelegate
INavigationContributor
IPermissionGroupProvider
IPermissionPolicy
IPermissionRequestor
IPermissionStore
IPreferencePanelProvider
IPropertyDiffRenderer
IPropertyRenderer
IRepositoryConnector
IRequestFilter
IRequestHandler
IResourceManager
ISearchSource
ITemplateProvider
ITemplateStreamFilter
ITicketActionController
ITicketChangeListener
ITicketManipulator
ITimelineEventProvider
IWikiChangeListener
IWikiMacroProvider
IWikiPageManipulator
IWikiSyntaxProvider
}}}

To make a plugin named !NewPlugin that implements the ITemplateStreamFilter and IWikiSyntaxProvider interfaces, run:

{{{#!sh
create-trac-plugin NewPlugin ITemplateStreamFilter IWikiSyntaxProvider
}}}

This will setup a directory structure using TracPluginTemplateScript:

{{{
NewPlugin/
|-- NewPlugin.egg-info # generated by PasteScript
|-- newplugin
|   |-- __init__.py
|   `-- newplugin.py
`-- setup.py
}}}

{{{newplugin.py}}} will be populated with markers for the appropriate interfaces and the correct imports:

{{{#!python
"""
NewPlugin:
a plugin for Trac
http://trac.edgewall.org
"""

from trac.core import *

from trac.web.api import ITemplateStreamFilter
from trac.wiki.api import IWikiSyntaxProvider

class NewPlugin(Component):

    implements(ITemplateStreamFilter, IWikiSyntaxProvider)

    ### methods for ITemplateStreamFilter

    """Filter a Genshi event stream prior to rendering."""

    def filter_stream(self, req, method, filename, stream, data):
        """Return a filtered Genshi event stream, or the original unfiltered
        stream if no match.

        `req` is the current request object, `method` is the Genshi render
        method (xml, xhtml or text), `filename` is the filename of the template
        to be rendered, `stream` is the event stream and `data` is the data for
        the current template.

        See the Genshi documentation for more information.
        """

    ### methods for IWikiSyntaxProvider

    def get_link_resolvers(self):
        """Return an iterable over (namespace, formatter) tuples.

        Each formatter should be a function of the form
        fmt(formatter, ns, target, label), and should
        return some HTML fragment.
        The `label` is already HTML escaped, whereas the `target` is not.
        """

    def get_wiki_syntax(self):
        """Return an iterable that provides additional wiki syntax.

        Additional wiki syntax correspond to a pair of (regexp, cb),
        the `regexp` for the additional syntax and the callback `cb`
        which will be called if there's a match.
        That function is of the form cb(formatter, ns, match).
        """
}}}

To just generate the file (to stdout), use {{{create-trac-component}}} (or {{{python create_component.py}}}):

{{{#!sh
create-trac-component NewPlugin ITemplateStreamFilter IWikiSyntaxProvider
}}}

== Bugs/Feature Requests

Existing bugs and feature requests for CreatePluginScript are 
[report:9?COMPONENT=CreatePluginScript here].

If you have any issues, create a 
[/newticket?component=CreatePluginScript new ticket].

If you want to submit patches, please read the 
[wiki:olemis#Guidelinestocollaborate patch submission guidelines].

[[TicketQuery(component=CreatePluginScript&group=type,format=progress)]]

== Download

Download the zipped source from [export:createpluginscript here].

If you just want {{{create_component.py}}} go [/svn/createpluginscript/anyrelease/create_trac_plugin/create_component.py here].

== Source

You can check out CreatePluginScript from [/svn/createpluginscript/anyrelease here] using Subversion, or [source:createpluginscript/anyrelease browse the source] with Trac.

== Installation

This script does not require installation. Download the script to your computer and it can be run from the command line.

== Recent Changes

[[ChangeLog(createpluginscript, 3)]]

== Author/Contributors

''Originally developed at [http://topp.openplans.org The Open Planning Project]''

'''Author:''' [wiki:k0s] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:''' [wiki:olemis Olemis Lang] [[BR]]