PanuWorld What's New Manager

Installation and usage manual

PanuWorld What's New Manager is a tool that scans all documents of your web site and then lists (up to) eight newest documents found using the HTML/XML template you have designed. The documents are not ranked by the file system dates but a special What's New Manager tag in the content of the file. Because of this you have full control of the document dates and changes that are not significant to the users do not need to update the date.

This tool is completely independent of PanuWorld Layout Manager, although they can be easily used on the same site because both of the require an off-line copy of the site.

Installation

To use the PanuWorld What's New Manager you will need a local copy of your web site on your hard disk. (To make the local copy to work during your testing and development, you will need to ensure that all internal links in it are relative.) The WhatsNewManager.exe does not need to be installed in any specific folder. However, usually it is copied to a folder just above the root folder of your web site local copy. Let's say that the root directory of your local copy is C:\Internet\www\. In this case, the WhatsNewManager.exe is copied to directory C:\Internet\.

In addition to this, you will need a suitable command file (*.cmd) that lists the files for the WhatsNewManager.exe and executes it. You cannot run WhatsNewManager.exe directly. Because the What's New Manager does not scan your site by itself, you have full control on the the files that are included on the what's new list. Usually the command file contains commands like:

mode con cp select=1252 > nul
dir /s/l/b www\*.html,www\*.htm,www\*.php | whatsnewmanager www\whatsnew.html www\whatsnew.rss

In this example command file, dir command lists all *.html, *.htm, and *.php files in all subdirectories (/s) below www, converting all found file paths to lowercase (/l), and lists only the file names and paths without any extra information (/b) that What's New Manager cannot handle. Then the resulting file list is passed to the WhatsNewManager.exe, which scans the files and updates two files, www\whatsnew.html and www\whatsnew.rss, with the results.

Naturally the number, types, locations, and names of your "what's new" document(s) may be different on your site.

The mode command is needed just to ensure that the dir command outputs possible non-English file names in a format that What's New Manager understands.

In some cases you may want to exclude some files or folders from the what's new list. This can be achieved by manipulating the file list returned by dir command e.g. with find command(s). For example, if your site has a subdirectory private whose files you want to never appear in the what's new list, modify your command file like this:

mode con cp select=1252 > nul
dir /s/l/b www\*.html,www\*.htm,www\*.php | find /v /i "\private\" | whatsnewmanager www\whatsnew.html

Now the find command removes (/v) those files that contain substring \private\ in their path (case-insensitive, /i) and they will not appear on the what's new list in any situation. If you want to leave out several directories, just add more find /v /i commands separated by | (vertical pipe) characters.

What's New Manager tag

Each file that will be analyzed by the What's New Manager must contain the special What's New Manager tag. This special character sequence can appear at any place of the file but usually it is inserted in the beginning of the file.

<!--$DATE 12.1.2008 $TITLE what's new manager manual
-->

The tag consists of keywords $DATE and $TITLE and the effective document date in format d.m.yyyy and document title (to be displayed in the what's new list). All of these items must be separated from each other with single space characters. The document title can contain spaces but it must end the row.

HTML comment tags () are not required by the What's New Manager but it is the most common way to prevent the tag to be displayed on the web site. Naturally, it the document is in another language than HTML, you have to use another methods to achieve the same effect.

The tag must be present in all files analyzed. If you want to exclude some specific file from the what's new list, add an empty tag in it. It tells the What's New Manager that the file can be safely skipped:

<!--$DATE $TITLE
-->

What's new HTML/XML file tags

What's New Manager does not use any separate template file, instead it updates the specified what's new list HTML/XML file with the results. The file must contain some What's New Manager specific tags that tell the program what texts must be replaced with the information collected.

The what's new HTML/XML document can contain references to the up to eight newest documents. For example, on a HTML page such references are usually links, and the tags can look e.g. like this:

<!--<li><a href="$EVAL LINK 1">$EVAL TITLE 1</a> (last update $EVAL DATE 1)</li>-->
<li><a href="[relative URL to the document]">[document title]</a> (last update [document date])</li>

The first line of a reference must contain only one HTML/XML comment containing "template" where the data will be inserted. In such template, there must be at least one valid $EVAL tag (see table below), otherwise it will be ignored as a standard comment.

If the first line contains at least one valid tag, the next line (content ignored) is replaced with the contents of the "template" with all valid tags processed. This allows the program to process the same file again and again replacing the previous results with the new ones automatically.

Note that you must leave one extra line after the template when editing the file. The template comment will always result in complete replacement of the next line. If one extra line is not left in the file, the replacement will delete something that follows the template comment line.

All of the tags are optional. When the What's New Manager detects a valid $EVAL tag in the "template", it replaces it with the corresponding value. The number 1...8 after the command tells the program which item of the what's new ranking must be inserted to that location.

Command (all uppercase, n = 1...8)	Description	Example (local time zone UTC+0200)
`$EVAL LINK n`	Replaced by the relative URL of the document.	`../path/newdocument.html`
`$EVAL TITLE n`	Replaced by the document title.	`Title of a new document`
`$EVAL DATE n`	Replaced by the document date in `d.m.yyyy` format.	`29.1.2010`
`$EVAL RFCDATE n`	Replaced with the document date in UTC RFC822 format (e.g. for RSS feeds)	`Thu, 28 Jan 2010 22:00:00 GMT`
`$EVAL TIME`	Replaced by the current date and time in `dd.mm.yyyy h:mm` format.	`29.01.2010 20:02`
`$EVAL RFCTIME`	Replaced by the current UTC date and time in RFC822 format (e.g. for RSS feeds)	`Fri, 29 Jan 2010 18:02:57 GMT`
`$EVAL YEAR`	Replaced by the current year	`2010`
`$EVAL GENERATOR`	Replaced by the What's New Manager name and version.	`PanuWorld What's New Manager 2.1.1`

Although these commands look like PanuWorld Layout Manager commands, they do not conflict with it. The Layout Manager does not process $EVAL commands in the document body ($EVAL is processed only in the template common sections).

All inserted texts have their &, <, and > characters escaped as & < and >. This ensures that the resulting HTML or XML document will not be broken.

RSS feeds

What's New Manager can be used to generate XML files, for example RSS feeds, listing the newest pages on the site. Just create an XML file containing "template" comments containing valid $EVAL tags as described above. The most important tags for RSS feeds are: $EVAL LINK, $EVAL TITLE, $EVAL RFCDATE, and $EVAL RFCTIME.

Note that the links in the RSS feed should be absolute. Therefore put the absolute URL to RSS file folder (ending with a /) before all $EVAL LINK tags ($EVAL LINK tags are substituted always by relative URLs from the RSS file folder to the referenced document).

All dates and times in RSS feeds must be represented in RFC822 format. Therefore do not use $EVAL DATE or $EVAL TIME in <pubDate> or <lastBuildDate> elements.

The value for the RSS <guid> element shall be unique for each updated page and update date. Therefore one suitable value is generated by combining the date and URL information of the item, for example:

<!--<guid isPermaLink="false">$EVAL DATE n-$EVAL LINK n</guid>-->

Because the <guid> value is not interpreted by the RSS reader as a date but just as an arbitrary string, you can use the non-RFC822 document date tag in the <guid>.

More information

Too see a real what's new page in action, open this page showing the five newest documents in this PanuWorld site. To see the What's New Manager tags used to produce the content, just look at the HTML source of the page. Similarly, an RSS feed showing the eight newest documents in this site is also available.

PanuWorld What's New Manager and an example command file for it are included in the PanuWorld Layout Manager package, which can be downloaded from the PanuWorld Layout Manager home page.