Sync Hacks: Headless Drupal Photo Gallery Using BitTorrent Sync API

Sync Hacks is a column dedicated to exploring new applications for Sync, as built by users like you. BitTorrent Sync is a free, unlimited, secure file-syncing app. (And now, it’s 2X faster.) If you’ve got an epic Sync idea, use-case or how-to, shoot us an email at sync[at]

In this week’s Sync Hacks: Realityloop‘s Stuart Clark shows us how to make a headless Drupal photo gallery using the BitTorrent Sync API. Read on for the full how-to, and check out Stuart’s original Realityloop post here.


From Stuart:

A headless photo gallery

My father is a hobbyist photographer, and like many other web developers out there I have at one time in my past tackled the job of building a website for a family member, both pre and during my time working with Drupal; pre-Drupal with a manual process of image resizing, and using ImageCache/Image styles to automate the process with Drupal.

What I found is that no matter how easy you make a system (and there are so many things you can do to improve the usability in Drupal), it can always be made simpler.

The appeal of BitTorrent Sync for a photo gallery site is the ability to manage the content in a completely headless state; no need for your users to log into the site at all, just drop their photos in a folder and they’re done. This is exactly what I will be demonstrating below.

This tutorial will cover:

1. How to setup the Sync API module
2. How to setup the Sync Fields module
3. Setting up a basic Sync powered photo gallery

This tutorial assumes you have:
1. An API enabled BTSync sever; see ‘Enabling the API’ in the Developer documentation
2. A fresh ‘Standard‘ install of Drupal 7
3. A basic understanding of Drupal site building

Part 1: Installing/enabling the modules

For this tutorial I used the following modules:

• BitTorrent Sync API 7.x-1.0:
• BitTorrent Sync Fields 7.x-1.0-beta1:

Install Drupal

There are various methods of installing Drupal modules. I prefer Drush or Drush make, but will demonstrate install via Drupals built in module installer

1. Navigate to your sites ‘Install new module‘ interface: admin/modules/install

2. Copy and paste one of the modules URLs, as provided above, into the ‘Install from a URL‘ field.

3. Click the ‘Install‘ button.

4. Repeat steps 2-3 until all modules are successfully installed.

5. Click the ‘Enable newly added modules‘ link or navigate to your sites ‘Modules‘ interface: admin/modules

6. Enable the newly added modules; Check the boxes next to the modules and click the ‘Save configuration‘ button.

Part 2: Configuring the BitTorrent Sync API module

Assuming you have already setup your BitTorrent Sync server and it is API enabled, this step should be painless.

1. Navigate to the ‘BitTorrent Sync API‘ configuration interface: admin/config/services/btsync

Note: If you are still on the ‘Modules‘ interface, you can simply click the ‘Configure‘ link next to the BTSync API module.

2. Enter the following details:
URL: The URL of your BTSync API server, likely the same as default.
Username: The ‘login‘ value as per the configuration of your BTSync API server.
Password: The ‘password‘ value as per the configuration of your BTSync API server.

3. Click the ‘Save configuration‘ button.

Part 3: Set up a content type & configure the Fields module

In this step we are going to setup a new content type and attach a Image field using the BTSync fields widget.

The BTSync Fields module provides Field types and widgets for Drupals Field system. As of writing this, the 7.x-1.0-beta1 release only contains a single field widget; BitTorrent Sync (basic). This widget allows us to assign or generate a BTSync secret to a File or Image field and when Cron is run it will ensure all eligible files in the sync are associated with the Field. This is the basis of our headless photo gallery.

1. Navigate to the ‘Content types‘ interface: admin/structure/types

2. Click the ‘Add content type‘ link.

3. Enter a human readable name for your content type (e.g., Gallery) and click the ‘Save and add fields‘ button.

4. Under the ‘Add existing field‘ row, select the ‘Image: field_image (Image)‘ item and update the ‘Widget‘ to ‘BitTorrent Sync (basic)‘.

5. Click the ‘Save‘ button.

On the next page, make the following changes (Note: These are just recommended settings for the sake of this tutorial.)
Required field: Ticked

Allowed file extensions: jpg, jpeg

Number of values: Unlimited

6. Click the ‘Save settings‘ button.

Part 4: Test it all out

Now that (most of) the hard stuff is out of the way, we can actually test it out and see it working in action. To do so, we will be generating a BTSync secret during the creation of a Node of our previously created Content type, and then using that secret to sync our photos.

1. Navigate to the ‘Add content‘ interface (node/add) and click on your newly created Content type (e.g., Gallery).

2. Give the content a ‘Title‘ (e.g., BTSync Gallery).

3. In the ‘Image‘ field, click the ‘Generate secret‘ button and copy the generated secret.
Note: If nothing happens, it’s likely due to mis-configuration of the BTSync API module or that the BTSync API server you defined is currently offline.
4. Click the ‘Save‘ button.

5. Setup a Sync folder with the generated secret in a desktop BTSync client (or at least an alternate BTSync instance).
6. Add some Photos to the folder and wait for them to finish syncing.

When Cron is next run all eligible synced files will be attached to the field and they will display on our newly created gallery.

For the sake of this tutorial, you can force Cron to be run via the ‘Status report‘ interface (admin/reports/status) by clicking the ‘run cron manually‘ link.


Part 5: Make it pretty(ier)

This approach in itself doesn’t make a photo gallery. Instead, it makes a piece of content with a bunch of images attached. There are many different ways you can work over the display, each with their pros and cons. My preference is generally a Views based solution, but for the sake of keeping things simple I will be using a Field formatter based approach with the Gallery formatter module.

1. As per Part 1, install and enable Gallery formatter module, version 7.x-1.3 (

2. Navigate to your Content types ‘Manage display‘ interface: admin/structure/types/manage/[content_type]/display

3. Choose ‘jQuery Gallery‘ on the ‘Format‘ dropdown on the ‘Image‘ field.

4. Click the ‘Save‘ button.


There you have it, a simple BitTorrent Sync-powered, headless, Drupal photo gallery.

Stuart Clark (@Decipher) is the lead Drupal developer at Realityloop ( in Australia.