img_0441

Notes about this book

To start off, we will get some definitions straight.

• $document_root refers to the filesystem's absolute path of your server's root (the place that gets pointed to by http://mysite.dom/)
• /path/to/drupal will be used as your filesystem's absolute path to the drupal install. This will also be referred to as $drupal_root
• $drupal_base refers to the path between $document_root and /path/to/drupal. The internal drupal global value $base_url should be equal to "http://mysite.dom/$drupal_base"
• drupal filesystem path (go to admin/settings or click on administer->settings) set 'File system path'
• filemanager public path (admin/settings/filemanager) set 'Public file system path'
• filemanager private path (admin/settings/filemanager) set 'Private file system path'

Some other notes to help with this document.

• Drupal paths are the query path that is really the $_GET['q'] argument. All drupal paths will be listed as relative paths to $drupal_base without the '?q=' prefixed. This means that if you are not using clean URLs, you will have to add the '?q=' before the path. For example, if our $drupal_base is 'content', a Drupal path like node/admin is really the URL http://mysite.dom/content/node/admin if you are using clean URLs and http://mysite.dom/content/?q=node/admin if you are not.

Cannon Beach

Overview

History

Acidfree is the 4th generation of a brainchild of Darren Hart, Bret Gundersen, and mine as we sought to create a cool webpage that our families could use as a communication hub. The original photo albums looked about the same, but were so integrated into the website that it was a bit of work to extract them and insert them into my own young website. The code was, frankly, not my best work ever. But I was young, inexperienced in web development, php, and user interfaces so my shortcomings can be overlooked for this first generation. The important point is that I got better.

The second generation was a bit of a rewrite to make the albums more modular so it would be easier to share the albums with other people. I think the biggest change was that the new albums were my first attempt at an object-oriented version. But with the limitations that php4 had, it really wasn't done right.

The third generation was a complete rewrite using php5 and a well-designed architecture done by Darren. In short, I thought this was the final resting place for the my photo albums. It worked well, and I was not the only one that thought it was an elegant design. But in the end, I realized that I didn't really want to play the part of Content Manager, Layout, and more. Darren introduced me to Drupal and the rest is history.

I found out that you could create modules to extend Drupal and immediatly the thought that if I could but have my happy albums, I would be a Drupal man. So I set out. At first, my realization that Drupal was object-oriented without using actual php5 object was disappointing. I got over that and wrote a module that extends the node type to behave like a photo album. Some time during this process I chose the name Acidfree because like all the acid-free scrapbooking supplies, my albums will not cause your images to fade or discolor over time. It took me some time and several tries before I was happy with the code structure and program flow. But about two months later, it is running on my own Drupal-based website. And three others.

Since getting Acidfree into the Drupal Contributions section, I have received help from several people in the form of patches, advice, and support help for all the support requests. Robb has also time and a considerable amount of code to get Acidfree working better with the various node_access modules. And finally, (and my wife's favorite part of all of this) is that various people have made monetary donations to the project. These go to a special fund that helps keep my wife happy so I can keep coding.

Behind the name

In the world of photo archival, acid-free paper is essential for the care and protection of your photos. In the paper creation process, the pulp is acidic (whether it is added for some reason or if it is naturally acidic, I don't know) and thus when it is made into paper, it causes what is called slow fires in the paper, which eventually destroys the paper and the images. My wife and all my sisters are avid scrapbookers and have told me that using acid-free paper and supplies is essential. So, when I was making my digital album, I wanted to follow suit and make sure that it was acid free and will keep my photos safe for generations to come.

What Acidfree is and what it isn't

Acidfree is not Gallery. Acidfree is an easy to use, good looking, Drupal-based photo and media album. It was written so that it could be extended to support other media types. It was written so it would be easy enough to use that my mother-in-law could use it.

Acidfree keeps your photos safe for generations

Acidfree is meant to a simple, yet full featured photo album for Drupal. It was designed from the ground up as a node type for Drupal, so it is very well integrated into the Drupal architecture. It is much simpler than Gallery to set up and use, but most definitely has fewer features. And it will never have as many features. If you want more features, by all means use Gallery. But if you want a simple, easy to use, full featured photo album, this is the place for you.

Acidfree includes support for various image types (and it is easy to add more) and for basic video types (think short clips from your digital camera). Again, it is easy to add support for more types of media if you want. I designed it to be extensible and themeable.

dscf1042

dscf2223

img_0415

Installation

This document assumes that you have correctly installed Drupal. It should not matter whether or not your $drupal_root is the same as $document_root or not. It should also work if you have your modules dir embedded as a subdir to your sites dir in $drupal_root.

A short version of installation listing is found in the README file included in the Acidfree distribution.

1. Install the Filemanager module from the drupal modules page and set it up.
   • This includes creating the table, setting paths, creating directories, etc. on the admin/settings/filemanager page. For more information on this topic, go to the Filemanager configuration section of this book.
   • Make sure you download the latest version of the Filemanager module. If there are any patches required for the filemanager, they will be included with the Acidfree distribution. We try to minimize this, but since both the Filemanager and Acidfree are just starting to get larger user bases, we are finding things where the APIs could improve.
2. Untar Acidfree distribution into your modules directory. Make sure the entire directory is included — don't just copy the acidfree.module file into your modules directory. The entire acidfree directory should be a subdir of the modules directory.
   • If there are any patches included in the Acidfree distribution, follow the directions at the top of the patch. They should be named something like filemanager-something.patch. If you don't know what a patch is or how to apply one, see How to install a Patch? Also, the INSTALL and UPGRADE files for that distribution will contain information on what you need to do.
3. Create the tables as shown in acidfree.mysql or acidfree.pgsql, making sure to add database prefixes if you are using them.
4. Enable the acidfree module on the admin modules page (admin/modules).
5. Go to the Acidfree settings page (admin/settings/acidfree) and configure Acidfree. For more details on this go to the Configuration section of this book.
6. Go to the acidfree/test page http://yoursite.dom/acidfree/test (or http://yoursite.dom/?q=acidfree/test) to check your install and settings. Follow any instructions it offers.
7. create albums and content!!

Living room

Our Home

Thanksgiving 2007

Travels

wedpic78

Acidfree Configuration

Because Acidfree is a fairly complex system, dealing with several media types, configuration is not trivial. But, we have tried to include sane default values, so you shouldn't have to worry to much about this section.

Image Resolution

Acidfree allows you to choose the size of images made available to users. There are three sizes: large, the highest resolution image, usually used for printing; medium, the browser viewable image; and thumbnail, the one that you will see when viewing an album. Choose these sizes wisely. Choose sizes that meet your disk space and theme.

It is possible to resize images after they have been imported by changing the image size and then hitting the cron script (http://mysite.dom/cron.php). But beware that it only resized a few at a time, not the entire site. You can select the number of images to resize at one time. Set this at a number that you are comfortable with, being aware that resizing images takes processor power and time. Do not set it to a too-high number that will cause a PHP timeout. See the acidfree/test page to check your max execution time.

It is possible to choose 'Do not keep large image', which means after creating the medium and thumbnail images, it will discard the full sized one. You can do this to save disk space, but if you do, you will not be able to resize the medium image to a larger size at a later time. The medium image is created from the full sized image and the thumbnail is created from the medium image, so you can resize the thumbnail to a larger size even if you are not saving the large images.

This section will also tell you how many of the images have been resized, so you can see how many more you have to go before your entire site is resized.

Acidfree Display

This section is primarily about simple themeing and aesthetics. These settings do not really change much important, so set them however you want. The defaults are sane.

• How do you want to order your pictures? Currently supported is chronologically and reverse chronologically or most recent first.
• Number of rows and number of columns in the album view (this also sets the number of items listed in the album contents view (rows*columns).
• Whether or not to show EXIF data. If the image has EXIF data, it will be shown in a div that can be themed to your liking on the full view of the image.

Image Manipulation

The image toolkit settings found on the site settings page (admin/settings) list the current image toolkit. Drupal ships with a default that uses GD2. The Image module ships with an ImageMagick toolkit (image.imagemagick.inc). Acidfree ships with another toolkit, Imagick (image.imagick.inc), a php4-imagick library that uses the ImageMagick libraries, but does not require forking and execing a new process. Choose whatever toolkit you want. All the toolkits work fine as far as Acidfree is concerned. It has been said that GD2 is slower than the others, but it is up to you.

Acidfree will work fine with only the image toolkit. But for those image snobs like the Author, lossless jpeg rotation is also supported using exiftran or jpegtran. If you want to have lossless jpeg rotation, install one of those programs and set the path in this section. Acidfree automatically tries to use lossless rotation and if that can't be done, it uses the image toolkit for rotation. While it is lossy, for most images it won't matter and you won't really be able to tell. But repeated rotations could result in poorer image quality.

Video Manipulation

Acidfree offers three settings for video manipulation. No thumbnails, user-supplied thumbnails, or mplayer-generated thumbnails. Be aware that currently, unless you are using the mplayer method, mass uploads of videos will not work because there is no way to determine the video resolution.

No thumbnails is the easy way out. All you have to do is set the height and width of the video when uploading it and a static thumbnail will be used for all the videos.

User-supplied thumbnails will probably get you the best looking thumbnails for your videos. For this option, you must supply a full-sized frame (the same resolution as the video) that you want to be the thumbnail. Acidfree will resize it to the correct size for the thumbnail.

Mplayer can automatically create thumbnails of most video types. This method currently will just grab the first frame of the video and create a thumbnail out of that. To use this method, you must have mplayer installed, select this option, and set the path to the executable.

Filemanager Settings

Acidfree supports public and private content via node_access modules such as Organic Groups or Node Privacy by Role. When a node is marked as not viewable by the Anonymous user, the files will be stored in the Filemanager private filestore. Here you can choose to store all of your images in the private filestore or update all your media files to reflect their respective nodes' public or private state.

Note that forcing all files to be stored in the private filestore will cause a performance hit, as streaming the files with Drupal is not as efficient as letting Apache handle it.

Unless you are upgrading from an older version of Acidfree, the 'Process all images against new security' option should not be necessary. But if you do select this, it is done via the cron hook, so you must hit cron.php enough times to process all your images.

Other settings

Access controls

Make sure you set up the appropriate permissions on the access control page (admin/access). You can choose to allow 'acidfree mass import', 'create acidfree albums', 'create acidfree photos', 'create acidfree videos', and 'edit own acidfree elements' for each user group.

Input filters

If you wish to have embedded Acidfree images in your other node bodies, enable the Acidfree input filters. Go to admin/filters and select 'configure' for each input type you want to enable it for. Then, check 'Acidfree inline filter' and hit save. This allows for tags like [acidfree:nnn] to be put in the body field of other node types.

Default publish/comment options

By default, Acidfree does not promote new items to the front page. If you wish to change this or change the other 'workflow' settings go to admin/node/configure/types/acidfree and change the defaults.

Filemanager configuration

• Public file system path: this path is most commonly the same as the 'File system path' on the admin/settings page. For a Drupal install that is serving several sites, a common place to put this is 'sites/domain.dom/files'. Then, each site's files are separate and can be protected on a per site basis.
• Public file system url: this is the $base_url plus some path to get to the 'Public file system path' above. This is for when the filemanager makes absolute URLs.
• Private file system path: this path is where the Filemanager keeps files that are marked private. This directory must be within the Drupal 'File system path' (admin/settings). This directory should not be web accessable (for those using Apache, the <directory> stanza with a deny statement is an order) but must be readable by the web server so the Filemanager can stream the files via http://yoursite.dom/filemanager/active&fid=nnnn requests.
• Maximum files per directory: for filesystem performance, the Filemanager makes sure that each directory does not have too many files in it. It uses numbered directories 0...n to separate files of the same name and to preserve fast directory access times.
• Working size limit: the working area is a staging area for temporary files. To become permanent, 'working' files are promoted to 'active' status. The working area does not need to be too big, but depending on the throughput of files and working age limit, you might want a larger size.
• Maximum working age: all files that do not get promoted from working to active will get deleted after they are too old. This determines the cleanup age. '-1' probably is not the best idea here.
• Maximum size limit: this is for all your files in all the different 'areas'. Unless you are disk-space limited, it is probably a good idea to leave this as '-1' and then limit each area individually.
• File areas: here you can set max size for each area (Acidfree is one 'area'). Make sure you select a large enough value for all your pictures or '-1' for unlimited. Also, you can check the box to force the Filemanager to use private files for all files in each area. This means that none of the files are directly accessible and will be transferred via streaming URLs. Because streaming is more processor intensive than direct access to files (letting the web server serve the files) it is better to not check this box.

Basic use of Acidfree

Adding content

There are several ways to get to the add acidfree pages.

1. To add content, from the navigation menu, you can select 'add content' -> 'acidfree media' -> and then the kind of media you want to add (photo, video, etc.)
2. go to node/add/acidfree/photo or node/add/acidfree/photo/nnn where nnn is the nid of the album you want to add to. (you can also substitute album/video/etc. for photo in the above URLs.)
3. go to an album you have own and click on the 'add photo...' links.

Once on the add content page, there are several required fields. Title is required for all media types. Parent album is also required. For albums, you can only select one parent. For other media types, you can choose multiple parent albums to place the items in.

• Album: no further required items.
• Photo: you must include the path to the full sized image you want to import. The screen viewable and thumbnail images will be generated automatically.
• Video: you must include the path to the video file you want to import. In addition, video may require video dimensions or an extracted video frame. If you are uploading the video frame also, be sure that it is the same size as the actual video — it will get resized to make the thumbnail.

There are other optional fields you can fill in. Description will be shown on the full view of the item (i.e. node/nnn will show the description for the item with nid nnn). Weight will determine a rough sorting order with items that have a larger weight sinking to the bottom of the pile and lighter ones floating to the top. Also fields from other modules will show up here like public/private access, taxonomy, etc.

Mass import

Mass import allows you to import more than one image at a time. However, just like each of the other media types can be controlled, the user must have permission to use this feature.

Select the parent album for the upload to go into and then the other module features that will apply to all the imported media. Then choose your import method.

Files to upload

Select up to five files to upload. These can be of any Acidfree recognized media type (most images, videos, .zip, .tar.gz, .tar.bz2). Make sure the max size of each individual file is not greater than your php.ini max filesize and that the sum total is not more than the max post size setting. Archives that include directories will be imported all the files and directories with directories creating albums.

Import local

Select a path local to the server that it can import files from. If you wish to include the full file structure, you can select the import subdirectories checkbox.

Editing content

Here the form is very similar to the add content form, but there are a few different options.

• Albums: you can choose a thumbnail from an item in this album to appear as the album thumbnail or you can have Acidfree choose a random one.
• Photos: you can rotate your images by selecting clockwise or counter-clockwise 90° rotation. Or, if your images are marked with the orientation EXIF tag and you have exiftran installed and configured, you can select the automatic rotation option.

Once again there are other fields from other modules that you can fill in here too. Knock yourself out. At the bottom of the form is a delete button. If you use this button to delete the item, it will delete the item permanently. If the item is an album, it will delete the album AND all its contents. If the item is in multiple albums, it will delete it from ALL the albums.

Album contents

Here is a different view of the album where you can do mass edits of all the items in it. Most of the options on the individual edit page are listed here in a tabular format. For all individual edits, you can simply do your edits and hit submit.

In addition to the individual edit options, there is a column of checkboxes on the left. You can use this column to move, copy or delete items. If you copy an album, it will copy the album and all of its contents to the new parent. If you copy an item, it will update the parent album field for that item to make it appear in both albums. If you move an item, it will move it to that new album. If you delete an item, it will remove it from the current album (and if it was only on one album, it will delete it permanently.) So be aware of the awesome power the album contents view offers and don't shoot yourself in the foot.

Advanced topics

Acidfree Inline Filter

Acidfree offers a built-in inline filter for inserting Acidfree elements into the body of other elements. This allows you to write a story about your latest camping trip and include small photos from the trip in with your text. First, you must enable the filter for each input type (html, php, etc.) at admin -> input types (admin/filter) and clicking on 'configure' for each input type you want to have [acidfree:nnn] tags enabled for. Then make sure the 'acidfree inline filter' is checked and hit save. Now you can add [acidfree:nnn] tags in the body of other elements.

There has evidently been some confusion about what the nnn in the tag is. The nnn stands for the node ID of the Acidfree node you want to appear.

It is possible to change the way the [acidfree:nnn] tags look by adding a few name/value pairs. Note that any value that has spaces in it must be quoted either with single quotes ' or with double quotes ". Currently, the choices are:

• title: use this string as the caption (Note that you can have the node title be the default caption by modifying the setting in admin/settings/acidfree)
• align: {left,right}
• size: {M, WxH} where M=max dimension and WxH=WidthxHeight
• link: 'none' or relative or absolute url e.g. http://www.google.com or node/59. If set to none, thumbnail will not be a link
• popup: any value. If set, it will cause the link to be a popup link
• style: CSS style information for the image
• class: additional class for the image

Examples

• [acidfree:1234 size=300 align=right] - right aligned thumbnail of node 1234 with max dimension of 300 pixels
• [acidfree:4321] - left aligned thumbnail of node 4321 (default thumbnail size)
• [acidfree:3241 align=left size=320x240] - right aligned thumbnail of node 3241 with size = 320x240
• [acidfree:3241 title='This is a different title' size=320 popup=true link="http://mysite.dom/"] - left aligned thumbnail of node 3241 with a title set, size = 320x240, link pointing to mysite.dom and target=blank_ set in the anchor
• [acidfree:3241 link=none class='my-image your-image' style="border: 2 px grey inset;"] - left aligned thumbnail of 3241, default size, class set and new style info

Themes

Like the rest of Drupal, Acidfree was designed with theming in mind. Almost all of Acidfree drawing routines can be themed.

The two main drawing routines theme_acidfree_print_thumb_{$class} and theme_acidfree_print_full_{$class} are defined for each class (currently album, photo and video).

Let's assume you are writing a new theme called 'blowfish.' The first thing you should do is copy the acidfree.css from the modules/acidfree directory into your theme directory. This copy in the theme dir will override the default css file. Feel free to modify it to suit your theming needs. Then in your blowfish.theme file, you need to define each of the default Acidfree theme functions you want to override. The current list of themeable functions in Acidfree are as follows:

Of all of these, the most common to theme are theme_acidfree_print_thumb_album, theme_acidfree_print_thumb_photo, and theme_acidfree_print_thumb_video. Some people may want to theme theme_acidfree_print_full_album, but really all it does is draw the thumbnails of its contents in a table. So most people can get what they want simply by modifying the CSS for the rest of the drawn elements.

So you will need to create the following functions in your blowfish.theme file:

Keep in mind that a lot of the theming can be done simply by changing the CSS of the existing theme. You can do this by copying the acidfree.css to your theme dir and then modifying it. One other advantage of this is that your theme will not be overwritten when you upgrade Acidfree in the future.

Frequently Asked Questions

I am not going to be presumptuous and just fill in the FAQ with all sorts of questions that I think people might ask. All of these questions are things people really have asked.

Frequently Asked Questions

Why can't I add a (photo/video/album)?
Why don't the "add photo/video/album" links show up?
Where did the name come from?
How do I install Acidfree?
Do I have to have mplayer?
Does Acidfree work with module X?
Can you add X feature to Acidfree?
Why don't video uploads work?
Why doesn't mass import work?
I am getting errors like .... What does this mean?

Frequently Given Answers

Why can't I add a (photo/video/album)?

• The most common cause of this is because you don't have permissions. Make sure the 'Create Acidfree ...' boxes are checked on the 'access control' page (admin/access).
• Another common problem is misconfiguration. I am the first to admit that Acidfree is not mere child's play when it comes to configuration. It is a complex system and requires _some_ thought to configure correctly. Your best help here is visiting the acidfree/test page (as user admin) to see what it tells you about your current setup.

Why don't the "add photo/video/album" links show up?

• The most common cause of this is because you don't have permissions. Make sure the 'Create Acidfree ...' boxes are checked on the 'access control' page (admin/access).
• You aren't logged in as a user who has permission to add stuff.

Where did the name come from?
See Overview for some history.

How do I install Acidfree?
See Installation for detailed instructions.

Do I have to have mplayer?
No. Mplayer is only needed if you want it to automatically extract the first frame from uploaded videos. Note that this requires shell_exec permissions for php. And mplayer may not be installed on your server, etc., etc. No, I will not install it for you.

Does Acidfree work with module X?
Acidfree should play well with others. If it doesn't, please open a bug and let me know. It has been tested in a wide range of setups by various users and myself, though it is impossible for me to test every situation.

Can you add X feature to Acidfree?
It all depends on how much I like it. I want to KISS (keep it simple stupid) and avoid bloatware that does everything under the sun (think Gallery2). This is something I wrote for personal use and so my mother-in-law would be able to use it also. So I want it to look nice and be simple to use and it MUST be simple to use or I will be spending my weekends as tech support for my mother-in-law.

The other thing you might want to consider is coding up you feature (or getting a friend to do it for you) and then submitting a patch. I don't have much time for real active development these days. Work is stressful, the kids are time consuming, and I don't get to spend as much time with my wife as I would like. So you might think about writing the feature yourself.

You might also consider donating a small sum of money in hopes that it might lend some motivation to me to get your pet project done. Now take note that I do not work on Acidfree for money—I am forbidden to do so by my employer. But if you happen to give me some money and I happen to implement some feature you wanted, everyone is happy.

Why don't video uploads work?
The most common problem here is a too small upload_max_filesize or post_max_size. While you are at it, make sure you fix memory_limit to be >=32M.

Why doesn't mass import work?
The most common problem here is a too small upload_max_filesize or post_max_size. While you are at it, make sure you fix memory_limit to be >=32M.

I am getting errors like .... What does this mean?
Search for those errors in the bug listings (make sure you search through the closed bugs as well). Don't automatically assume you are the first one to ever see this error and immediately open a bug. However, if after searching for the bug and finding none others, feel free to open a bug. Make sure you paste in the exact error messages and tell how to reproduce it. If I can't reproduce it, chances are, it won't get fixed.