ClariNet PhotoGrab Templates

If you are using ClariNet's photograb perl script to extract incoming photos on your system, you want to be able to insert the photos, captions, headlines and other materials into an attractive looking web page.

To do this, you can edit a template file that lets you build the HTML you want. The HTML can then be inserted into a web page using the "server side include" mechanism of most web servers, assuming it is turned on. Your webmaster needs to configure the server to do this if it is not already configured.

Setting up the Page to include the HTML

You must pick a page in which you want the live photo and text inserted. This may end up being your home page. Many sites like the idea that a live picture, changing many times per day with a hot photo of a current event can make a web site a more dynamic, interesting place. If people come to a web page and always see an interesting photo of a very current news event, they will really get a sense that this page is doing something for them, and be drawn into the news linked from the photo.

ClariNet's goal is to help our subscribers make their systems, news servers and web pages more interesting for their users, to keep them coming back and keep them pleased with being a user on the system.

Consult with your webmaster, but chances are this means the page that inserts the generated HTML needs to have the extension ".shtml" instead of ".html" This can complicate matters if the page is to be the master home page, normally known as index.html -- check with your webmaster.

Pick a spot in the page where it would be suitable to include the photo. If you plan a photo and a caption, this will take up the whole width of the page. Photos usually are about half the width of a typical web browser's page, and the caption or headline take the other half. So just find a place where you can insert a box about 200 pixels high and the full width of the page.

If you're being more creative, and want to put the photo and caption in a vertically stacked table, they will only take half the page and you can mix in other items and text.

At the place where you wish to insert the HTML with the photo etc. include a string like this:

<!--#include file="claripic/main.txt" --> 

with a path to the HTML file (it ends in .txt but it is really html) relative to your page. This assumes you are inserting the main HTML page generated by photograb. If you are generating multiple pages, the location may differ.

If you are not at the root of your server, you have to use a virtual path, as in:

<!--#include virtual="claripic/main.txt" --> 

Editing The Templates

The template will be found in a directory in your web server tree, usually called claripic.

The "main" template (usually all you use) is called main.template. We provide several sample templates and you and your webmaster can select the one you like best, or write your own to suit your tastes.

The template is actually a Perl program but you don't need to care much about that. You will be editing the part of the file between the two lines with "END_HTML" on them.

This part is HTML with some very minor tweaks we will explain here.

HTML differences

The most important difference is that you can insert variables into the text. These will be strings, or perhaps you would prefer to think of them as "macros" which have been calculated by the program that extracted the picture. They can be inserted right into your text. For example, if you have the string $headline in your HTML, the actual headline of the photo story will be inserted there. Below we describe all the variables you can insert.

Now, because the character "$" has become special, you need to know that a few special characters must be prefaced with a backslash (\) if you want to use them in your HTML and get the literal character out. These are the dollar sign ($), the at-sign (@) and of course the backslash itself. (To get a single backslash, you must type two.)

Thus to say "The cost is $5" you must write "The cost is \$5" instead.

Now it turns out there is actually the ability to do a tremendous amount here, and if you know your Perl, you can do that, but mostly you can just edit the HTML to provide a nice layout for the components extracted from the picture.

Three Traps

1. You might forget to escape one of the special characters, causing the program to issue a warning or to give you null output.
2. If you goof, and edit the perl part so that there is an error in the program, the system will use the default template built into the photograb script. If the HTML suddenly changes you will know why! That's why it is good to test a new template after you change it.
3. You might forget the editing the template does not cause new HTML to be generated. To see the results, first photograb must run on a photo and then you must load up the web page that includes the output of photograb. You can run it manually if you are set up to do this or you can wait for a new photo.

The Variables

Here are the variables you can insert into your HTML

$caption

The caption of the photo. Usually several lines long. Clever perl programmers may do modifications on it to insert formatting, but you can just insert any formatting you want around the caption.

/$image_dir/$imfile

The URL of the saved image file on your system. Ie. to make an inclusion of it, you usually say <img src=/$image_dir/$imfile>. As you might guess, $image_dir is "claripic" and $imfile is the name of the JPEG in that directory.

$headline

The headline of the story with the photo. Sometimes the photo will be old and the caption thus old, but the story will be fresh and so the headline is always worth having.

$attributes

If we have them, these are the HTML attributes to include in your <IMG> tag. This string will be something like "width=200 height=150". It is very handly to insert this into an <IMG> tag because it lets the web browser display text even before the picture loads.

$image_width

If we have it, the width of the picture in pixels. Null if we don't have it.

$image_height

If we have it, the height of the picture in pixels. Null if we don't have it.

$which

The tag for this picture, normally "main" -- if you are handling multiple pictures, you will use this tag anywhere you refer to something that might be different from one picture to the next.

