Creator information
Current maintainer :Max Maischein
Author(s) :Max Maischein
Recipe homepage :<none>

Version history
The documentation file was last modified on Tue Nov 29 18:22:58 2016.

Overview is a (not so) simple news system.
Compatible Genpage Versions
Version 1.0.3 and above.
news( aNewsdirectory )
news( aNewsdirectory, aMaxItems )
news( aNewsdirectory, aMaxItems, aNewsThemefile )

news() looks at all files with the extension .news in the directory given through aNewsdirectory, formats each with a template and returns the whole thing. The items are sorted by the creation date of their file. The maximum number of news items can also be specified, as can the output format through a theme file. I use to maintain the news, FAQ and history pages for my site.

aNewsdirectory must be the name of a directory in which at least one file with the extension .news should be found (and it should be readable ...).

aMaxItems is an optional parameter that gives the maximum number of items that should be presented on the page. If this parameter is undefined, a default of 5 items is assumed. If you want all items to be presented on a page, you must supply a negative value (for example -1) to aMaxItems.

aNewsThemefile is the second optional parameter. It contains the name of the template file for both, the whole news body and for each item. A set of prefabricated themes are already supplied, some are direct rips of their originals (Slashdot, Freshmeat) while others are creations of my own. If this parameter is undefined, a default template (embedded into the source code) is used. News themes historically reside in $root/news.themes, but you are free to move them somewhere else.

News files

The format of the news files is as follows :

Fieldname:Field text (only one line)
OtherFieldname:Other field text (only one line)
BODY:Body of the news
More body ... (even without the BODY: prefix, because BODY collects all this)
All the fields can be used in the news theme to have locations for the date, email, homepage etc., it is a good idea to keep track of the required fields for each news theme. news() also works if a field is required in the theme but missing in the .news file.
One special field is the ID field, which should contain an unique ID that identifies the news item on the page. If the ID field is not given, news() automagically creates a unique ID for it. The use of the ID field is to link (for example) headlines to their body.
Another special field is the DATE field. If it is not present, news() substitutes the creation date of the corresponding .news file. Deviating from the "one-field-per-line" rule is only the BODY field, every line after the "BODY:" line also goes into the BODY field - this allows for easier creation of long news.

Theme files

The format of the theme files is as follows :

<!-- This is the section that surrounds all the items -->

<!-- This section will be repeated for every item -->

In both sections, there will be some special replacements :
In the %_NEWS_BODY_% section, <!-- _NEWS_ ITEMS --> will be replaced by the list of items.
In the %_NEWS_ITEM_% section, <!-- _NEWS_ itemname --> will be replaced by the text after itemname: in the item file (or some witty text, if itemname is not present).


First of all, the file must be included in some content by using <!-- _GP_ recipe( "" ) -->.

Setting up all the stuff for news() can be done in two steps :

  1. Create a directory content/news/ and create at least one file with the extension .news there.
  2. At the location in your page where you want the news to be placed, put the following HTML :
    <!-- _GP_ news( "$root/content/news" ) -->

Let's assume that there is a directory $root/content/news and that in that directory, there are two files, and Let's further assume that the filedate of is younger than the filedate of The contents of are :

TITLE:Hello world !
BODY:Hello world !
This is the first news that you will see. This item was produced yesterday.
Even more interesting stuff will follow. Also, <A href="">hotlinks</A>
can be embedded into news.

And let's also assume the contents of are :

TITLE:Great news today !
BODY:Hello again !
Today's news are not really that new. But you never know :)

Note that in, the DATE field is missing. news() will substitute the file's date and time, if the date field is missing.
Let's now look at the following HTML excerpt to be used in a .content file :

<A name="news"></A>
<!-- _GP_ include "$root/include/" -->
<!-- _GP_ news( "$root/content/news/",4, "$root/news.themes/default.gpnewstheme" ) -->
<A href="completenews.html">Full news</A>

The above code will produce the following, nice news (HTML output ommitted for brevity) :

Great news todaySat Jun 12 17:16:15 1999
Hello again ! Today's news are not really that new. But you never know :)
Hello World !Yesterday
Hello world ! This is the first news that you will see. This item was produced yesterday. Even more interesting stuff will follow. Also, hotlinks can be embedded into news.
Full news

There are other news themes, which make it possible to create headlines from the news (by simply omitting the _NEWS_ BODY field), to create a FAQ style list (by combining the headlines and then the news bodies in one page) and many more. For a FAQ or headlines, there might be another interesting recipe, toc(), which creates a table of contents from all headings in one page.

Creating a page with all news

If you want to create a page that contains all news items (and thus can become quite large), simply use the following code :

<!-- _GP_ news( "$root/content/news/", -1, "$root/news.themes/default.gpnewstheme" ) -->
There is no way (yet) to make news() and Genpage spit out several pages with 5 items each, and I don't consider this useful (yet).

To-do List

Known Bugs
None known :)

Back to Top

This page generated using Genpage - Version: 1.0.7 on Wed Nov 30 16:34:11 2016

© Max Maischein