[[PageOutline(2-5,Contents,pullout)]] = Manage images and screenshots in Trac == Description This plugin provides a screenshots upload and viewing facility 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 the timeline and screenshots can be referenced or embedded in Trac wiki pages. The plugin internally defines few interfaces for further extension. The plugin can also be used as a picture archive for the wiki pages. See also: ScreenshotPastePlugin == Bugs/Feature Requests Existing bugs and feature requests for ScreenshotsPlugin are [report:9?COMPONENT=ScreenshotsPlugin here]. If you have any issues, create a [/newticket?component=ScreenshotsPlugin new ticket]. [[TicketQuery(component=ScreenshotsPlugin&group=type,format=progress)]] == Download Download the zipped source from [export:screenshotsplugin zipped here]. == Source Check out ScreenshotsPlugin from [/svn/screenshotsplugin here] using Subversion, or [source:screenshotsplugin browse the source] with Trac. == Installation '''Dependencies''': * [pypi:pillow Python Imaging Library]. * Optional: TracTags plugin for screenshot tagging support. Install the plugin egg. Set the variables in the {{{[screenshots]}}} section of your {{{trac.ini}}} configuration file according to your needs: ||'''Option'''||'''Description'''||'''Default Value'''|| ||additional_tags|| what additional screenshot attributes will be inserted as tags || author,components,versions,name || ||default_components|| default values for component filter || all || ||default_description|| description attached to the screenshot if not explicitly specified in request || $description || ||default_filter_relation|| how the filters should be related by default || or || ||default_format|| format which will be returned if no format is specified in request (see ''formats'' below) || html || ||default_list_item|| how the {{{[[ScreenshotsList]]}}} macro should be expanded by default || $id - $name - $description || ||default_order_directions|| whether to start with the first or last item by default || asc || ||default_orders|| if not specified otherwise, by which criteria should we order? || id || ||default_versions|| default values for version filter || all || ||ext|| list of allowed file extension which can be uploaded || jpg,png || ||formats|| in which formats images can be downloaded || raw,html,jpg,png || ||mainnav_title|| caption in Tracs main navigation menu (empty = hide item)|| Screenshots || ||metanav_title|| caption in Tracs meta navigation menu (empty = hide item) || || ||path|| location of directory where plugin should store uploaded and generated images || /var/lib/trac/screenshots || {{{default_format}}} and {{{formats}}} must be supported by your Python Imaging Library installation. There are two meta formats: * {{{raw}}} denotes original format of uploaded image * {{{html}}} is image embedded in HTML page. {{{ext}}} can also include the {{{zip}}} extension, which is not included by default for security reasons. If a {{{zip}}} file containing multiple images is uploaded, all of the images applying to the other extensions specified by {{{ext}}} will be added with the same metadata entered for the {{{zip}}} file, and the {{{zip}}} file itself will be abandoned. {{{default_components}}} and {{{default_versions}}} options sets default values for component and version filter. Another possible value for {{{additional_tags}}} except of those listed as default is {{{description}}}. If you run Trac in an environment which needs to enable plugins explicitly, put these lines in your `trac.ini` file: {{{#!ini [components] TracScreenshots.init.ScreenshotsInit = enabled TracScreenshots.core.ScreenshotsCore = enabled TracScreenshots.api.ScreenshotsApi = enabled TracScreenshots.matrix_view.ScreenshotsMatrixView = enabled TracScreenshots.tags.ScreenshotsMatrixView = enabled TracScreenshots.wiki.ScreenshotsWiki = enabled TracScreenshots.timeline.ScreenshotsTimeline = enabled # For 0.11 branch. TracScreenshots.tags.ScreenshotsTags = enabled }}} {{{ScreenshotMatrixView}}} is currently the only component for actual screenshots display, although there are internally defined interfaces, so any other component with a different view can be introduced in the future. If you don't have TagsPlugin installed, then replace the last line with: {{{#!ini tracscreenshots.tags.screenshotstags = disabled }}} Create a directory you have specified with {{{path}}} config option and make sure it is accessible by your Trac server. The next step is to upgrade your environment: {{{#!sh trac-admin upgrade }}} == Permissions This plugin defines the following permissions, each one in this list depends on the one mentioned before it, and adds its permissions upon that, with `SCREENSHOTS_FILTER` and `SCREENSHOTS_ORDER` being on the same level: ||'''Permission'''||'''Description'''|| ||SCREENSHOTS_ADD||permission to upload screenshots|| ||SCREENSHOTS_ADMIN||permission to upload, delete, view, filter and order screenshots|| ||SCREENSHOTS_DELETE||permission to delete screenshots|| ||SCREENSHOTS_FILTER||permission to modify component and version filter|| ||SCREENSHOTS_ORDER||permission to change the order they are displayed in|| ||SCREENSHOTS_VIEW||permission to browse screenshots and see screenshot uploads in timeline|| If you use Apache, please restart it before setting permissions. You can add these permissions by typing the following commands from the command line or you can use the Web admin interface to do it for you: {{{#!sh trac-admin permission add SCREENSHOTS_ADMIN trac-admin permission add SCREENSHOTS_ADD trac-admin permission add SCREENSHOTS_DELETE trac-admin permission add SCREENSHOTS_FILTER trac-admin permission add SCREENSHOTS_ORDER trac-admin permission add SCREENSHOTS_VIEW }}} == Macros The macro {{{[screenshot:]}}} can be used for screenshots referencing. For screenshot embedding in wiki page use {{{[[Screenshot(, [=, ...])]]}}}. First argument is the ID of the screenshot and is mandatory. The following image attributes can then optionally be specified: * {{{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 below). * {{{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 may want to consider using tools like [http://www.maschek.hu/imagemap/imgmap imgmap], which itself is dual licensed: Commercial and GPL. {{{[[ScreenshotsList()]]}}} macro displays a list of all available screenshots on the wiki page. It accepts one argument, which is the template for list items formatting. The 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 the `trac.ini` configuration options. Now it uses a comma separated list, so change this to prevent inconveniences. == About i18n/l10n support The 0.12 branch of this plugin is prepared for localization.[[BR]] But English message texts are still the (POSIX) default. If this isn't your preferred language, you can 1. check if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracscreenshots Transifex] or 2. do it yourself, see the [t:wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details. Contributing your translation is highly appreciated. You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project] via [https://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]: Top translations: Trac_Plugin-L10N ยป [https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracscreenshots/ tracscreenshots][[BR]] [[Image(https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracscreenshots/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=https://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracscreenshots/)]] Kindly provided by [[Image(https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]] Preparing the plugin from source requires the additional step of compiling message catalog files. This will be done automatically by invoking a suitable Babel install. Walk through: {{{#!sh cd tracscreenshots python ./setup.py compile_catalog -f python ./setup.py bdist_egg }}} Step 2 is almost obsolete, and only needed to include translations marked as `# fuzzy` by the translator, since the compilation before packaging will do message catalog compilation compile only without the extra `-f` argument. Again, for more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins]. == Change Log [[ChangeLog(/screenshotsplugin, 3)]] == Author/Contributors '''Author:''' [wiki:Blackhex] [[BR]] '''Maintainer:''' [[Maintainer]] [[BR]] '''Contributors:''' [wiki:hasienda] [[BR]]