Contents
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 embedded in wiki pages. Plugin internally defines few interfaces for further extension.
The name is a little misleading as of course it is perfectly able to be used as a picture archive for the wiki pages.
Donations
If you want to support plugin's development, you can donate some small amount via PayPal. If you specify particular feature, you want to support, in the note field, the donation will be used on that feature.
Any donation will be gratefully welcomed.
Bugs/Feature Requests
Existing bugs and feature requests for ScreenshotsPlugin are here.
If you have any issues, create a new ticket but read BugReporting page first, please.
Download and Source
Download the zipped source, check out using Subversion, or browse the source with Trac.
Dependencies
You need to have PIL library installed to get plugin working. Plugin optionally depends on TracTags plugin for screenshot tagging support.
Installation
Install plugins egg and set variables in the [screenshots] section of your trac.ini configuration file according to your needs. Following list shows all of them with a description and their default values:
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 PIL 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 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.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 one present component for actual screenshots display although there are internaly defined interfaces so any other component with different view can be introduced in the future.
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 <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):
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 | allows to modify component and version filter |
SCREENSHOTS_ORDER | permits to change the order they are displayed in |
SCREENSHOTS_VIEW | permits 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 following commands from commandline 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
There is a macro [screenshot:<screenshot_id>] for screenshots referencing.
For screenshot embedding in wiki page use [[Screenshot(<screenshot_id>, [<attribute>=<value>, ...])]]. 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 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 trac.ini configuration options. Now it uses comma separated list so change this to prevent inconveniences.
Feedback
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
- look, if it's already available from the Trac plugin l10n project at Transifex or
- do it yourself (see the l10n cookbook page for Trac plugins for more details).
You've done a new translation? Superb! 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
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
[12139] by rjollos on 10/10/12 03:54:13
Fixed incorrect source code encoding (http://www.python.org/dev/peps/pep-0263/).
[8987] by Blackhex on 09/20/10 14:56:24
- Fixing #7701 and other PosgreSQL related problems.
- Trac 0.11.5 dependency for 0.11 branch added.
[8717] by Blackhex on 09/09/10 09:44:05
- Translated to Czech language.
[8708] by hasienda on 09/08/10 23:37:04
ScreenshotsPlugin: Add clean Czech message catalog, this time for real.
File was already announced but left out from changeset [8690].
[8690] by hasienda on 09/08/10 14:54:13
ScreenshotsPlugin: Extract translatable messages creating first catalog template.
There are even preliminary German translations, that need to get completed and empty Czech catalog to start translation work right away.
[8689] by hasienda on 09/08/10 14:48:29
ScreenshotsPlugin: Add basic code and markup for i18n support.
Again reviewed by Radek Bartoň, who added the ingenious, original translation module import to template files. Bumping version, since this is going to be backwards-incompatible anyway. And we'll aim at translated doc-strings for all registered configuration options; 1st time I see this one, let's see, how/where this works.
Author/Contributors
Author: Blackhex
Maintainer: Blackhex
Contributors: hasienda
Attachments
- tracscreenshots-0.1.jpg (95.8 kB) -
Screenshot of early version 0.1
, added by Blackhex on 08/01/06 12:44:55.