theUpstairsRoom

In the last two installments, we looked at the basics required to interact with a Horde server and obtain content for display on external, or "non-Horde" websites.  In this article, we'll take it a step further and give a concrete example of using Horde content to power a website - we are going to use Ansel, the Horde Project's photo management application, to power a personal, or family website.

Ansel is a powerful photo management application that provides many features.  Even so, sometimes you just want to have a dedicated website to showcase your images...or maybe you want to integrate a gallery onto an existing website. Both are very easy using Ansel's api.

For this example, let's assume we are trying to integrate a family photo album into an existing family website.  To do this, we are going to add a 'Gallery' section to the site, and for simplicity, we are going to use a "Lightbox" style gallery, so that when you click on an image thumbnail to view it, an overlay appears displaying the image on the same page. Gallery styles are a key part of Ansel, and allow you to change the look and feel of the Gallery View. You can learn more about styles and how to hack your own by looking at the create_serialized_styles.php file in the scripts/ directory.

So, let's get started.  Let's assume that you have a number of galleries in Ansel and you only want to show a certain sub-set of those galleries on the new site. For example, let's say that you want all the galleries that have a category of "Family" to appear on this site. (It's also possible to do this with just a list of gallery ids you want included, but you would have to build the top-level View yourself. In the stable release of Ansel, this limitation will be fixed).

First things first, let's define some configuration stuff. (These should probably be in some sort of conf.php file and included on each of your "gallery" pages).

/ These define the root of the site
$base_url = 'http://example.com';
$fs_base = '/srv/www/example.com';
// The path to the Horde server.
$horde = 'http://another.example.com/horde';
// Let's assume we want all the galleries in the 
// "Family" category
$filter = 'Family';

// ...but only those owned by this user.
$owner = 'myusername';

// The named Ansel style to use.
$gallery_style = 'ansel_lightbox_simple';

Now, before we do anything useful, we will need a Registry instance:

define('HORDE_BASE', '/horde');
require_once HORDE_BASE . '/lib/core.php';
$registry = &Registry::singleton();

 Now for the fun:

$content = $registry->call(
    'images/renderView',
    array(array('owner' => $owner,
                'category' => $filter,
                'style' => $gallery_style,
                'gallery_view_url' => $base_url . '/gallery.php?gallery=%g'),
    null,
    'List'));
  

Some explanation: This calls Ansel's images/renderView api method. This method takes 3 arguments. The first is an array of parameters that get passed to the Ansel_View object that will be doing the rendering, the second is the application scope (we are using the default scope - if you don't understand this, it's not important to the task at hand), and the third is the general type of view we want to render (currently supported are Gallery and List - an Image view should be available by the time Ansel is released as stable).

The various view parameters that a view takes can be browsed by viewing the developer documentation for each view, but a quick explanation for the parameters we are using for the List view are as follows:

• owner - We are limiting to galleries owned by this username.
• category - Only galleries that have this category are returned.
• style - Force the use of this gallery style.
  
• gallery_view_url - This is perhaps the most important one, as this sets the url that the gallery thumbnail will point to.  You set this to the page on your site that will render a single gallery - %g is replaced by the choosen gallery's id.

So, what we have now, in $content is the HTML needed to render a List of galleries, that will correctly point to a page on your own website to view an individual gallery. Now, let's look at what it takes to actually render that gallery - in gallery.php (the target page we set above):

/* Grab the form info */
require_once $fs_base . '/lib/Utils.php';
$gallery_id = Util::getFormData('gallery', 0);

$content = $registry->call(
    'images/renderView',
    array(array('gallery_id' => $gallery_id,
                'gallery_view_url' => $base_url . '/photos/gallery.php?gallery=%g',
                'style' => $gallery_style,
                'image_view_url' => $horde . '/ansel/img/screen.php?image=%i',
                'hide_comments' => true),
          null,
          'Gallery'));

Again, we are calling the images/renderView api method. This time we are requesting a Gallery view to be rendered.  The view parameters in the first argument are similar to the first time we called this method - the new parameters are:

• gallery_id - Yes, this is the gallery id we want to view.
• image_view_url - This is similar to the gallery_view_url, except that this parameter is used as the target when clicking on an image thumbnail. It's the link that gets followed to view a single image (in this case, it's the actual path to the image, since that's what the LightBox style requires). Also, %g  and %i are replaced by the gallery id and image id respectively.
• hide_comments - allows the hiding of the comment counts for each image (if comments are enabled in Ansel). Setting this to false or omitting it will cause the number of comments to show in each image "tile".

We now have a very basic way to render a complete Ansel gallery on an external website using just a handful of api calls.  This article demonstrates the basic idea, but obviously leaves out a bit of eye candy.  In the next installment we will look more deeply at Ansel's api to see what else is available, including some techniques for getting things like a list of most recently added images.

Resources:

• http://dev.horde.org/api/ansel
• http://cvs.horde.org/ansel
• http://horde.org/ansel
  

Some sites that use Ansel via the api as described here:

• http://theabramsgallery.com
• http://rubinskyfamily.com/photos