This plugin provides a reusable image viewer component based on Leaflet.
The grails2 branch contains the 0.8.x series of the plugin compatible with Grails 2.x
The grails3 branch hosts version 1.x and forward of the plugin compatible with grails 3.x
The master branch contains the 1.4.x series of the plugin compatible with Grails 4.12
compile "au.org.ala.plugins.grails:images-client-plugin:1.0", noCache
The image-viewer resources module need to be added to the page where we want to use the viewer. Eg using the Asset Pipeline plugin:
<asset:javascript src="ala/images-client.js"/>
<asset:stylesheet src="ala/images-client.css" />❗ This will create a viewer instance in the document global scope called imgvwr.
imageId as per the images.ala.org.au service and the id of the <div> element that will contain the viewer as parameters of the viewImage method. Eg:
imgvwr.viewImage($("#viewerContainerId"), imageId, {custom options...});
| Option | Default | Description |
|---|---|---|
| imageServiceBaseUrl | 'http://images.ala.org.au' | URL where the images service is located |
| imageClientUrl | '' | Context path of the app using the plugin e.g. "/specimenbrowser". Required for using calibration and subimaging controls. |
| auxDataUrl | N/A | A URL to a JSON webservice that provides key/value pairs to be rendered in the information popup |
| auxDataTitle | N/A | Default value is 'View more information about this image'. A |
| initialZoom | 'auto' | number with the initial zoom level. When set to 'auto' the most suitable zoom level for the viewer container size will be automatically calculated. |
| addDownloadButton | true | Shows the image download button control. |
| addDrawer | true | Add the rectangle draw tool |
| addSubImageToggle | true | Add the "show subimages" button |
| addCalibration | true | Add the calibration tools |
| addImageInfo | true | Shows button control with link to the image info page. |
| addLoading | true | Displays an unobtrusive loading indicator when tiles are loading or when other data is loading. |
| addCloseButton | false | Add a control to dismiss bootstrap modal dialog. |
| addAttribution | false | Add a control to show image attribution. The text to show is passed on 'attribution' option. |
| attribution | '' | Text to show on attribution control. Make sure 'addAttribution' option is switched on. |
| addPreferenceButton | false | Disabled if user role is not part of the configured role list in config file. allowedImageEditingRoles= |
| addLikeDislikeButton | false | Add button to up and down vote and a help button. |
| disableLikeDislikeButton | false | Disable up and down vote buttons when user is not logged in. |
| likeUrl | '' | Url to call when a user up vote an image. |
| dislikeUrl | '' | Url to call when a user down vote an image. |
| userRatingUrl | '' | Url to call to get the current voting on an image. |
| userRatingHelpText | '' | Text to display when help button is clicked. |
| galleryOptions | {...} | Check the gallery component documentation bellow 👇 |
| Method | Description |
|---|---|
| viewImage(targetDiv, imageId, scientificName, guid, options) | targetDiv has to be wrapped in a jQuery selector. |
| resizeViewer(targetDiv) | required when viewer container is initially hidden or its size changes. |
| removeCurrentImage() | Removes current image layer. Use case example: when reuisng viewer instance in a popup you don't want the previous image to show up while the image you have requested is being loaded. |
| getViewerInstance() | Provides the leaflet map/image viewer instance in case you need to perform some customizations. |
| get/setImageClientBaseUrl(url) | get/set imageClientUrl property |
| get/setImageServiceBaseUrl(url) | get/set imageServiceBaseUrl property |
| other | There some other public methods that I am not sure they are used. Check source code for more details: ala-image-viewer.js. |
This component converts our viewer component into an fully feature image gallery where you can easily switch between a given set of images that are conveniently presented as thumbnails in an image carousel sitting bellow our already familiar zoomable image viewer. You might be able to picture it better in the following screenshot:
The thumbnail carousel is actually a slighltly modified implementation of the SliderPro component. These are some of the features it provides around this use case:
- Responsive layout that automatically adjust to available width.
- Thumbnail automatically resized/cropped so all have the same size.
- High level of accessibility due to keyboard support.
- Touch/Swipe friendly for mobile devices.
To create the image gallery we need to position the viewer and the thumbnail carousel in out page. The embedded style sheet support the following HTML layout by default:
<div class="img-gallery">
<div id="imageViewer"></div>
<div id="carousel" class="slider-pro">
<div class="sp-slides thumbnails" style="display: none;">
<g:each in="${occurrence.imageIds}" var="imageId" status="index">
<div class="sp-slide">
<img class="sp-image" />
<img class="sp-thumbnail" src="${occurrence.imageUrls[index]}" img-id="${imageId}"/>
</div>
</g:each>
</div>
</div>
</div>To instantiate the image thumbnail gallery you just need the id of the corresponding <div> container and the custom options if any:
new GalleryWidget('carousel', {options}The following snippet example initialises the thumbnail gallery and the viewer:
...
var customViewerOptions = {
imageServiceBaseUrl: imageServiceBaseUrl,
galleryOptions: { // Note #1
enableGalleryMode: true,
showFullScreenControls: true
}
};
new GalleryWidget('carousel', {
gotoThumbnail: function() { // Note #2
imgvwr.removeCurrentImage();
var selectedImageId = $('#carousel').find('.sp-selected-thumbnail > img').attr('img-id');
imgvwr.viewImage($("#imageViewer"), selectedImageId, $.extend(customViewerOptions, commonOptions));
}
});
imgvwr.viewImage($("#imageViewer"), images[0], $.extend(customViewerOptions,commonOptions));#1 - The viewer requires some options to be set to integrate the viewer gallery related controls with the thumbnail carousel. Please check these options in the corresponding section bellow 👇
#2 - The GalleryWidget options are those available in the SliderPro component, but many of them do not apply to the thumbnail gallery: SliderPro options. ❗The gotoThumbnail property needs to be provided always to see the selected image in the viewer.
| Option | Default | Description |
|---|---|---|
| enableGalleryMode | false | Need to be set to true if we want the viewer to take into consideration the other options available. |
| closeControlContent | null | In the case that the viewer is opened in a modal dialog or something similar, you need a button with the markup required to close the dialog. |
| showFullScreenControls | false | if true the viewer will show a control bar with two buttons to show the previous and next images. |
Example #1:
galleryOptions: {
enableGalleryMode: true,
closeControlContent: '<i class="fa fa-times" data-dismiss="modal" aria-label="Close" style="line-height:1.65;"></i>',
showFullScreenControls: true
}In this example the closeControlContent property adds a font-awesome icon to the control and adds the necessary markup to close a Bootstrap 3 modal dialog when it is clicked:
Check the SliderPro documentation for more information.
var defaultOptions = {
width: '100%',
height: '100%',
fade: true,
arrows: false,
buttons: false,
fullScreen: false,
shuffle: false,
thumbnailArrows: true,
autoplay: false
};All those can be overridden when creating the GalleryWidget instance.
The configuration options allow images to be marked as preferred by commmunicating with the lists server, which maintains a persistent list of preferred images and the BIE index, whuich records the current preferred image for a taxon. The user needs to be logghed in and have the appropriate roles to prefer images. Note this can get a bit tricky, since a successful prefer updates two services and there's plenty of room for authentication errors.
| Config | Description |
|---|---|
| speciesList.baseURL | SpeciesList BaseURL (eg: https://lists.ala.org.au) |
| speciesList.apiKey | API key for the species list web service |
| bieService.baseUrl | Bie Index BaseURL (eg: http://bie.ala.org.au/ws) |
| bieService.apiKey | API key for the BIE index |
| speciesList.preferredSpeciesListDruid | Preferred Species List Druid (eg: dr4778) |
| speciesList.preferredListName | Preferred Species List Name (eg: ALA Preferred Species Images) |
| allowedImageEditingRoles | User roles for users to be able to nominate preferred image for species. (eg: ROLE_ADMIN,ROLE_USER) |
TODO
-
version 0.8 (10/08/2017)
- Upgraded to Java 8
- Upgraded to Grails 2.5.6
- Upgraded to ALA Auth 2.x
- Added support for Asset Pipeline
-
version 0.7 (14/06/2016)
- Added feature to up and down vote an image.
- Added feature to nominate image as ALA Preffered image. ImageController will update ALA Preferred species list and once successful, it will update the Bie Index. Please see the configuration section for this feature to work properly.
-
version 0.6.1 (15/06/2015)
- Bugfix for img thumbnail carousel.
-
version 0.6 (10/06/2015)
- Added reusable thumbnail image gallery component based a customized implementation of the SliderPro component to reuse just the thumbnail gallery bit. This component is responsive, accesible through keyboard and support the swipe mobile events.
- Added some image gallery related options for the existing leaflet based viewer.
-
version 0.5.3 (02/06/2015)
- Bugfix release
-
version 0.5 (28/05/2015)
- Transfer of the subimaging tools to this plugin
- Added leaflet.loading control.
-
version 0.4 (20/05/2015)
- Optional parameter
initialZoomdefault value is now 'auto'. This means that the component will adjust the optimum zoom level so the image fits inside the image viewer container. - Removed unnecessary grails plugin dependency with ala-bootstrap2.
- Optional parameter