ClariCGI Template Predefined Variables

When a ClariCGI template executes, several predefined variables are created or updated for use by the template.

General Variables

All the configuration variables are available as variables to templates. Indeed, extra variables can be put in the ClariCGI configuration file to be available to templates as you see fit.

Variables defined in the configuration file are permanent and may not be changed by templates. If you want a template to be able to act like it can change one, it should refer to a variable you create on your own which is initially assigned to the value of the configuration variable.

See the ClariCGI configuration guide for a list of the standard configuration variables

Script_Base

The URL of the directory where the ClariCGI script resides. Other CGIs may reside here.

Script_Name

The URL of the ClariCGI script, without a query. Useful in generating URLs that will refer to ClariCGI and give it new queries. Always terminated with a slash, since all ClariCGI calls should have a slash after the CGI's name so web browsers do relative URL right. Because of this, you actually should not have to use this variable. Relative URLs, with no protocol or slash in front of them, should call back to ClariCGI automatically.

claricgi_version

The version number of the copy of ClariCGI that is running. Version 1.0 has the value of 100.

Does_Tables

This is null if the browser is one of those known not to handle HTML-3 style tables. Ie. it is null for Lynx, Netscape version 1.1 and prior. This is not a super safe way to do this test, but keeping a list of all the browsers that do handle tables is quite hard too. You may wish to use the HTTP_USER_AGENT CGI environment variable and match it against regular expressions to make this determination.

If the browser is one of those that probably handle tables, this variable will be equal to the HTTP_USER_AGENT CGI environment variable.

time_now

An ASCII version of the current time, in unix ctime() format.

raw_time_now

The numeric current time, seconds since Jan 1, 1970.

All Queries

The following variables are available during all queries. The provide the various parsed components of a query.

query_msgidquery

True if the query is a fetch-by-message-id

query_usenumbers

True if a newsgroup query should use article numbers in URLs of articles listed.

query_no_date

True of the "date-" flag was set on the query.

query_msgidslug

True if the "g^" flag was set on the query.

query_showlarge

True if the Showlarge flag was set on the query, enabling large photos stories to be seen. (Not implemented)

query_next

True if the Shownext flag was set on the query, requesting a next article button. (Not implemented)

query_previous

True if the Showprev flag was set on the query, requesting a previous article button. (Not implemented)

query_summary

True if the Showsummary flag was set on the query, requesting that menus include the summary header if present. (Not implemented)

query_personal_paper

True if this is a personal newspaper query, ie. if the "paper^" flag was set on the query.

query_wholegroup

True if the "whole^" flag was set on the query.

query_specific

True if the query is for a specific article, not a list.

query_artinline

True if the "inline^" flag was set on the query, or it is otherwise a request for a list of articles to be included inline rather than as a menu.

query_list_titles

True if the "list^" flag was set on the query, or it is otherwise a request for a list of articles to be offered as a menu, ie. a newsgroup query.

query_always_match

True if the "Always^" flag was set on the query, ie. that it should always try to match.

query_index

The query index value, as provided by the "v:" tag.

query_slug

The slugword as provided by the "slug:" tag.

query_generic

The generic argument to a query -- message-id in specific article queries, personal paper name in personal paper queries, and other future definitions.

query_pagetitle

Any title argument provided on the query with the "Title:" tag. Note that usually templates are provided this value with modifications in the Title variable.

query_text

The full text of the query.

query_newsgroup

The newsgroup in which the query is being done. Note that even with message-id queries a newsgroup will usually be provided, the first legal group in which the article is present in the history file.

Hierarchy Templates

Newsgroup Template

Suggested_Title

A suggested title for the page, suitable for the Title procedure call and inserting in HTML <H1> tags. For example, this title might be "20 most recent articles in newsgroup clari.foo" or "All (matched) articles in newsgroup clari.bar" etc. The suggested title is formed from what the user asked for in the query.

Title

This will be the title for the page requested in the query, otherwise it will be the Suggested_Title.

List_Style

This is the HTML list style recommended for this page. Usually this is "OL" for lists of the most recent articles, and "UL" for lists of the oldest or all articles. You can insert this in HTML list tags, or choose your own list style, including tables. See the headline menu template.

