wiki:ScreenshotsPlugin

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 the timeline and screenshots can be referenced or embedded in wiki pages. The plugin internally defines few interfaces for further extension.

The plugin is perfectly able to be used as a picture archive for the wiki pages.

See also: ScreenshotPastePlugin

Bugs/Feature Requests

Check existing bugs and feature requests first, please. If you have additional issues, you are welcome to ask at our mailing-list to confirm proper local install and configuration. Please create a new ticket, if you're reasonably sure, that it will be a valid defect report or a generally useful enhancement that follows BugReporting recommendations.

defect

44 / 45

enhancement

21 / 21

task

0 / 1

Download and Source

Download the zipped source, check out using Subversion, or browse the source with Trac.

Dependencies

You need to have the Python Imaging Library installed to get the plugin working. Plugin optionally depends on TracTags plugin for screenshot tagging support.

Installation

Install the plugin egg. Set the variables in the [screenshots] section of your trac.ini configuration file according to your needs:

OptionDescriptionDefault 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 and 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 trac.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:

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 <path_to_environment> upgrade

Permissions

Screenshots plugin defines four 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:

PermissionDescription
SCREENSHOTS_ADDpermission to upload screenshots
SCREENSHOTS_ADMINpermission to upload, delete, view, filter and order screenshots
SCREENSHOTS_DELETEpermission to delete screenshots
SCREENSHOTS_FILTERallows to modify component and version filter
SCREENSHOTS_ORDERpermits to change the order they are displayed in
SCREENSHOTS_VIEWpermits 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 WebAdminPlugin to do it for you:

trac-admin <path_to_environment> permission add <user> SCREENSHOTS_ADMIN
trac-admin <path_to_environment> permission add <user> SCREENSHOTS_ADD
trac-admin <path_to_environment> permission add <user> SCREENSHOTS_DELETE
trac-admin <path_to_environment> permission add <user> SCREENSHOTS_FILTER
trac-admin <path_to_environment> permission add <user> SCREENSHOTS_ORDER
trac-admin <path_to_environment> permission add <user> SCREENSHOTS_VIEW

Macros

The macro [screenshot:<screenshot_id>] can be used for screenshots referencing.

For screenshot embedding in wiki page use [[Screenshot(<screenshot_id>, [<attribute>=<value>, ...])]]. 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 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 imgmap.

[[ScreenshotsList()]] macro displays list of all available screenshots on wiki page. Accepts one argument which is template for list items formatting. 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 comma separated list so change this to prevent inconveniences.

Feedback

Are you using this plugin?
  • Yes, it's usefull. (sgrayban, cboos, okaori, wadeb, s0undt3ch, ttressieres, imme, dh1jc, talameelombu, Tharban, athomas, jtuchscherer, xvirus, osimons, Sincklation, manni, izzy, ericalens, KevinGabbert, mwehr, renzo, marcvs, eskil, rjollos, koolhand, edo, colski, dfleming, lucasrangit, miezuit, lhr870630, hasienda, arnisandy, lucid, AdrianFritz, akliewer99, AmigaAbattoir)
  • No, it's useless.
  • No, I don't need it. (dfaerch, harmy, prz)

  • You don't have permission to vote. You may need to login.

About i18n/l10n support

The 0.12 branch of this plugin is prepared for localization.
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 Trac plugin l10n project at Transifex or
  2. do it yourself, see the 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 Trac plugin l10n project via Transifex:

Top translations: Trac_Plugin-L10N » tracscreenshots

http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/tracscreenshots/chart/image_png

Kindly provided by https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.png

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:

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 l10n cookbook page for Trac plugins.

Change Log

[13303] by hasienda on 2013-06-23 15:10:27
ScreenshotsPlugin: Use own actions instead of 'WIKI_*' for tagging action permission checks, closes #10940.

Fixing the issue for the two most current branches simultaneously.

[12139] by rjollos on 2012-10-10 03:54:13
Fixed incorrect source code encoding (http://www.python.org/dev/peps/pep-0263/).
[8987] by Blackhex on 2010-09-20 14:56:24

ScreenshotsPlugin:

  • Fixing #7701 and other PosgreSQL related problems.
  • Trac 0.11.5 dependency for 0.11 branch added.

Author/Contributors

Author: Blackhex
Maintainer: none (needsadoption)
Contributors: hasienda

Last modified 5 weeks ago Last modified on Apr 2, 2015, 1:54:10 PM

Attachments (1)

Download all attachments as: .zip