= Screenshots Plugin = == Description == Provides screenshots upload and viewing subsystem for Trac. Uploaded screenshots can be described with short name, longer description and custom tags (if TracTags plugin is installed) and assigned to any number of components and versions registered in Trac. Screenshot uploads can be listed in timeline and screenshots can be referenced or embender in wiki pages. Plugin internally defines few interfaces for further extension. == Bugs/Feature Requests == Existing bugs and feature requests for ScreenshotsPlugin are [query:?status=new&status=assigned&status=reopened&group=&component=ScreenshotsPlugin&order=priority here]. If you have any issues, create a [http://trac-hacks.org/newticket?component=ScreenshotsPlugin&owner=Blackhex new ticket] but read BugReporting page first, please. == Download and Source == Download the [download:screenshotsplugin zipped source], check out [/svn/screenshotsplugin using Subversion], or [source:screenshotsplugin browse the source] with Trac. == Dependencies == You need to have [http://pythonware.com/products/pil/ PIL] library installed to get plugin working. Plugin optionally depends on TracTags plugin for screenshot tagging support. == Installation == Install plugin's egg and set variables in trac.ini configuration file according to your needs. Following list shows all of them with their default values: {{{ [screenshots] mainnav_title = Screenshots metanav_title = path = /var/lib/trac/screenshots ext = jpg,png formats = raw,html,jpg,png default_format = html default_components = none default_versions = none }}} Value of {{{mainnav_title}}} variable sets caption of item in Trac's main navigation menu and {{{metanav_title}}} sets caption of meta navigation menu item. Appropriate item will be hidden if its title is empty. {{{path}}} is location of directory where plugin should store uploaded and generated images and {{{ext}}} is list of allowed file extension which can be uploaded. Using {{{formats}}} option you can set in wich formats can be images downloaded and {{{default_format}}} is format which will be returned if no format is specified in request. It must be one of formats supported by your PIL library installation. There are two meta formats: {{{raw}}} denotes original format of uploaded image and {{{html}}} is image embended in HTML page. {{{default_components}}} and {{{default_versions}}} options sets default values for component and version filter. Set these variables according your Trac setup, otherwise, you would't see any screenshots with default filter. If you run Trac in environment which needs to enable plugins explicitly put in trac.ini these lines: {{{ [components] TracScreenshots.init.ScreenshotsInit = enabled TracScreenshots.core.ScreenshotsCore = enabled TracScreenshots.api.ScreenshotsApi = enabled TracScreenshots.wiki.ScreenshotsWiki = enabled TracScreenshots.timeline.ScreenshotsTimeline = enabled # For 0.11 branch. TracScreenshots.tags.ScreenshotsTags = enabled }}} If you don't have TagsPlugin installed replace last line with {{{ tracscreenshots.tags.screenshotstags = disabled }}} Create directory you have specified with {{{path}}} config option and make sure it is accessible by Trac server. The next step is to upgrade your environment: {{{ # trac-admin upgrade }}} == Permissions == Screenshots plugin defines three permissions. With SCREENSHOTS_VIEW permission you can browse screenshots and see screenshot uploads in timeline. SCREENSHOTS_ADMIN adds you rights to upload screenshots and SCREENSHOTS_FILTER allows you to modify component and version filter. ''If you use apache, please restart it, before setting permissions.'' You can add these permissions by typing following commands from commandline or you can use WebAdminPlugin to do it for you: {{{ # trac-admin permission add SCREENSHOTS_VIEW # trac-admin permission add SCREENSHOTS_ADMIN # trac-admin permission add SCREENSHOTS_FILTER }}} == Macros == There is a macro {{{[screenshot:]}}} for screenshots referencing. For screenshot embending in wiki page use {{{[[Screenshot(, [=, ...])]]}}}. First mandatory argument is ID of the screenshot. Number or image attributes can be specified next. This is a list of them: * {{{align}}} - Specifies image alignment in wiki page. Possible values are: {{{left}}}, {{{right}}} and {{{center}}}. * {{{alt}}} - Alternative description of image. * {{{border}}} - Sets image border of specified width in pixels. * {{{class}}} - Class of image for CSS styling. * {{{description}}} - Brief description under the image. Accepts several variables (see bellow). * {{{format}}} - Format of returned image or screenshot behind link. * {{{height}}} - Height of image. Set to 0 if you want original image height. * {{{id}}} - ID of image for CSS styling. * {{{longdesc}}} - Detailed description of image. * {{{title}}} - Title of image. * {{{usemap}}} - Image map for clickable images. * {{{width}}} - Width of image. Set to 0 if you want original image width. Attribute {{{description}}} displays several variables: * {{{$id}}} - ID of image. * {{{$name}}} - Name of image. * {{{$author}}} - User name who uploaded image. * {{{$time}}} - Time when image was uploaded. * {{{$file}}} - File name of image. * {{{$description}}} - Detailed description of image. * {{{$width}}} - Original width of image. * {{{$height}}} - Original height of image. * {{{$tags}}} - Comma separated list of screenshot tags. * {{{$components}}} - Comma separated list of screenshot components. * {{{$versions}}} - Comma separated list of screenshot versions. Example: {{{ [[Screenshot(2,width=400,height=300,description=The $name by $author: $description,align=left)]] }}} For creating image maps you might consider using tools like http://www.maschek.hu/imagemap/imgmap. {{{[[ScreenshotsList()]]}}} macro displays list of all available screenshots on wiki page. Accepts one argument which is template for list items fromatting. Possible variables in this template are: * {{{$id}}} - ID of image. * {{{$name}}} - Name of image. * {{{$author}}} - User name who uploaded image. * {{{$time}}} - Time when image was uploaded. * {{{$file}}} - File name of image. * {{{$description}}} - Detailed description of image. * {{{$width}}} - Original width of image. * {{{$height}}} - Original height of image. * {{{$tags}}} - Comma separated list of screenshot tags. * {{{$components}}} - Comma separated list of screenshot components. * {{{$versions}}} - Comma separated list of screenshot versions. Example: {{{ [[ScreenshotsList($name - $description ($widthx$height))]] }}} == Notes == Previous revisions used space separated list of values in {{{trac.ini}}} configuration options. Now it uses comma separated list so change this to prevent inconveniences. == Feedback == [[Poll(Are you using this plugin?; Yes, it's usefull.; No, it's useless.; No, I don't need it.)]] == Change Log == [[ChangeLog(/screenshotsplugin, 5)]] == Author/Contributors == '''Author:''' [wiki:Blackhex] [[BR]] '''Contributors:'''