Numbers_Tag

If the query is supposed to use article numbers instead of message-ids to refer to articles, because the "number^" tag was set on the query, this will be the string ";n^" -- otherwise it is null. You can use this to build other group queries that appear on the page.

Needs_Whole_Link

This is true if a link to articles in the past is valid and requested for this page. Ie. even if the user requests such a link this will be false if the page already shows all the articles in the group.

Sample Group Template

The following template is simlar to our default Newsgroup template. You will note that this template is called for both inline and menu queries, and such templates have to test query_artinline and act appropriately.

<body bgcolor=white> 
{ title( Title ) } 
<h1 align=center>{Title}</h2> 
{ clari_logo; query_header; } 
{ # For inline queries, put a line before articles, otherwise start list 
  if( query_artinline ) 
        "<HR width=80% size=2 color=red>"; 
  else 
        %"<{List_Style}>"; 
  fi 
  # execute the query 
  query( query_text ); 
  
  %"</{List_Style}>" if !query_artinline; 
  %"<P><a href={Script_Name}?;g:{query_newsgroup};l^{numberstag}>View all articles in {query_newsgroup}</a></P>" if Needs_Whole_Link; 
  } 

Note the use of Needs_Whole_Link and numberstag to assure that the proper link to other stories is offered with the right query.

Menu of Newsgroups Template

Two templates are available here, to be defined in the configuration file. The master template controls the look of the entire page, and will contain a call to the list function usually with the query_newsgroup variable as an argument. The real control of individual elements comes from the special group_listing variable, which can be set in the master group_list template, or in general.

Inside the group_listing template you can use the following:

List_Newgroup

The newsgroup being listed

Group_Max

The highest article number in the newsgroup, from the active file.

Group_Min

The lowest article number in the newsgroup. Will be one more than Group_Max if there are actually no articles in the group. A brand new newsgroup usually starts out with a max of 0 and a min of 1. If the minimum is 0, then this is not a group, it's a hierarchy (as such this will only happen in a hierarchy listing)

Group_Flags

Any flags from the active file for the group. For example, this is "m" if the group is moderated.

Group_Read

Currently unimplemented, this variable will contain, when the user is using "newsrc' mode, the highest article number that has been shown to the user in past sessions, so you can calculate how many unread articles there are from Group_Max-Group_Read after checking if Group_Min is larger than Group_Read.

Group_Unread

The number of unread articles in the newsgroup, based on the user's own "high article" count if using a newsrc, and based on Group_Max-Group_Min+1 if not.

Hier_Count

A hierarchy listing is being done, and the named group is a hierarchy, or a group and a hierarchy, this number will be the number of matching subgroups in the hiearchy.

Hierarchy_Level

In hierarchy listings, this contains the current level of hierarchy being listed. It is 0 if hierarchies are not being listed. It is 1 for top level hierarchies and so on.

Note that you can perform more complex matching if you simply have the pattern be something like a dot (.) to match all newsgroups, and have the test in the group_listing template, testing more complex regular expressions, or in fact doing anything the programming language can do to test newsgroups, including showing only groups with unread articles or groups that match one pattern but don't match another. Of course, you must make a new template for each complex pattern you want to evaluate.

Sample Groups Menu Templates

Here is a simple template that makes a nice table for newsgroup menus, pulling descriptions from the DBM database. Here they are shown as they would be defined in the config file because that is normally where these would get defined.

Group List:     {Title( "Newsgroup Menu: ", query_newsgroup )} 
                <H1 align=center>Newsgroup Menu: {query_newsgroup}</H1> 
                <CENTER><TABLE> 
                {list( query_newsgroup, query_index );} 
                </TABLE></center> 
  
Group Listing:  <TR><TD align=right>{grouplist(List_Newsgroup);} 
                <TD>{data("Short:" . List_Newsgroup);}</TR> 

Hierarchy Listing:	<TR><TD align=right> 
			(+) <a href="{Script_name}?;m+;g:{Hierarchy}.*;v:{Hierarchy_Level+1}"><font color=darkred>{Hierarchy}</font></a> 
			<TD>{data("Short:" . Hierarchy . ":");}</TR> 

