v2 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 and CSS

Outlined below are the JavaScript libraries that need 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.6.1 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.

Note that to unlock all the features of TagTray, you'll need to install the fancyBox v2 lightbox libray, which is also included in the block below.


<!-- Load fancyBox v2 library from CDNJS -->
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/fancybox/2.1.5/jquery.fancybox.css">
<script src="//cdnjs.cloudflare.com/ajax/libs/fancybox/2.1.5/jquery.fancybox.pack.js"></script>

<!-- Load the optional TagTray style theme (if you want to use our default styles) -->
<link rel="stylesheet" type="text/css" href="//api.tagtray.com/v2/tagtray-theme-default.css"/>

<!-- Load the TagTray library -->
<script src="//api.tagtray.com/v2/tagtray.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-layout-type this setting is used to switch between our default layout, where image sizes are fixed at a pre-defined width/height (the simplest way to get started), and a more mobile-friendly responsive fluid layout where image sizes adapt based on the viewport width, which can be enabled by setting this value to responsive. (default = fixed)
data-image-width width of each image in pixels when using a fixed layout (default = 150)
data-image-height height of each image in pixels when using a fixed layout (default = 150)
data-image-margin margin between images in pixels when using a fixed layout (default = 10)
data-columns-per-row you may optionally explicitly specify the number of columns you're displaying if a fixed page width using a fixed layout -- in this case, no margin is added to the right-most image of each column (default = 0 for disabled)
data-grid-options configuration of the grid when using a responsive layout type (default explained below)
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-page-size number of images on each page of the gallery, up to a maximum of 30 (default = 20)
data-max-num-pages optionally cap the max number of pages to allow (default = 0 for no cap)
data-display-pagination position or visibility of default pagination controls, either top, bottom, both, or none (default = top)
data-pagination-type by default pagination is displayed in a page up / page down format with each new page replacing the previous (updown), but optionally each new page can be loaded onto the bottom of the gallery instead (more) (default = updown)
data-next-text text to label the next page link (default = '>')
data-prev-text text to label the previous page link (default = '<')
data-load-more-text text to label the "Load More" pagination link (default = 'LOAD MORE')
data-wrap-gallery-css add an additional custom CSS class name to the main gallery wrapper
data-wrap-photo-css add an additional custom CSS class name to each photo wrapper in the gallery
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

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)


Step 4: Use Your Own Styling, Our Styling, or Both

TagTray has been designed to be fully styled using your own site's stylesheets, creating a seamless integration. So, feel free to override any of our styles.

Our installation instructions above include our standard default theme css -- this includes styling for pagination buttons, etc. It can be safely excluded if you wish to completley style these elements on your own.



Step 5: Add Any Additional Scripts

With no additional effort TagTray will make use of the fancyBox script you should already have installed (fancyBox v2 is required for full functionality, but fancyBox v1 will work as well).

You can also easily incorporate other scripts with your TagTray such as a bxSlider horizontal slider layout. See an example of bxSlider integration here.



Step 6: 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.


Extra Credit: Customizing Responsive Layout Options

TagTray offers an optional responsive layout feature, where, instead of specifying absolute sizes for your images, we attempt to lay them out for you at optional sizes based on the width of the screen. This is useful for sites that are built using a responsive layout.

We've modeled our 12-column grid system after Bootstrap's, given its popularity, so if you're familiar with Bootstrap's grid layout, you'll be familiar with ours.

In a nutshell, the screen is divided into a 12 column grid, and you have the ability to specify how many of those 12 columns you want each of your photos to span at various device widths. So, to divide your photos across these 12 columns, you would use the following number of grid columns per photo:

4 columns of photos:
each photo uses 3 columns of grid (4 * 3 = 12)
3 columns of photos:
each photo uses 4 columns of grid (3 * 4 = 12)
2 columns of photos:
each photo uses 6 columns of grid (2 * 6 = 12)
1 column of photos:
each photo uses 12 columns of grid (1 * 12 = 12)

The device widths you can specify are:

Size Used With Class Prefix
Extra Small Phones < 768px tagtray-col-xs-
Small Tablets >= 768px tagtray-col-sm-
Medium Desktops >= 992px tagtray-col-md-
Large Wide Screens >= 1200 tagtray-col-lg-

So, to put this all together, our default grid configuration is:

tagtray-col-xs-6 tagtray-col-sm-3 tagtray-col-md-3 tagtray-col-lg-2

Which equates to:

Extra Small:
2 columns of photos
Small:
4 columns of photos
Medium:
4 columns of photos
Large:
6 column of photos

You can change this default configuration by passing a different set of classes into the data-grid-options data attribute.



Upgrading from v1 API

Note that these installation documents are for our new v2 API. Upgrade instructions are here. We're still supporting the original v1 API, but if you need any assistance upgrading, please contact us for help.