| TOC |
|
| TOC |
| TOC |
The Shoot'n'Share(tm) Digital Image Publicizer is a program designed to make it easy to host a web site wherein picture albums can be displayed. Multiple "members" are supported, allowing one server to serve images from many artists, each with control over his or her own works. Images can be manipulated via the web, and the server supports upload via email as well. In addition, the general public visiting the web site may leave comments on individual images, forming a sort of chat board. They can also do searches for words in image descriptions and chats. The programs run equally well under Linux or Windows, requiring only minimal additional software besides a web server, all of which is available open-source as well as being included. (The code can be made available under MacOS as well, if requested.) A sophisticated software architecture ensures that the computational resources used by the server are low.
This document describes the interface as seen by members. It explains each web form, the format for email submissions, and what members with administrative privileges can do that unprivileged members cannot.
| TOC |
Members need to understand very little about the architecture and operation of the system. However, there are a few aspects of the architecture that affect how the system works of which members should be aware.
The system consists of three major parts: A set of CGI scripts for a web-based interface (including members changing the images, public searching, and public chatting), a script triggered from "cron" that adds images to the database that are received via email, and a script triggered from "cron" that updates the website based on changes from the first two scripts.
The data for the scripts is generally in four major places: The "ORIG" directory holds all the images, chat data, control files, logs, and so on. The "ROOT" directory is in the web server's normal namespace; it's what normal viewers peruse. The scripts directory holds a collection of CGI scripts, most of which allow members to update their own web pages and allow administrators to do administrative operations, one of which allows viewers to add "chat" comments to images, and one of which allows viewers to search for keywords. The final location is the program holding the main body of code to run the server, including all the scripts, bundled into one file.
Members should note, particularly, that changes are made to a repository ("ORIG") that is not directly visible on the public web, with changes being propagated in batches ("rebuild") to the public web in batches. These updates are deferred until some minutes after the repository has finished being changed. So as long as the member keeps working on images, the updates are not performed. By default, changes made by members will appear on the public site five to ten minutes after the member submits the change. Changes will appear in the editing interface immediately. By default, public comments on images will appear about a minute after the comment is made.
This delayed update allows for all pages served to the public to be static. It also allows the same "rebuild" to be propagated to multiple servers for high-traffic sites. Finally, it makes administration easier, as code can be updated and other administrative tasks can be performed without affecting the public's access to the site. It also aallows multiple sites in multiple languages or targeted at multiple browser quirks to be supported easily.
This delay has a few visible effects. When a new image is added, the thumbnail and size information is not determined until a rebuild is run, so a "broken image" icon will display for the thumbnail until the image is visible to the public. When an image is deleted, it will still be visible for a time, and it can be "rescued" by the member. When an image is added that is corrupt or in a format that the program cannot handle, a mail message will be returned sometime later to the member informing of the problem, since the image file is not actually examined until thumbnails are created.
On the other hand, since all changes are made solely to the repository, a member can create a directory and add a number of images to it without waiting for the directory to be propagated to the public web site.
The static web pages are build by scripts that are easy to recode, to support different looks, different (human) languages, and so on. All web pages seen by non-members are generated by scripts designed to be easily modified.
| TOC |
The following files are created in the ROOT directory being served. The ROOT directory is often one level down from the document root of the HTTP server, but it need not be. The ROOT directory is the directory containing the page listing all the members. The files have specifically been named to allow a member to publish the member's directory, a specific subdirectory, or a specific individual file with an intuitive name.
- $ROOT
- The top-level created directory.
- $ROOT/index.html
- Top-level index file, listing all the members.
- $ROOT/index[0-9]*.html
- Top-level index file continued.
- $ROOT/recent.html
- First pages of the chronological index over all members. index.html should have a link to this.
- $ROOT/recent[0-9]*.html
- All pages of the chronological index over all members. They list entries in reverse-chronological order, with each entry showing the thumbnail, title, penname, date, and time. The thumbnail and title links to the .html file. The penname links to the member's .html file. The date links to the first date page with that date.
- $ROOT/$PENNAME/index.html
- The member's main page. It's named "index.html" to allow a member to give $ROOT/$PENNAME as their "home page". It shows the penname, title, and notes. It may have a link to the alphabetically next and previous members (if any). It may have a link to "member login" for the member's editing. It has a link to the per-member chronological index. It has a link to the per-member chat index. It shows the top level of directories and photographs.
- $ROOT/$PENNAME/recent[0-9]*.html
- The per-member chronological index. Just like under $ROOT, only for files of this member only. The "date" link links to the per-member date page. Note that there are no chronological indicies for subdirectories of a member's directory.
- $ROOT/$PENNAME/chat[0-9]*.html
- The per-member chronological index based on most-recent-chatted times.
- $ROOT/$PENNAME/index[0-9]*.html
- The per-member by-directory alphabetical index. "index.html" is the first entry. The same structure is repeated in each subdirectory of the member's directories. Each page has links to the member's main index, alphabetically previous and next pages, and "up" to the parent directory of this directory. Each subdirectory has a directory icon, the directory name and title, all of which link to the subdirectory. Each image has the same structure as in the by-date indicies.
- $ROOT/$PENNAME/some/path/index[0-9]*.html
- As above.
- $ROOT/$PENNAME/some/path/$imagename.html
- Each image has an associated imagename+thumb.jpg, imagename+web.jpg, and imagename.html file. The html file shows the penname (linked to the member's main page), the title and web-sized thumbnail (both linked to the full-size image), the notes, the chat file (if any), and then a form for adding to the chat file (if allowed). The EXIF data is also included, if present and enabled by the member.
| TOC |
This section documents the scripts available to normal (unprivileged) members.
The member login script takes a penname, a password, and an optional adminname. If penname or password is missing, then the CGI script returns a form with the fields to be filled out. If an invalid password is supplied, the script pauses for several seconds before returning the form, to make dictionary attacks harder.
If the penname is supplied and the password matches the penname's password, or penname and adminname and password are all supplied and the password matches the adminname's password, then the login is successful. In this case, a new page is returned. The start of the page has the member editing links, with a CGI link to editmember. The end of the page has a list of sections, with one link for each file or directory in the member's directory tree. Additional links to scripts will be present if an adminname was provided, or if the member name provided has administrative privileges.
Each entry in the file list is either a directory or an image file. Directories have the following links: "New Sub Directory", "Edit this directory", "New Subdirectory", "New Image", and "Show only this". Images have only the "Edit" link.
(All scripts accept the penname, password, and adminname arguments, performing the same checks as the login script. All links have the given arguments appended to them, and all forms have hidden fields with those values filled in. Hence, each member needs only log in once.)
The "edit member" section allows changing the password, the title, the email address, the notes, and the EXIF field choices. If the form was generated via administrator login, all fields are available for editing except the penname, including administrative privileges, quota, etc.
The EXIF field choices determines what fields from the EXIF data in a jpeg image is shown. The list is all known EXIF fields, and those checked will be displayed on the individual image pages if they're present in the image. Most digital cameras add at least some of this information to the images, but many editing programs will destroy this information. The complete collection of EXIF information is extracted from the image when the thumbnails are generated, which generally happens only when the image is added. Changing checkboxes here therefore will update web pages as they're rebuilt. By default, all web pages are rebuilt each night, so changes here might take as long as a day to be reflected on the web pages. An administrator can rebuild the web pages on demand.
The "Normalize" checkbox will cause new images added by this member to have the contrast of the thumbnail and web-sized images normalized. (The original image is never modified by the server.)
The newsubdir script is responsible for creating a subdirectory of a given directory. It prompts for the directory name, its title, and any notes. If all arguments are kosher, it creates the directory, then returns to the member's top-level login script.
The editsubdir script is responsible for editing a subdirectory's information. It prompts for a new title, notes, and whether or not to keep the directory. If the "KEEP" checkbox is cleared, the directory is deleted (in a recoverable way) upon the next rebuild. (Note that this also gives the member about five minutes to change his mind, recovering the directory without administrative action.) If all arguments are kosher, it modifies the directory, then returns to the member's top-level login script. Note that the directory is not actually deleted, but rather simply moved out of the directories manipulated by the scripts, so the webmaster can recover an accidentally-deleted directory by logging in to the server.
The newimage script is responsible for adding an image to a subdirectory. It prompts for Title, Notes, and whether or not to show the image in indicies, whether or not to allow the public to comment on this image, a marker for whether to rotate thumbnail images as they're generated, the image file name, format, and contents. Currently, only JPEG, TIFF, and GIF are supported, but this is relatively easy to extend if needed. The script, after adding the image, returns to the member's top-level login script or to add another image. If the image is not shown in indicies, it can still be accessed via the full path to the HTML file generated, but "next" and "previous" and the alphabetical and chronological indicies will skip this image. A "rotated" image rotates the thumbnails without otherwise affecting the original image, allowing a turned camera to be "corrected". (Note that the server never modifies an original image. Only the thumbnail images are changed.)
The name for an image file must start with a letter or a digit. It may contain only letters, digits, hyphens, spaces, and underlines.
See the section on email access for another way to create new images.
The editimage script is responsible for modifying the description of an image in a subdirectory. It prompts for Title, Notes, Chat field, Chat-OK, Show in indicies, and Keep. The script, after modifying the image's information file, returns to the member's top-level login script. If "Chat OK" is unchecked, no further changes to the chats will be permitted to non-members. If "Show" is unchecked, the image will be removed from the indicies without being otherwise affected. If "Keep" is turned off, the next rebuild will delete the image (in a way that an administrator can recover it). Note that members should avoid changing the "chat contents" field if they don't understand the format. Note too that there is no way to change the actual image or the rotation of the thumbnails; instead, delete and re-add the image.
It is possible for a member to add images to an existing subdirectory via MIME email, that is, via "attachments" to messages mailed to the server. The administrator will tell you the address to use. The format of the mail message is simple. Currently, the library being used to parse the mail has a bug that makes it slow for large images, so try to keep mail messages down to one megabyte or one image, whichever is bigger.
To add an image, the member addresses a mail message to the server's email-acceptance address, something like "portfolio@example.com". This email message contains a set of "name=value" lines, one per line. If a "value" takes more than one line, it can be continued on the next line, indented. The self-explanatory names of the fields are as follows:
OP - "addimage", saying what operation to perform.
NAME - the name of the file to be stored on the server, optional and taken from the name of the file attached if possible.
TITLE - the title to be shown on web pages.
NOTES - the notes to be shown on web pages.
PENNAME - the name of the member (the same one the member logs in with over the web).
PASSWORD - the password of the member (the same one the member logs in with over the web).
DIRECTORY - the path to the directory, defaulting to the top-level directory.
DATE - as YYYY/MM/DD, optional.
TIME - as HH:MM, 24-hour clock, optional.
FLIP - "cw" for clockwise, "ccw" for counterclockwise, optional.
CHAT - 0 or 1, 1 to allow chats, optional.
SHOW - 0 or 1, 1 to include in indicies, optional.
Each attached image file is examined for name and type, and added to the repository with the parameters from the textual part of the message. Adding a blank line after all the parameters will ensure that any signature is not interpreted as part of the commands.
As an example, to add an image of my cat to the "Mine" directory in my "Pets" directory, I would generate an email message as follows with "Cat One.jpg" attached:
To: portfolio@images.example.com From: dnew@example.com Subject: Add my cat penname=Darren password=Secret title=My Cat directory=Pets/Mine notes=This is a picture of Kitty, my cat. He's siamese, and therefore quite loud. Please tell me what you think! This was taken with a Sony digital camera. chat=1 flip=ccw
When the server processes this, the member will receive (at the member's registered email address) a message with the subject "Re: Add my cat" that will describe whether or not the message was accepted, and if not, why not. Had multiple images been attached, they would all get the same notes, title, directory, and so on. However, this would be acceptable if they had different file names.
| TOC |
There are a number of administrative scripts available when a member logs in with administrative privileges. These scripts are described here.
If an administrator logs in on behalf of another member (i.e., uses the "adminname" field on the main login page), the administrator may "fixup" that user. This involves going through all the stored information about images belonging to that member and verifying that it is correct. Fixing up "hard" involves discarding all cached information and thumbnails, which may cause a significant delay upon the next incremental or full rebuild. If a collection of images is added manually without any information files, or one is copied from a PicEdit repository, a "fixup" will ensure it's ready to be used with this program. It is also necessary if the administrator ever receives an email from the member login script indicating an inconsistency was detected. A "hard" fixup, deleting the thumbnails, is necessary for some configuration changes to take effect, such as a change in the size of thumbnails. Under normal operation, this should never be needed.
If an administrator logs in on behalf of another member (i.e., uses the "adminname" field on the main login page), the administrator will also have additional checkboxes on the "Edit Member" page, which will either "freeze" the member or grant the member administrative privileges. If frozen, the member will be unable to log on, preventing any changes (beyond adding chats) to any images.
If an administrator logs in under his or her own penname, additional choices are available. The system's logfile can be viewed, or viewed and rotated (stored under a different name in the log file directory). A new member can be added. An incremental, full, or HTML rebuild can be scheduled for the next time the script runs, regardless of whether there were any changes and regardless of how long ago those changes were made.
| TOC |
The author appreciates the valuable comments of Tor Amundson, Dale New, Jerry Brown, and Wen New.