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.


Step 2: Install the TagTray JavaScript

Outlined below is the JavaScript libraries that needs to be included on your site (this code would 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 Attribute Description
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 Attributes

These attributes are used to configure the optional carousel layout type.
Data Attribute Description
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 = 2)
data-carousel-max-slides the maximum number of slides to be shown. (default = 6)
data-carousel-pager if true, a pager will be added (default = true)
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 Attributes

These attributes are used to configure the photo uploader -- see the photo uploader guide for more info.
Data Attribute Description
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 Attribute Description
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)

Events

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.

Event Description
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 after it has been rendered, or to tie it together with other JavaScript libraries.

Optional Params:
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.

Class Description
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)
Small
Tablets (<= 720 px)
Medium
Desktops (<= 1224 px)
Large
Desktops (> 1224 px)
1 default sm-cols-1 md-cols-1 n/a
2 xs-cols-2 default md-cols-2 lg-cols-2
3 xs-cols-3 sm-cols-3 default lg-cols-3
4 n/a sm-cols-4 md-cols-4 lg-cols-4
5 n/a sm-cols-5 md-cols-5 default
6 n/a n/a n/a lg-cols-6


Manually Rendering Galleries via JavaSript

TagTray galleries are automatically rendered after the DOM of their host page has been fully loaded. Sometimes it is desirable to manually control the gallery rendering, for example when building a single-page JavaScript app for which the DOM isn't reloaded after navigation, or when attributes of a gallery need to change based on user interaction. To force the galleries to render (or re-render based on changed attributes), use the following JavaScript method:


TagTrayCore.renderGalleries();


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.