Use-Case Guide

Browsing pictures

• Get the pictures off your media in your usual way (I reccomend USB CompactFlash card readers, but this will depend on your camera and OS).
• Make a .tar, .tar.gz, or .ZIP archive out of your pictures. Windows users will probably have access to WinZip and can easily make a .ZIP file. Unix users can make a tarball out of it. It's egregious that you have to do this, but it's a technology limitation with the way web servers and browsers currently work.
• Log into your AreaJ account if you haven't already. Click the "Upload Files" button in the footer area.
• Enter at least a unique caption so that your images can be easily searched for after you upload them. The caption doesn't have to be permanent, but should be unique - I would suggest some keyword related to the pictures and then a number indicating the date, like 'geneva01012001'.
• Don't bother marking the pictures private unless you have something in there that you don't want your Mum seeing.
• Click the "Browse..." button (or whatever button your browser puts next to the "Select File:" field.
• Some browser (noteable netscape) will have an unreasonable file filter (like *.html) set in the upload panel that opens up... you may have to set it to "*" in order for the file browser to show the .tar, .tar.gz, or .ZIP archive file that you want to upload.
• Select the archive file that you created earlier and click ok.
• Click "Upload" on the AreaJ Upload form.
• Wait while your pictures are uploaded to the server, added to the system, and converted to thumbnails.
• When it's done, click on "Member Search" and enter the caption you specified ('geneva01012001' in my example). Leave the table dimensions at about 5 x 1, but turn off EXIF text for the moment (takes up too much room). If you turn off image editing except for selection editing, you should be able to set the table dimensions to 5x3 or more. This will get you more images on the same page, making it easier to comprehend the whole image set. Click "Get Images".
• You should see thumbnails of all your images in the result set. You can use the 'Next' and 'Prev' buttons to navigate through them.
• Using the "Select" checkbox directly under the images, pick the images that need to be rotated 90 degrees to the right. Click the checkbox for each one, and then go to the next page and do the same until you reach the end of the set. Once you've got them all selected, Use the "Selection" box at the bottom of the page (doesn't matter which page you're on) and change the "Rotation" drop-down to "90". Click "Perform". The images you selected should now be rotated. Tip: if you've got some that need to be rotated to the left, do the same thing for those images, and choose the "270" rotation setting. Use the "Clear Selection" link to unselect everything.
• Using the same selection procedure, select all the images that you don't want to keep. Click the "Mark For Deletion" link in the "Selection" box. This doesn't delete the images, but it does mean that they won't show up in searches that specify "Non-Deleted Images Only" and you can delete them, if only to save the space and clutter, by using the "Delete Files" button later. If you mark something for deletion and then actually delete the file, it will still exist in the original archive file that you uploaded (and that should still be available to you as a download link on the "Upload Files" page). If you'd like to eliminate the files just marked for deletion from view without deleting them, you can go back to the search page and perform the same search as before (making sure that "Non-Deleted Images Only" is selected). To totally expunge a picture from the disk, you will have to delete the archive it came in - use the uploads page for that.
• Depending on your pictures, you may want to sharpen all or most of them. My experience with digital cameras is that they almost always produce an image that can benefit from at least a one-stop sharpen filter. The resizing operations involved in the production of thumbnails often makes the image a little fuzzy as well, necessitating some sharpening. You can select just the ones you think need sharpening, or select them all using the "select all" link, and then set the sharpening to +1 (or whatever you feel is appropriate).
• At this point, you probably want to edit individual images for brightness, since this tends to vary a lot by picture. To do this, go back to the search page, turn the Selection setting to "Don't Show Edit Links", and then turn on at least the "Images" editing features. At this point you might also want to set the "Post Edit Refresh" drop-down to "Image". This will allow you to immediately see the results of your edit without requiring a page refresh, which tends to interrupt the creative process. Some browsers (Netscape) don't always deal well with this option, however.
• Once you're set up for individual image editing, you should see hue, saturation, brightness, and sharpen controls under the image. For each image, set the brightness to the level you feel is appropriate. Don't worry about the fact that you've done this after doing the sharpen filter; the actual operations are always performed in the following order: resize, adjust (hue, saturation, brightness), sharpen. (Purists will note that this is slightly wrong as well; for best results, the resize should come before the sharpen - however, we always resize first to reduce the amount of CPU load necessary for subsequent image manipulation. If you care, use PhotoShop instead.) Every edit you make is stored permanently and will be applied to the image in any size that it is viewed.
• Once you're satisfied with your set of images, you'll probably want to sort out grouping. In my experience, I rarely get a CF card full of just one type of picture - usually half of it are family pictures and the other half is pictures of my vacation in Geneva, or somesuch. But everything is captioned with the same descriptive keyword (in this case, 'geneva01012001'). This is easily addressed. If your camera date was set, every image has been tagged with some EXIF information, one bit of which is the date and time the picture was taken. If in the Search page you chose to order by Date, your pictures should already be chronologically ordered. (The search will in any case attempt to use the last component of the filename as the final search constraint, so even if your pictures are all dated '0000-00-00 00:00:00' they should at least appear in chronological order, assuming that your camera stores files in a sortable form - usually cameras store digital images in numbered files, which means they should appear chronologically even though no dates are set on them. But I digress.) Turn Selection Editing on again, and select the subset that needs to be differently captioned (in this case the first half of the pictures, the ones with family in it instead of the Jet D'Eau), and using the field next to "Add Caption To Selected" in the Selection box, enter the appropriate caption (in my case 'family01012001'), and add the caption to the selected set using the "Add Caption To Selected" link. Then, keeping the same selection, remove the 'geneva01012001' caption from the same set, by entering 'geneva01012001' in the field and clicking the 'Delete Caption From Selected' link.
• Now that you've got two (or perhaps more) groups of fully-tweaked photos, you'll probably want to add a caption to each picture. First, turn the unlabelled checkbox to the left of the caption field to the unset position - this checkbox, when turned on, marks an added caption as being indexable. 'Indexable' in this context means that the 'User/Caption' tree feature is aware of it. Most short tags that identify locations or people probably should be indexable, so that they may be properly grouped with others of the same caption using the User/Caption feature. Captions that are specific to a particular photo, however, such as 'Look at how much Uncle Jim can drink' probably should not be indexable. These non-indexable captions are considered 'story' captions. If one-off captions such as this are indexed, the User/Caption Tree feature becomes too cluttered - you get long lists of captions of individual photographs, when what you want is a set of terse captions that identify photos with a common theme (such as a place name or a vacation title). Note that setting a caption to be non-indexable doesn't keep it from being found using the Captions text area in the main search page - in fact, you want to be able to use the search page to find pictures captioned individually ("now, where *is* that picture of Uncle Jim getting really drunk at the family reunion?"). After the 'indexable' setting has been turned off, enter a descriptive caption and Click the Add link beside the field. Doing this will result in a 'story' caption.
• Now you'd like to send a single URL to friends/relatives with pictures from one or the other trip. To do this, go back to the search page and search for one caption or the other. Tip: if you've forgotten which caption you used, use the "User/Caption Tree" feature. Set up the search just like you want your recipients to see it - a large field of 5x5 thumbnails with captions beneath, a vertical sequence of "Small" icons with captions beside, whatever. Once you've set up the search to your satisfaction, Hit the "Generate Bookmark" link. This will make a bookmark appear that can be pasted into an email that when exercised by your recipients, will bring them to the page you were at when you clicked "Generate Bookmark".

Setting up slideshows

Login/Logout

A user should only request administrator priveledges if they are a designated administrator and they intend to do administration when logged in. To avoid possible misuse of the administrator priveledges, it is a good idea to not request administrator priveledges even if you are an administrator. In this way, malicious users should be unable to abuse the administrator priveledges of an administrator who has left him/herself logged in.

Once a user has logged in, the button should read "Logout <username>". Pressing the button will immediately log out the user.

Creating a user account with this feature is pretty straightforward; enter a name, an optional email address, and a password (twice) and a new user will be creted if the username is unique and the passwords match. New users by default are given a set of private images for demonstration purposes. The images are private by default so that zillions of duplicate images don't appear in general searches or the title page.

Search

User

The original image that you uploaded is where the real size resides. When you request images of thumbnail, small, or large size, the original image is dynamically scaled and the result is presented to you. However, the actual size of the original is unchanged - in fact, we never, ever modify the original file.

This option will gain you the most real estate if you turn it off.

You would probably choose "Viewer's Captions Only" if you've gotten in the habit of applying your own captions to other users' images. You might choose "Owner's Captions Only" if you're only interested in the captions that the owner applied to the image.

Ordering Randomly is mainly useful for slideshow presentations - a random permutation is applied to the result set such that the order will be unpredictable and hopefully interesting. The search criterion still apply; if you define your search criterion too narrowly you may still have too small a result set to be interesting.

Which setting you should choose depends on your values of the moment. If you're doing inital processing of raw images to get their rotation right, adjust their brightness a bit, and then sharpen it (for instance), then "Control Per Image" might make more sense since you know what you need to do for each image (even though it isn't the same for every image) and you don't want to waste time for interim changes to take effect. If, on the other hand, you're experimenting with effects, or just getting used to the behaviour of the controls, you might want to use "Immediate Reaction" to see what the effect of a given editing change is without having to always be clicking on the "Perform" button.

The calendars that initially appear depend on a number of things. If you entered a date in the "After Date" field of the search form, the calendars will be centered around that. If you haven't done that, then calendars centered around the current date should appear.

Dates for which pictures exist for the user selected should show up in a highlight color. Clicking on those dates will search for those images. Returning to the search page from those images, you'll find that the search page is set for your convenience to return you to those images. When searching for images from the Diary page, others' private images will not be shown, but if you are logged in, any images that are owned by you and are private will be shown.

It's a good idea to uniquely caption all uploads so that you can find them afterward. Depending on the date of pictures to find them is not a good idea, as your camera may not have it's internal date set properly, or it may have lost its date due to battery failure. Marking images private is another way to identify them after upload, if you only ever mark them private when you upload, then modify them to your satisfaction, then remove the private markings. This methodology, however, will tend to get confusing if you start keeping images private because you don't want anyone to ever see them (rather than just because you don't want others to see them until they're edited to your satisfaction). My reccomendation: use a caption, you can always remove it later.

Uploaded files are found in the uploads subdirectory of the users' areaj directory (which defaults to AreaJ::Features::areajRoot()/users/). This is worth knowing if you are also an OS user of the system that AreaJ is running on, if you ever want to use the images for other purposes than AreaJ.

After upload, the uploaded archive files are decompressed (the uploaded files can be found in a path something like AreaJ::Features::areajRoot()/<user>/uploads/<timestamp>/<uploadfilename.tar.gz>) into a files subdirectory of the users' areaj directory - something like: AreaJ::Features::areajRoot()/users/<user>/files/<archivename>;/DCIM/100Canon/<DSCN0596.JPG>. Those files are then added to the database, along with the captioning information.

The archive files that you've uploaded are listed by date and time uploaded at the bottom of the window; you can click on the links to download them again if you want - you can also click "Show" to go to a search results page showing just the images in that archive; in addition, you can permanently delete the archive and all the files contained within it, along with all the captions and other information associated with the archive from here.

If you attempt to upload an archive that will cause your total amount of space used to exceed your quota, behaviour will differ depending on the policy of the areaj site. AreaJ sites that enforce strict quotas will reject any upload that exceeds the user's quota amount, while non-strict sites will allow you to exceed your quota on your final upload. Non-strict is nicer to users because it won't waste their time; in order to reject an upload, a strict site actually has to wait until all the data is transferred, which for a large file can take some time.

• User's login identity
• A flag indicating whether the user may assume administrator priveledges
• The user's (encrypted) password - when a user is disabled by an administrator, this value is set to 'disabled', which can't be encrypted to, ergo the user can't log in.
• The user's email address
• The amount (in MB) of the user's quota.

When adding or enabling a user, the user's username will be randomly generated, and printed out for the administrator to see. You should copy this password somewhere to send to the user as it is the only plaintext record of the password, or you can immediately change the user's password, or eliminate it alltogether by disabling the user when you add them. The user will then not be able to login until their password is changed using the "Change Password" screen - which the administrator will have to do since the user can't login yet. If you're running areaj under https only, this should be relatively secure, though there is always the possibility of someone reading the users initial password over the shoulder of the creator/enabler. As a policy, it's a good idea to have users change their password as soon as possible. If you're not running over https, this potential security hole is probably the least of your worries.

An administrator cannot disable him/herself, or remove his/her own administrator priveledges. This is to ensure that there will always be a valid administrator in the system.

Deleting a user is probably not a great idea - it destroys the user, and deletes all of the users' files, database entries, and uploaded archives. It is almost always a better idea to merely disable the user; that way all of their images and captions remain in the system in case you ever need to recover anything.

The email address associated with a user becomes effectively public - so if you don't want your e-mail address public, leave it blank or use your favorite spam-filtering email address.

Disk quotas can be set here; Use 'NONE' if you want the user to have an unlimited quota.

Cache Management

Backup

Security

• When new users are created or enabled, a random password is generated for them and displayed to the administrator. This is insecure because it's displayed on a page that could potentially be left up or cached. It is probably better than initializing the users with an obvious password, however. If you're very security conscious, immediately change user passwords after enablement/creation - then only you will know what you typed in, and you can use your NSA-issued burn-before-reading, one-time-pad CD to send it to the user. Who will probably then change his password to 'password', or 'friend' (like hackers never read Tolkien, sheesh).
• AreaJ users' passwords are stored in MD5-encrypted form in the mysql database.
• Session information is held entirely on the server.
• Only one cookie is issued, and it expires when your browser exits.
• Because we're using cookies, the session id should never be logged anywhere.
• Administrators have to explicitly request that role when logging in if they want to change other users' information (including passwords).
• Part of the install process creates a new, pseudo-random password for the areaj user.
• I've tried to avoid global data in perl code.
• None of the above is going to give you anything like true security unless you're running all of this behind https. I made an effort to set it up so that you could just protect the sensitive pages (login, change password, manage users) behind https, but in the end, it's very difficult to mix frames, javascript, and ssl, so your best bet is to run everything behind https and deal with the slight performance degradation.

• Is the DB.pm file readable only by www-data?
• Do your areaj admin users have real passwords?
• Are you running behind https?

License

Author

Thanks