= create a trac plugin skeleton given a list of interfaces =

== Description ==

This python package will create a trac plugin skeleton given its name and a list of interfaces it is to implement.  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 [http://trac.edgewall.org/wiki/TracDev/ComponentArchitecture component] are generated by looking through the chosen 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.

== Bugs/Feature Requests == 

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

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=CreatePluginScript&owner=k0s new ticket].

== Download ==

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

If you just want {{{create_component.py}}} go [http://trac-hacks.org/svn/createpluginscript/anyrelease/create_trac_plugin/create_component.py here].

== Source ==

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

== Example ==

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

{{{
$ 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:

{{{
$ 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:

{{{
"""
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}}}):

{{{
$ create-trac-component NewPlugin ITemplateStreamFilter IWikiSyntaxProvider
}}}

== Recent Changes ==

[[ChangeLog(createpluginscript, 3)]]

== Author/Contributors ==

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

'''Author:''' [wiki:k0s] [[BR]]
'''Contributors:'''