Gallerix 1.0 Documentation

Introduction

Gallerix is a photo album module for Drupal. It it's AJAX-centric but still relies on traditional methods to upload and manage pictures. Gallerix allows for per-user albums, and also includes an optional security mode.

Installation

Gallerix relies on a few essential PHP privileges to work properly. During installation, Gallerix will perform the following operations:

• Create the tables gallerix_pictures and gallerix_albums.

• Create the following table structure inside the files directory:

  • Gallerix

    • Albums

    • Repository

    • Trash

• CHMOD each of these folders to 0777.

Requirements

• MKDIR, RMDIR, CHMOD privileges.

• Working Image Toolkit (GD, ImageMagick)

Recommended

• Modifiable execution time, set to unlimited (-1)

  • Resizing pictures takes a huge toll on execution time, if you you have the option, either modify the .ini file, or use set_ini('max_execution_time', '-1') to set the max execution time to infinite.

• Modifiable max upload size and max post size.

  • If you plan on enabling archive uploads, you will need to modify PHP's default 2 MB limit.

• Views Module

  • If Views is installed, Gallerix will use the link www.example.com/gallery to list all albums, and it will also accept a UID as an argument.

Options

• Resolutions

  • You can modify the resolutions of all derivative images created by Gallerix. Note that the full size images are scaled, not resized, so the aspect ratio will remain the same. Thumbnails will first be scaled to the width, and then cropped, so they will have a landscape ratio, but remain proportional.

• Display Options

  • Sort: You can set the default sort order of all albums here. You can override this on a per-album basis in the album edit page.

  • Number of Thumbnails: This will change how many thumbnails display when viewing an album. This should probably be an odd number so the thumbnail of the current picture

• Picture Sources

  • Number of Upload Fields: controls how many pictures users will be able to upload at a time. Remember that this is more useful if you turn off archive uploading.

  • Archive uploading: allows users to upload ZIP/TAR.GZ files. This will generally require you to increase the max post size, and max upload size.

  • Enable Repository: Whenever you're in the Manage Pictures screen, Gallerix will scan files/gallerix/repository for pictures/archives to use. This is very useful if only a handful of trusted people can create albums, since you can upload everything with FTP.

  • Delete From Repository: if checked, files will be moved from the repository to the album rather than copied.

  • Add Trashcan Pictures: if the trash can is enabled (see below), the files in it will show up as files you can add.

• Picture Insertion

  • Extract EXIF Data: will extract the selected tags from any uploaded picture, and store them for other modules to use. Note that EXIF data is poorly standardized so only add fields you think are supported by your camera model. The default ones are fairly standard.

  • Extract IPTC Tags: will extract tags added by programs like Photoshop and Photoshop Elements that describe the picture, such as people, places, and authors. Unfortunately, PHP cannot differentiate between the type of tags, so they will all be treated the same.

• Picture Deletion

  • Enable Trashcan: When enabled, all deleted pictures will be moved to files/gallerix/trashcan rather than disposed of.

• Gallerix Security

  • Secure Mode: Activating this will enable secure mode, which for the time being is NOT retroactive. You should activate this from the very beginning if you wish to use this feature. See below for an in depth description.

Security

Gallerix provides no node access management, because this is best left to more specialized modules. What Gallerix can do, however, is make sure users stay within the realm of pictures they are allowed to see.

For example, lets say you nave node 20 with 4 pictures in it, with PIDs 1, 2, 3, 4. Then you also have node 25 which is only viewable by a few users (using your favorite node access module). Node 25 has 2 pictures in it, with PIDs 10, and 11.

In our example, when secure mode is activated, Gallerix will make sure users are only viewing pictures that belong to the NID they are in. That is, they can't just change the URL or the AJAX request to view pictures outside of the current node. With secure mode off, Gallerix will simply show whatever PID is requested, with no integrity checks.

Secure mode utilizes a variety of checks to perform its job, but the most important one is that it changes filenames to avoid sequential access. This is done using a SHA1 algorithm to every uploaded file. Of course, the original filename is lost. Similarly, the “sort by filename” option becomes useless since there will be no pattern in the new names.

Adding Pictures

Creating albums using Gallerix is a two step process. First you must create the album just like any other node in Drupal. The title becomes the album name, and the body is an internal description that users will not see. You can also select a sort order that overrides the default sort order, if you wish to do so.

Once the album has been created, you'll be taken to the main viewing page, which will tell you the album is empty. Click on the tab that says “Manage Pictures” to add pictures to the album. You can also remove pictures from the album through this screen, and add captions to existing pictures.

Captions will appear when you hover over a thumbnail. Other modules can also make use of the caption feature. Note that if you enable the “Extract EXIF” option, Gallerix will use the ImageDescription field as the caption field. If there's no ImageDescription, it will use Title. If there's no title, it'll leave it blank for the user to fill in.

Mass Operations

If you decide to change the default sort order, you should run “Resort Albums” on all Gallerix albums. This will only resort the albums that did not override the default sort order. Albums that do override the default sort order do not need to be resorted manually, they will automatically resort themselves upon submitting the edit form.

If you change the resolution of thumbnails or full pictures, you need to run “Rebuild Derivatives” on all the albums you wish to update. Keep in mind that building derivatives is an extremely intensive operation that will probably monopolize the server.

Gallerix Widget Engine

Although Gallerix is a robust module capable of managing all of your image needs, it becomes even more useful and powerful when paired with the Gallerix Widget Engine. When enabled, the engine will allow a variety to widgets to attach themselves to each image. The engine itself is bundled with four widgets:

• Original Widget: This is the simplest of all the widgets. It will add a link on all pictures that will take you to the location of the original, full sized image. You will probably want to avoid using this if you plan to resell your pictures.

• Date Widget: This simple widget will use the EXIF field “DateTimeOriginal” to let viewers know when the picture was taken. Note that EXIF extraction must be enabled in the general settings page.

• Caption Widget: Similar to the date widget, this will show the viewer whatever caption you added to the picture. This is very useful if you caption your pictures with management software such as Photoshop Elements.

• Story Widget: Although captions can be useful, they have a length limit since they are displayed right under the picture. Using this widget, you can add a story to each picture, and then submit it using AJAX. Only the album creator can use this widget.

Although Gallerix is open source and available for no charge, the Gallerix Widget Engine is only available through a (small) paid license. To purchase the license, visit http://the.failbo.at/gallerix to learn more.

Change Log

• 1.0 Beta