= インタフェースのリファレンス =
Tracは、[wiki:TracDoc/ComponentArhitectureJa ComponentArchitecture]に基づき多くのインタフェースをプラグイン開発者に提供しています。[[BR]]
が、資料はほとんどないので、ここにまとめてみました。

== インタフェース一覧 ==
0.10で若干インタフェースが増えてるようです。

||パッケージ||インタフェース||0.9||0.10||説明||
||trac.db.api||[wiki:TracDoc/Interface#IDatabaseConnector IDatabaseConnector]||×||○||DBを変更するためのインタフェース？||
||trac.mimeview.api||[wiki:TracDoc/Interface#IHTMLPreviewRenderer IHTMLPreviewRenderer]||○||○||リポジトリブラウザでHTMLを表示するためのインタフェース||
||trac.mimeview.api||[wiki:TracDoc/Interface#IHTMLPreviewAnnotator IHTMLPreviewAnnotator]||○||○||リポジトリブラウザで付加情報を表示するためのインタフェース||
||trac.tests.core||ITest||×||○||
||trac.ticket.api||ITicketChangeListener||×||○||
||trac.ticket.api||ITicketManipulator||×||○||
||trac.versioncontrol.api||IRepositoryConnector||×||○||
||trac.web.api||IAuthenticator||○||○||
||trac.web.api||IRequestHandler||○||○||
||trac.web.chrome||INavigationContributor||○||○||
||trac.web.chrome||ITemplateProvider||○||○||
||trac.wiki.api||IWikiChangeListener||○||○||
||trac.wiki.api||IWikiPageManipulator||×||○||
||trac.wiki.api||IWikiMacroProvider||○||○||
||trac.wiki.api||IWikiSyntaxProvider||○||○||
||trac.env||IEnvironmentSetupParticipant||○||○||
||trac.perm||IPermissionRequestor||○||○||
||trac.perm||IPermissionStore||○||○||
||trac.perm||IPermissionGroupProvider||○||○||
||trac.Search||ISearchSource||○||○||
||trac.Timeline||ITimelineEventProvider||○||○||

== リファレンス ==
=== IDatabaseConnector ===
Trac 0.10以降。DB接続先を変えるためのインタフェースみたいです。
{{{
#!python
class IDatabaseConnector(Interface):
    """Extension point interface for components that support the connection to
    relational databases."""

    def get_supported_schemes():
        """Return the connection URL schemes supported by the connector, and
        their relative priorities as an iterable of `(scheme, priority)` tuples.
        """

    def get_connection(**kwargs):
        """Create a new connection to the database."""
        
    def init_db(**kwargs):
        """Initialize the database."""

    def to_sql(table):
        """Return the DDL statements necessary to create the specified table,
        including indices."""
}}}
=== IHTMLPreviewRenderer ===
リポジトリブラウザで、MimeTypeに紐づくHTMLを出力するためのインタフェース。
特定のMimeTypeに対して、リポジトリブラウザでデータを見せたいときにこれを使います。
{{{
class IHTMLPreviewRenderer(Interface):
    """Extension point interface for components that add HTML renderers of
    specific content types to the `Mimeview` component.
    """

    # implementing classes should set this property to True if they
    # support text content where Trac should expand tabs into spaces
    expand_tabs = False

    def get_quality_ratio(mimetype):
        """Return the level of support this renderer provides for the `content`
        of the specified MIME type. The return value must be a number between
        0 and 9, where 0 means no support and 9 means "perfect" support.
        """

    def render(req, mimetype, content, filename=None, url=None):
        """Render an XHTML preview of the raw `content`.

        The `content` might be:
         * a `str` object
         * an `unicode` string
         * any object with a `read` method, returning one of the above

        It is assumed that the content will correspond to the given `mimetype`.

        Besides the `content` value, the same content may eventually
        be available through the `filename` or `url` parameters.
        This is useful for renderers that embed objects, using <object> or
        <img> instead of including the content inline.
        
        Can return the generated XHTML text as a single string or as an
        iterable that yields strings. In the latter case, the list will
        be considered to correspond to lines of text in the original content.
        """
}}}
サンプル：
source:/trunk/xdocviewplugin/xdocview/xdocview.py@36
=== IHTMLPreviewAnnotator ===
IHTMLPreviewRendererと似てますが、これは付加情報をXHTMLで表示するためのものみたい？使ってるのは見たことありません。
{{{
class IHTMLPreviewAnnotator(Interface):
    """Extension point interface for components that can annotate an XHTML
    representation of file contents with additional information."""

    def get_annotation_type():
        """Return a (type, label, description) tuple that defines the type of
        annotation and provides human readable names. The `type` element should
        be unique to the annotator. The `label` element is used as column
        heading for the table, while `description` is used as a display name to
        let the user toggle the appearance of the annotation type.
        """

    def annotate_line(number, content):
        """Return the XHTML markup for the table cell that contains the
        annotation data."""
}}}

=== ITicketChangeListener ===
Ver0.10以降。
チケットの変更時に呼び出されるインタフェース。作成時、変更時、削除（削除ってあったっけ？）時にそれぞれ
呼び出されるメソッドを定義する。
{{{
#!python
class ITicketChangeListener(Interface):
    """Extension point interface for components that require notification when
    tickets are created, modified, or deleted."""

    def ticket_created(ticket):
        """Called when a ticket is created."""

    def ticket_changed(ticket, comment, old_values):
        """Called when a ticket is modified.
        
        `old_values` is a dictionary containing the previous values of the
        fields that have changed.
        """

    def ticket_deleted(ticket):
        """Called when a ticket is deleted."""
}}}
=== ITicketManipulator ===
Ver0.10以降。
チケットの登録時に呼び出されるインタフェース。値のチェックを行うのに使う。
{{{
#!python
class ITicketManipulator(Interface):
    """Miscellaneous manipulation of ticket workflow features."""

    def prepare_ticket(req, ticket, fields, actions):
        """Not currently called, but should be provided for future
        compatibility."""

    def validate_ticket(req, ticket):
        """Validate a ticket after it's been populated from user input.
        
        Must return a list of `(field, message)` tuples, one for each problem
        detected. `field` can be `None` to indicate an overall problem with the
        ticket. Therefore, a return value of `[]` means everything is OK."""
}}}
=== IRepositoryConnector ===
Ver0.10以降。
SVN以外のバージョン管理システムを使うためのインタフェース。
{{{
#!python
class IRepositoryConnector(Interface):
    """Extension point interface for components that provide support for a
    specific version control system."""

    def get_supported_types():
        """Return the types of version control systems that are supported by
        this connector, and their relative priorities.
        
        Highest number is highest priority.
        """

    def get_repository(repos_type, repos_dir, authname):
        """Return the Repository object for the given repository type and
        directory.
        """
}}}
=== IAuthenticator ===

{{{
#!python
class IAuthenticator(Interface):
    """Extension point interface for components that can provide the name
    of the remote user."""

    def authenticate(req):
        """Return the name of the remote user, or `None` if the identity of the
        user is unknown."""
}}}
=== IRequestHandler ===
リクエストハンドラ。リクエストを処理する場合に使う。っていうかメニューにアイテムを作ったら
まず間違いなく使う。いろんなモジュールが使っているので参照すればだいたい分かる。
{{{
#!python
class IRequestHandler(Interface):
    """Extension point interface for request handlers."""

    # implementing classes should set this property to `True` if they
    # don't need session and authentication related information
    anonymous_request = False
    
    # implementing classes should set this property to `False` if they
    # don't need the HDF data and don't produce content using a template
    use_template = True
    
    def match_request(req):
        """Return whether the handler wants to process the given request."""

    def process_request(req):
        """Process the request. Should return a (template_name, content_type)
        tuple, where `template` is the ClearSilver template to use (either
        a `neo_cs.CS` object, or the file name of the template), and
        `content_type` is the MIME type of the content. If `content_type` is
        `None`, "text/html" is assumed.

        Note that if template processing should not occur, this method can
        simply send the response itself and not return anything.
        """
}}}
=== INavigationContributor ===
メニューバーにアイテムを出すときに使う。これも多くのコンポーネントで使われている。
{{{
#!python
class INavigationContributor(Interface):
    """Extension point interface for components that contribute items to the
    navigation.
    """

    def get_active_navigation_item(req):
        """This method is only called for the `IRequestHandler` processing the
        request.
        
        It should return the name of the navigation item that should be
        highlighted as active/current.
        """

    def get_navigation_items(req):
        """Should return an iterable object over the list of navigation items to
        add, each being a tuple in the form (category, name, text).
        """
}}}
=== ITemplateProvider ===
ClearSilverテンプレートから、静的なコンテンツ（画像とか）を呼びたい場合に使う。
{{{
#!python
class ITemplateProvider(Interface):
    """Extension point interface for components that provide their own
    ClearSilver templates and accompanying static resources.
    """

    def get_htdocs_dirs():
        """Return a list of directories with static resources (such as style
        sheets, images, etc.)

        Each item in the list must be a `(prefix, abspath)` tuple. The
        `prefix` part defines the path in the URL that requests to these
        resources are prefixed with.
        
        The `abspath` is the absolute path to the directory containing the
        resources on the local file system.
        """
}}}