Installation and Configuration
Step 1: Setup Your TagTray Account
Create an account on TagTray and enter the tags from Facebook, Instagram, Twitter, or custom photo uploads, that you want to assemble into a gallery for display on your site. This custom gallery you've created will be available for display on your site using a code snippet explained below.
typically be installed before the closing
</head> tag of your main page layout).
TagTray requires jQuery v 1.7 or higher to operate. In the unlikely case that your site is not
currently using jQuery, you will need to install it before the TagTray includes. The easiest way to do so
is to follow Using jQuery with a CDN.
<!-- Load the TagTray library --> <script src="//api.tagtray.com/v3/tagtray.js" ></script>
If you plan on using our carousel layout option, also include the optional TagTray carousel library.
<!-- Load the TagTray + Carousel libraries --> <script src="//api.tagtray.com/v3/tagtray.js" ></script> <script src="//api.tagtray.com/v3/tagtray-carousel.js" ></script>
Step 3: Display the Gallery On Your Page
After you have configured your gallery's tags through our dashboard, you will be be given a unique code per gallery that you can use to display that gallery on your website. Your gallery code will be shown in red at the top of your gallery management page.
Use the following code snippet (customized with your gallery code) to output that gallery wherever you choose. Note that your TagTray gallery is extremely customizable, so browse through all our example galleries, and carefully review the configuration settings outlined below to find a setup that best matches your needs.
<!-- Display the TagTray gallery in the body of your site --> <div class="tagtray-gallery" data-gallery-code="add your assigned gallery code here"></div>
Optional Configuration Attributes
|data-gallery-type||this setting is used to switch between our default active layout, where the gallery images are auto-arranged responsively in a manner that best fits the available space (the most common format), a carousel layout where the images are presented horizontally in a carousel / slider component, and an optional passive layout, where the gallery is presented without any special formatting, giving you the option to apply your own custom layout (default = active)|
|data-hide-source-icon||we'll display an icon over your gallery photo indicating the source of the photo (e.g. Instagram or Facebook) unless you select this option to hide that icon (default = false)|
|data-overlay-type||In order to customize the overlay that's displayed when hovering over a photo, message displays the post's comments, likes displays a count of likes for the post, or you can hide the overlay if you wish by selecting none (default = message)|
|data-overlay-tagline||specify an optional message to display at the top of the overlay upon hover (default = "Shop The Style")|
|data-page-size||number of images on each page of the gallery, up to a maximum of 30 (default = 24)|
|data-max-num-pages||optionally cap the max number of pages to allow (ignored in carousel layout) (default = 0 for no cap)|
|data-load-more-text||text to label the "Load More" pagination link (default = 'Load More')|
|data-image-resolution||by default we'll load the highest resolution source image for the photos in your gallery, but you can explicitly specify an image resolution by overriding this setting to low (approx. 150px wide), medium (approx. 320px wide), or high for the highest resolution available (default = high, except with carousels where a best fit can be determined)|
|data-icon-facebook-url||optionally override the standard Facebook icon overlay with one of your own|
|data-icon-instagram-url||optionally override the standard Instagram icon overlay with one of your own|
|data-icon-twitter-url||optionally override the standard Twitter icon overlay with one of your own|
|data-icon-upload-url||optionally override the standard custom upload icon overlay with one of your own|
|data-icon-video-url||optionally override the standard custom video icon overlay with one of your own|
Carousel AttributesThese attributes are used to configure the optional carousel layout type.
|data-carousel-slide-width||width of each slide in a carousel layout (default = 200)|
|data-carousel-slide-margin||margin between each slide in a carousel layout (default = 10)|
|data-carousel-min-slides||the minimum number of slides to be shown (default = 1)|
|data-carousel-max-slides||the maximum number of slides to be shown. (default = 6)|
|data-carousel-force-square||if true, horizontal photos will be cropped to square dimensions (default = false)|
|data-carousel-pager||if true, a pager will be added (default = false)|
|data-carousel-controls||if true, "Next" / "Prev" controls will be added (default = true)|
|data-carousel-auto||if true, slides will automatically transition when browser has focus (default = false)|
|data-carousel-pause||the amount of time (in ms) between each auto transition, if enabled (default = 4000)|
Photo Uploader AttributesThese attributes are used to configure the photo uploader -- see the photo uploader guide for more info.
|data-fp-upload-type||Optionally specify simple for the easiest of upload options (everything is handled for you), or select collect-info to add your own info collection form (default = none)|
|data-fp-upload-message||Specify the message that will be displayed beside the upload button (default = 'Submit your own photo to our gallery')|
|data-fp-success-message||Specify the message that will be displayed after a successful upload in the simple mode (default = 'Your photo upload was successful.')|
|data-fp-success-message-class||Specify the CSS class(es) that will be wrapped around the success message in simple mode (default = Bootstrap style 'alert alert-success')|
|data-fp-button-text||Specify the label that will be displayed on the upload button (default = 'Select Photo...')|
|data-fp-button-class||Specify the CSS class(es) that will be wrapped around the upload button (default = Bootstrap style 'btn btn-primary')|
|data-fp-services||The list of services from which to allow uploads. The services will be shown in the provided order. Full list (default = 'COMPUTER,WEBCAM,INSTAGRAM,FACEBOOK,URL,DROPBOX,GOOGLE_DRIVE,CONVERT')|
|data-fp-crop-ratio||Specify a mandated crop area height to width ratio. This can be a float, an integer or a ratio like 1/1 (to enforce a square upload), 4/3 or 16/9. By default it is not specifed.|
Shoppable Gallery Attributes
|data-product-id||this field can be optionally used with our shoppable photos feature to pass in the product ID from your eCommerce template for the current product page, in which case only photos tagged with that product will be displayed (creating a product-specific gallery)|
TagTray fires off certain events in the rendering process to help you do pre and post render processing (such as customizing apparance or behavior via jQuery). These events are listed and described below.
Note that your event handlers should come after the TagTray display snippet.
|show.tt.gallery||This event is fired before the gallery is rendered. Use this to update gallery configuration data attributes before the gallery is rendered.|
|shown.tt.gallery||This event is fired after the gallery has been rendered. Use this to update the gallery
param1: returns the number of photos rendered in the gallery. Use this to act on an empty gallery.
|flip.tt.page||This event is fired when a gallery page is turned.|
CSS Style Options
In addition to the numerous column width CSS classes explained in detail in the next section, these classes can be applied to the main tagtray-gallery div.
|tagtray-no-margins||This class will remove all margins between the photos in the standard grid-based gallery layout.|
Customizing Gallery Column Widths
By default a responsive gallery will be rendered at either 1, 2, 3 or 5 columns wide, depending on the screen width. You can override these defaults by adding one of the following classes to your main gallery DIV.
For example, to specify a minimum column count of 2 columns on extra small devices, and 6 columns on large devices, you would add these classes to your gallery as follows.
<div class="tagtray-gallery xs-cols-2 lg-cols-6" ... </div>
|Num Columns||Extra Small
Phones (<= 480 px)
Tablets (<= 720 px)
Desktops (<= 1224 px)
Desktops (> 1224 px)
Manually Rendering Galleries via JavaSript
Upgrading from v2 API
Note that these installation documents are for our new v3 API. We're still supporting the original v2 API, but if you need any assistance upgrading, please contact us for help.
Major things to note:
- If you installed fancyBox with our TagTray library, you can now remove those CSS and JS includes, they're no longer needed.
- If you installed bxSlider to display your gallery in a carousel, you can now remove those CSS and JS includes as they're no longer needed either.
- All the boilerplate HTML previously required with the simple file upload are no longer needed.
- All fixed width options have been removed.
- The prior grid-based responsive layout options are no longer available.