Article Template

These variables are available when doing output of an article. In addition, all headers from the USENET message are available with variable names equal to the header name in lower case, prefaced with "H_" and with non-alphanumeric characters mapped to underbar (_). For example the Message ID will be in the variable H_message_id, however you may prefer the variable Messageid which has the message-ID without angle brackets.

Note that if a USENET header happens to match the name of a configuration file variable, it will not be set, since these variables may not be changed by user data or template programs.

The following additional variables are defined:

Subject

The subject line of the message with any special ClariNet tags, such as the photo-identification tag, removed.

Messageid

The Message-ID, with the "<" and ">" removed, as is typical in Message-IDs used in news: URLs and ClariCGI queries

Title

Any special title provided by the query or other factors. You may wish to provide this instead of, or in addition to the article Subject, which is the traditional title to put on an article.

Note that you can use the header() function to output a nice header. In fact, the default article layout can be coded as:

	{ header(); body(); } 

But usually article templates like to manipulate the header a bit more than that.

Finding article templates

The group may end up being the first legal group in the news "history" file entry for the article's message-id. This means that per-group article templates may not currently work as planned unless you use article menus that refer to stories by group and article number instead of by message-id. (This is normally bad because you want the same message to always have the same URL, ie. the message-id, no matter what group the message is read from. If you have to include the newsgroup in the URL, you can't get that ability.)

Article templates can of course be stored in the predefined templates directory, and applied to an article by specifying the template explicitly in the query with an "A:templatename" query operand.

Complex Article Template

Below you can see an article template that does pretty much what our default template does. You can modify this to your taste, adding or removing headers. Please note that ClariNet contractual requirements require that you display the copyright notice found in the Organization or Copyright header line of any ClariNet article, as well as the byline from the From: line and attribution to ClariNet at a minimum.

Note this template has references to an image on our web server. You would of course modify this to point to an icon on your own server. Icons on our own servers are not guaranteed to be fixed or always present.

	<HTML><BODY bgcolor=white> 
	<IMG src="http://www.clari.net/Gifs/en-1inch.gif" width=72  
	height=20 align=right alt=""> 
	{ 
		# Leader line if either a slugword or From: line 
		if( H_slugword || H_from )  
			"<ADDRESS>"; 
			%"<a href=http://www.clari.net/>ClariNet</a> Story <B>{H_slugword}</B> from " if slugword; 
			%"<em>{H_from}</em> "; 
			Provider; 
			"</ADDRESS>"; 
			fi 
	} 
	{ Title( Title || "e.News: " . Subject ); } 
	<H2 align=center>{ Title || Subject}</H2> 
	{ # We add the real subject as a sub-header if one was provided  
	%"<h3 align=center>[{Subject}]</h3>" if Title;} 
	<ADDRESS> 
	{%"<STRONG>To:</STRONG> {H_to}<BR>" if H_to;} 
	{%"<STRONG>CC:</STRONG> {H_cc}<BR>" if H_cc;} 
	{%"<STRONG>{H_organization}</STRONG>" if H_organization;} 
	{H_organization && H_date ? " / " # Insert delim if both are present } 
	{H_date}<BR> 
	{% "<STRONG>Keywords:</STRONG> {H_keywords}<BR>" if H_keywords;} 
	{% "<STRONG>Summary:</STRONG> {H_summary}<BR>" if H_summary;} 
	{% "<STRONG>Location:</STRONG> {H_location}<BR>" if H_location;} 
	{% "Copyright {H_copyright}<BR>" if H_copyright;} 
	</ADDRESS> 
	{%"<STRONG>Priority:</STRONG> {H_priority}<BR>" if H_priority && H_priority != "regular";} 
	{%"<STRONG>Format:</STRONG> {H_format}<BR>" if H_format;} 
	{if( H_newsgroups ) 
		"Newsgroups: "; 
		grouplist( H_newsgroups ); 
		"<BR>"; 
		fi } 
	{if( H_references ) 
		"References: "; 
		msgidlist( H_references ); 
		"<BR>"; 
		fi } 
	<HR> 
	{art_head} 
	{body(0);} 
	<HR><P>Thank you for using our system</P> 

Added at the end of the template is a tag line which is not present in the real default template

Headline Menu Template

When a newsgroup displays a menu of headlines, there is actually a template for each menu entry. This allows you to make the entries and HTML list (the default) or an HTML table in just about any style you wish. You can also decide want to provide with each entry.

You can actually modify this template. If you assign the list_member variable it is treated as a template for the display of headline menu items.

The default template is as follows:

	{List_Tag||"<LI>"} 
	{"<img allign=top src=/Gifs/camera.gif>" if Art_Photo;} 
	<a href="{Script_Name; 
	if(query_usenumbers) 
		%"?{query_newsgroup}:{Art_Number}"; 
	 else 
		%"?;m:{Art_Message_ID};g^"; 
		fi 
	}">{"<font size=-1 color=darkgreen>[Seen]</font>" if Art_Seen; 
	Art_Subject; 
	}</a> - <font color=darkred><i>({fullname( Art_From )})</i></font> 
	{%"<font size=-1 color=darkblue>{Art_Condate}</font>" if Art_Condate;} 

