== Extension Point : ''ILegacyAttachmentPolicyDelegate'' ==

||'''Interface'''||''ILegacyAttachmentPolicyDelegate''||'''Since'''||[wiki:TracDev/ApiChanges/0.11#ILegacyAttachmentDelegate 0.11]||
||'''Module'''||''trac.attachment''||'''Source'''||[source:trunk/trac/attachment.py#/ILegacyAttachmentPolicyDelegate attachment.py]||

The ''ILegacyAttachmentPolicyDelegate'' implementations define how to check for `ATTACHMENT_*` permissions for different realms.

== Purpose ==

The TracPermissions system defines coarse permissions to control which users have access to which modules. TracFineGrainedPermissions introduced more fine grained control over permissions for individual resources. The [wiki:trac.perm.IPermissionPolicy IPermissionPolicy] interface is used to implement this new system, re-implement the legacy behavior and allow plugins to extend the permission policies.

Attachment permissions are not really separate permissions and can not e.g. be specified in the Admin interface. `LegacyAttachmentPolicy` (a `IPermissionPolicy` implementation) handles the legacy attachment permissions `ATTACHMENT_CREATE`, `ATTACHMENT_VIEW` and `ATTACHMENT_DELETE`. For the ''ticket'', ''wiki'' and ''milestone'' realms, it maps them directly to `TICKET_*`, `WIKI_*` and `MILESTONE_*` permissions on the parent resource. Attachments are child resources, and this delegates attachment permissions to their parent resources'. (E.g., if a user has the permission to modify a page, that user can also attach a file; permission to delete a page also gives permission to delete an attachment, etc.)

Plugins that implement other resource realms and also support attachments can implement the `ILegacyAttachmentPolicyDelegate` interface. This allows extending `LegacyAttachmentPolicy` with similar mappings.

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].

`ILegacyAttachmentPolicyDelegate` implementations are only used if the `LegacyAttachmentPolicy` is listed in the ''permission_policies'' configured in [wiki:TracIni#trac-section trac.ini].

These policies are called for user actions on a attachments. They can explicitly allow or deny these action, or abstain to defer the check to the next policy in the chain. For attachments to realms other than ''ticket'', ''wiki'' or ''milestone'', the `LegacyAttachmentPolicy` will defer to `ILegacyAttachmentPolicyDelegate` implementations.

== Examples ==

A minimal ILegacyAttachmentPolicyDelegate in isolation is not very useful (but possible) and usually accompanied by implementations of other interfaces that request and require these permissions. Hence the following example is best understood in context of the ComponentModuleExamples.

In Trac components have no attachments. One could extend the ComponentModuleExamples to implement support for such attachments. The following example maps attachment permissions to component and ticket admin permissions:

{{{#!python
from trac.core import Component, implements
from trac.attachment import ILegacyAttachmentPolicyDelegate

class ComponentModule(Component):
    implements(ILegacyAttachmentPolicyDelegate)

    def check_attachment_permission(self, action, username, resource, perm):
        if resource.parent.realm == 'component':
            if action == 'ATTACHMENT_VIEW':
                return 'COMPONENT_VIEW' in perm(resource.parent)
            elif action in ('ATTACHMENT_CREATE','ATTACHMENT_DELETE'): 
                return 'TICKET_ADMIN' in perm(resource.parent)
}}}

== Available Implementations ==

||= Plugin =||= maps attachment permissions to =||= for attachments to resources of realm =||= Notes =||
|| [https://malept.com/projects/trac-atompub.html AtomPub Plugin] || `ATOM_*` || `atompub` || ||
|| [bitten:WikiStart Bitten] || `BUILD_*` || `build` || ||
|| th:ExoWebCodeReviewPlugin || `CODE_REVIEW_*` || `CodeReview` || ||
|| th:FullBlogPlugin || `BLOG_*` || `blog` || Performs some additional logic. ||
|| [https://code.google.com/p/tracmailarchiveextplugin/ MailArchiveExtPlugin] || `MAILARCHIVE_*` || `mailarchive` || ||
|| [https://www.coderesort.com/p/open/wiki/TracTalkPlugin TracTalkPlugin] || `TALK_*` || `talk` || ||
|| [https://code.google.com/p/trac-testmanagement-plugin/ trac-testmanagement-plugin] || `TEST_*` || `test` || ||
|| th:ExtendedVersionPlugin || `VERSION_*` || `version` || ||
|| th:DiscussionPlugin || `DISCUSSION_ATTACH` || `discussion` || ||

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.attachment.ILegacyAttachmentPolicyDelegate-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_attachment.html#trac.attachment.ILegacyAttachmentPolicyDelegate API Reference]
 * See [wiki:trac.perm.IPermissionPolicy IPermissionPolicy]
 * Initial development: [Trac-Dev:2783 mailing list archive]
 * Related tickets:
  * [query:status!=closed&component=attachment attachment component]
 * This interface is sometimes referred to as `ILegacyAttachmentDelegate` by mistake.
 * Why ''Legacy''?
   * The idea was that this mechanism would no longer be necessary once it becomes easier to setup fine-grained permissions in the default permission store.