3 DecStuart Clark

Not even 24 hours after the release of the BitTorrent Sync (BTSync) API, an API that I was eagerly awaiting, we were happy to be able to release arguably the first implementation of said API in the form of the BTSync API Drupal module, and only a few weeks later I personally released a Beta release of the BTSync Field module.

Since then I've been planing on putting together both a text and a video tutorial/demonstration on exactly how one would use the modules, and maybe to touch on future plans I have working with the BTSync API. I was also approached by BitTorrent's Kathie Pham with interest in showcasing the work I have done with the API at Realityloop and in my own time, so even more motivation to get something put together.

I've decided that all the things I would like to demonstrate would be too much for a single post, so instead I will be doing multiple posts over a period of a few weeks (hopefully).

The Tutorial: BitTorrent Sync powered, headless, Drupal photo gallery

There are so many things that the API could be used for, I personally have many plans for future modules, more ideas than time, but the one thing that appealed to me the most, and the idea that the tutorial/demonstration is going to focus on, is photo galleries.

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 BTSync for a photo gallery site, to me at least, 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:

• How to setup the BTSync API module
• How to setup the BTSync Fields module
• Setting up a basic BTSync powered photo gallery

This tutorial assumes:

• An API enabled BTSync sever; see 'Enabling the API' in the Developer documentation
• A fresh 'Standard' install of Drupal 7
• 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: http://ftp.drupal.org/files/projects/btsync-7.x-1.0.zip
• BitTorrent Sync Fields 7.x-1.0-beta1: http://ftp.drupal.org/files/projects/btsync_fields-7.x-1.0-beta1.zip

There are various methods of installing Drupal modules, with my personal preference being Drush or Drush make, but I will demonstrate installation 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 BTSync API module.

Assuming you have already setup your BTSync server and it is API enabled, this step should be relatively 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 - Setting up a content type / Configuring the BTSync Fields module.

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.

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

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.
6. On the next page, make the following changes:
   • Required field: Ticked
   • Allowed file extensions: jpg, jpeg
   • Number of values: Unlimited

   Note: These are just recommended settings for the sake of this tutorial.

7. Click the 'Save settings' button.

Part 4 - Time to 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 (http://ftp.drupal.org/files/projects/galleryformatter-7.x-1.3.zip).
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 BTSync powered, headless, Drupal photo gallery.

In the next post I will be covering over how to integrate with the BitTorrent Sync API module directly and with the Rules module, keep your eyes peeled.

drupal planetdrupal 7btsynctutorial