This outputs the List_Tag or <LI> if the tag is not set, then outputs a camera ICON if the article has graphics. Then it puts out a link to the article in either numeric or message-ID form, the link text being the headline. If the Art_Seen tag is set, it first puts out the word "Seen", small and in Green.

It then outputs the full name of the author (byline) in dark red, and then the date in small size dark blue type if the date is not redundant.

The following other variables are avilable in menu templates.

List_Tag

In the default menu template, you can set this variable to have a different list preface tag than <LI>. Thus if all you want is to put the items in a table, you can just set this to be a <TD> element with the appropriate tags, though you won't get a closing </TD>, browsers will handle that.

Art_Shortdate

The date, in a short, simple mm/dd form.

Art_Condate

This is Art_Shortdate, or a null string if the date is already present in the article headline in some form. This is also null if the query has requested that dates not be provided in menus, so generally this is what you should use to render the date.

Art_Subject

The article subject, with any ClariNet photo identification tags removed.

Art_From

The From: line of the article. You can apply the userid and fullname functions to this.

Art_Message_ID

The article Message ID, with any angle brackets "<" and ">" removed from the outside.

Art_Photo

True if the article has graphics or a photo, false otherwise.

Art_Date

This is a numeric variable with the date of posting of the article as a Unix time number (seconds since Jan 1, 1970 midnight GMT). Mostly useful in comparisons.

Art_Number

The article number of the article.

Art_Lines

The number of lines in the article, if there was a Lines: header present. Often this is not present, and this will be zero.

Art_Limit

The limit requested in the query of how many articles to present. Always a positive number even if the query_index is negative. Will be a very large number if the query has requested all articles (query_index is 0).

Art_Bytes

The number of bytes in the article. More reliable than the number of lines as it is always set. You can test this to tag big articles etc.

Art_Index

The index of the article in our menu. The first item will have an index of 1, and so on to the end or the limit. If you want a table with numbered entries, you can use this.

Art_Seen

Has this article already been presented to the user on this page? Usually true only in multi-queries, special queries or personal newspapers. It is considered good form to eliminate or tag articles the user has already been offered higher up on the page to avoid wasting their time going at the same article.

Table of Articles

<TR> 
<TD> 
{"<img allign=top src=/Gifs/camera.gif>" if Art_Photo;} 
</TD> 
<TD><a href="{Script_Name; 
if(query_usenumbers) 
	%"?{query_newsgroup}:{Art_Number}"; 
  else 
	%"?;m:{Art_Message_ID};g^"; 
	fi 
}">{"<font size=-1 color=darkgreen>[Seen] %s</font>" if Art_Seen; 
Art_Subject;}</a> - <font color=darkred><i>({fullname( Art_From )})</i></font> 
</TD> 
<TD>{%"<font size=-1 color=darkblue>{Art_Condate}</font>" if Art_Condate;}</TD> 
</TR>