$message_id

This is the message-id of the news article with the small photo. This is what you use in a "news:" URL to refer to the story using the Netscape or other browser newsreader. To use such a URL, users must have configured netscape to know about your news server, or it must have the default name of "news" which is usually does. The "<" and ">" are stripped off the message-id, which is what you want for "news:" URLs. Unforunately, the message updating may make this URL no longer valid by the time a user clicks on it.

$large_message_id

The message-id of the news article with the large version of the photo. you can use this to refer users to a bigger, high resolution version of the small picture you are putting on your web page. Again they must have their browser ready to talk to a USENET news server.

$head{"field-name"}

You can actually refer to any field from the header of the USENET message that contained the photo. For example $head{"newsgroups"} gives you the newsgroups list for the article. The field names are always all lower case. Multi-line headers are joined into one line.

@article_body

This is the text, in plain unformatted ASCII, of the article with the story. You won't usually use this. It can be quite large, and needs to be formatted or surrounded by <PRE></PRE>

$bodlink

This special variable is either "A" if the photo had a story with it or "NOTALINK" if the photo had no story with it. This is useful because you may not want to bother offering a link to the "real story" if there is no real story. Sometimes we ship photos with just a caption and no story, just as newspapers often run photos.

Here's the trick. You can start a link with <$bodlink instead of <A and follow through with the href= tag and other tags you need for the link. If there is a story, your link will be real. If there is no story, it's an unknown html tag -- and so there is no link. You close out the link with </$bodlink>.

$newsgroup

The first newsgroup on the newsgroups line. This is usually not clari.news.photos, even if you extract from there. You can use this to generate a URL of "news:$newsgroup" to take users to the newsgroup with this story. The variable $spaces_group is similar but has spaces after the dots in the name -- which means it can be wrapped around line breaks, which you sometimes need.

Sample Template

Here is a nice template that lays out the headline, picture and caption as a 3 column table, with the picture in the middle.

<TABLE COLSPEC "L20 L20 L20"> 
	<TR> 

	<TD> 
	<FONT SIZE=+2><STRONG>Featured story</STRONG> 
	<HR> 

	<$bodlink href="news:$message_id">$headline</$bodlink></FONT> 
	</TD> 

	<TD> 
	<$bodlink HREF="news:$message_id$"> 
	<IMG BORDER=2 $attributes SRC="/$image_dir/$imfile"></$bodlink> 
	</TD> 
	<TD>  
	<FONT COLOR=darkred>$caption</FONT> 
	<BR>[<a href="news:$large_message_id">Larger Photo</a>] 
	</TD> 

	</TR> 
	</TABLE> 

Testing

To test a new template, you will need a photo story with a small photo in it.

Go to the newsgroup from which you are extracting photos, such as clari.news.photos, and find a small photo story. Small photo stories are about 10K in size and have "[Sm..." at the start of their Subject: line.

Save one of these away for testing, or always extract the newest each time, as you like. You can save in a newsreader or go directly to the directory (usually /usr/spool/news/clari/news/photos) to get the file.

Find out where your sysadmin has installed photograb, and if you have permissions to run it. Your admin may also make a special version for testing that does not write on the live files, which is a good idea. You can do that yourself by using the "dir=." option to photograb when you run it, to have it read the template from the current directory and write its picture and main.txt file there.

photograb dir=. <sample_photo_article 

Notes on synchronization

If you plan to provide links from photos, captions etc. to "news:" URLs with the message-id of the story or large photo story, you must beware of potential synchonization problems. If the web page and the news server are not in sync, a link on the web server may end up pointing to a story that has not yet arrived, or possibly been updated (deleted and replaced with a newer version.)

If you want, instead of linking to the story itself, you can link to the newsgroups it is in, either directly to clari.news.photos, for example, or to the main newsgroup of the story (provided to you in the variable $newsgroup). This will take the user to a menu of the related stories, including that story as one of the most recent. Such a link is a pain if the goal is to read just the story, but it is assured to work and sometimes leads to more interesting material.

ClariCGI

An ideal way to provide a link off the photo is with ClariCGI. You can use this in several ways to assure the link always works.

For example, a ClariCGI link of the form /cgi-bin/claricgi/?;g+;m:$message_id will link to the message-id provided, but cause it to search for an update under the same slug if that message isn't found.

Another way to do this is to have a ClariCGI query that will return the same story used to generate the photo. If you are always using the latest photo from clari.news.photos, then the simple URL of

/cgi-bin/claricgi/?;g:clari.news.photos 

will always return that latest photo. Of course it only works for users enabled for ClariCGI on your site, and not outsiders, which is how it should be.