DNewsWeb is a web to news gateway, it lets you merge your web pages and your news groups. By displaying usenet and local news groups on your web pages, users can read and post news directly using their favourite web browser.
DNewsWeb is provided FREE with your DNews News Server and is quick and simple to set up.
You will have recieved the following DNewsWeb files when you downloaded DNews:
dnews\web\*.tpl (directory of template html files)
You must install DNewsWeb on your WEB server, in a directory that you have already set up on your server as containing CGI programs. You must read your server documentation if you don't currently know how to set up a cgi program. Typically you would copy the files to a directory like:
Two files should be copied to this directory
copy \dnews\dnewsweb.exe \SERVER_ROOT\cgi-bin copy \dnews\dnewsweb.ini \SERVER_ROOT\cgi-bin
In some instances you will have to place the .ini file in a different directory. This is dependent on your server software, sometimes the 'SERVER_ROOT' is the right directory. (DNEWSWEB will give an error if it can't find this file, in which case just try moving it somewhere else.)
Now edit dnewsweb.ini and define: your news host, templates directory and news groups to display on your web page.
Syntax: Parameter Value
|newshost||news.your.domain||The name or number of your DNews news server. Use an IP number to speed up the process.|
|templates||c:/dnewsweb||The directory where you have copied the *.tpl files, On UNIX this directory must be set so that DNewsWeb can write to it. e.g. chown nobody /var/spool/dnewsweb|
|auto_subscribe||rec.humor, local.chat,local support||This setting allows you to list the news groups whose names you want to appear on the subscribed list for new users. Generally you will want to list some groups of particular interest or importance. For example you may have a local support news group or want everyone to see the rec.humor group or rec.chat|
|allow||local.*,rec.*||Groups to actually let people read: This setting allows you to specify which of all news groups you will allow access to via your website. For example allow rec.* allows all groups matching the rec.anything in the news header|
Now copy the tpl files from the distribution directory to the directory you have defined for templates in dnewsweb.ini
cd /dnews/web copy *.tpl /dnewsweb
If you wish, you can tailor the template files to give DNewsWeb the same look and feel as your own web pages. It is assumed you know how to edit raw html files, in addition there are some variables that you can use. The list of variables depends on which page DNewsWeb is showing. For example the %%h_subject%% variable only works when displaying an item, or directory listing.
Note: If you leave the template files in the /dnews directory, then they will be over-written next time you upgrade DNews, so it is best to move them if you wish to tailor the appearance.
Here is a list of the template files, and a brief description of each. In some cases alternate files have been included in the distribution, you may want to try one of these for an alternate layout, simply copy the alternate file over the top of the original.
|top.tpl||The first/top page shown when DNewsWeb is run|
|list.tpl||A list of newsgroups at a given level in the tree|
|items.tpl||A single news group, listing articles in that group|
|item.tpl||A single article within a news group|
|follow.tpl||Used when user posts a FOLLOW-UP message|
|post.tpl||Used when a user posts a NEW message|
|posted.tpl||To tell the user that the post was successful|
|required.tpl||To tell the user that a required field was not filled in|
|search.tpl||For searching the FTS database (if enabled)|
|results.tpl||Results of FTS search|
|xsearch.tpl||For searching a single news group|
|xresults.tpl||Results of searching single news group|
|postit.tpl||Template for messages posted using posting form|
|post_form.tpl||For posting with extra fields on form (replace post.tpl with this)|
Here is a list of the variables that you can use in these templates
|%%b_action%%||the cgi ref to DNewsWeb needed for a form 'action'|
|%%b_group%%||href to go to an individual group||top.tpl|
|%%b_search%%||href to go to the FTS search form||top.tpl|
|%%b_allgroups%%||href to go to the list of all news groups|
|%%begin_dir%%||Starts list of all news groups at this tree level||list.tpl|
|%%end_dir%%||Ends list of news groups||list.tpl|
|%%ifdef%%var%%||Conditional inclusion if variable is defined|
|%%b_related%%||List of related message||item.tpl|
|%%b_recent%%||Most recent articles in group||item.tpl|
|%%b_topgroups%%||Goes to top/main page of DNewsWeb||item.tpl|
|%%b_allgroups%%||Goes to list of all news groups||item.tpl|
|%%b_follow%%||Goes to form for posting followup messages||item.tpl|
|%%b_post%%||Post a new message to this group||items.tpl|
|%%b_searchgrp%%||Search this group for text||items.tpl|
|%%b_next%%||Next page of this group||items.tpl|
|%%b_prev%%||Previous page of this group||items.tpl|
|%%indent%%1%%||Used to define each indent level for threaded display||items.tpl|
|%%begin_item%%||Starts definition of how each item in dir is displayed||items.tpl|
|%%end_item%%||Ends definition of each item||items.tpl|
|%%b_item%%||Goes to a particular item||items.tpl|
|%%h_subject%%||The subject for a given item||items.tpl|
|%%h_date%%||The date for a given item||items.tpl|
|%%h_date_trim%%||The date trimmed to be readable||items.tpl|
|%%h_from%%||The email address of the person who posted it||items.tpl|
|%%h_from_trim%%||The email address trimmed to be readable||items.tpl|
|%%h_lines%%||The number of lines in this message||items.tpl|
|%%h_content-type%%||The value of the mime content type header||items.tpl|
|%%h_scores%%||The score an item got in a search|
|%%h_subject_30%%||The first 30 characters of the subject, also 40 and 60||items.tpl|
|%%summary%%||The summary of a search result|
|%%quote_body%%||Used in 'followup' to quote a previous message|
|%%show_item%%||Used to show the actual item||item.tpl|
|%%begin_dir%%||Starts the list of items within a group||items.tpl|
|%%end_dir%%||Ends item list|
|%%indent%%||Define the codes to indent and un indent||items.tpl|
|%%h_references%%||The references header|
|%%h_message-id%%||The message id of a message|
|%%h_newsgroups%%||The newsgroups it is posted to|
|%%h_group%%||The current group being displayed.|
|%%include%%file%%||Reads the named file in, (it cannot contain variables)|
|%%nitems:group.name%%||Number of items in the specified group (5.5f2 and later)|
|%%lastxhdr:header:group.name%%||Header information from last article (5.5f2 and later - see below)|
|Used by page up/down buttons to figure out where the next page up or down should start from, also used to decide if to show a page down button, if undefined then no button need be shown||items.tpl|
|Classic if then else structure, be sure to put these on the beginning of a line, and the 'xxx' must be a template variable, the expression is TRUE if the variable has a non empty value.|
|%%spaces%%||Is defined as the number of spaces (or images) to use for indenting. Images can be set instead in dnewsweb.ini||items.tpl|
|Is defined if the item is larger than 'isbinary_size' defined in dnewsweb.ini||items.tpl|
|Is set to the current sort order when showing a list of items||items.tpl|
|Displays NetWin CopyRight notice.|
The %%ifgroup%%ListOfGroups%% can be used to change the appearance of pages based on the news group being displayed. (e.g. you might want to use a background image of little cars for a newsgroup devoted to cars)
Useful for displaying adverts, you would setup a cron job (or program that runs every 10 minutes) to change the advert file, thus displaying a new advert each time someone reads the group. By only changing the advert every 10 minutes you avoid the problem of people turning off the images because they are too slow.
This variable can be used to display the contents of a header from the last message in a given group. This is useful if you want to display information about the last post. E.g.
%%lastxhdr:date:comp.lang.c%% - Display the time and date of the last post to comp.lang.c
%%lastxhdr:from:comp.lang.c%% - Display the sender of the last post to comp.lang.c
See the file items_t.tpl (or copy it to items.tpl) to see how a table can be used instead of the standard list format for news items.
|newshost||news.your.domain||The name or number of your DNews news server|
|templates||c:/dnewsweb||The directory where you have copied the *.tpl files|
|groups||rec.humor, local.chat||Groups that will appear on the top DNewsWeb page, this setting is obsolete, use the top.tpl file instead.|
|post_groups||local.*,rec.humor||List groups that users may post to using DNewsWeb|
|post_users||220.127.116.11,22.44.*||List IP addresses (not numbers) that may post|
|debug||True||Enables verbose debug output, (for NetWin use)|
|pagesize||60||Approx. number of items to show per page|
|allow||comp.lang.*,local.*||Groups to allow users read access too.|
|content_type||text/html||Used for some web servers which allow fancy features if the content type is changed to something non standard.|
|log_file||/var/log/dnewsweb.log||Allows you to specify a directory where DNewsWeb has 'write' access to create its log file.|
|sort_rev||true||Puts new messages at the top of each page instead of the bottom.|
|wrap_post||60||Wraps new posts at 60 characters|
|wrap_text||60||Wraps current existing articles at 60 characters|
With DNewsWeb you can define a posting form with required and optional fields. These will be used to force the user into giving you specific information with every post, for example with a newsgroup that is used for technical support you would require that the user tells you what version of the software they are using, etc. To try this out start switch to the example forms:
copy post_form.tpl post.tpl copy postit_2.tpl postit.tpl
Then try posting a message.
In the post.tpl there are two hidden fields to tell DNewsWeb what fields it should look for and which ones are required.
<input type=hidden name="required" value="os,version,reg"> <input type=hidden name="optional" value="keywords">
And then you can use normal form input fields to ask for the extra data, e.g.:
Operating System <input name="os" size=50 > (Required)<br> Software Version <input name="version" size=50 > (Required)<br> Registration Number <input name="reg" size=50 > (Required)<br> Keywords <input name="keywords" size=50 > (Optional)<br>
And finally you need to define a file called postit.tpl which DNews will use to construct the actual layout of the message that will be posted to the news server, e.g.
Operating System: %%os%% DNews Version: %%version%% Customer Registration Code: %%reg%% Keyword: %%keywords%% %%message%%
The following example (frame.htm) can be used to run DNewsWeb inside frames, the http address below needs to be changed to match your server.
<html> <head> <Title> DNewsWeb using frames </title> </head> <frameset rows="50%,50%"> <frame src="http://your.web.server/cgi-bin/dnewsweb.exe" name="items"> <frame src="empty.htm" name="item"> </frameset> </html>
Then in the templates items.tpl and item.tpl define the targets for buttons that should switch forms, for example the 'show item' href in items.tpl must point to the 'item' frame, e.g.
<li><a href="%%b_item%%" target="item">%%h_subject%% </a> ...<br>
Make similar changes to the href buttons in item.tpl that should jump back to the "items" frame. (see items_f.tpl and item_f.tpl for examples.)
<td><a href="%%b_related%%" target="items">Related Items</a> <td><a href="%%b_recent%%" target="items">Recent Items</a> <td><a href="%%b_topgroups%%" target="items">Standard Groups</a> <td><a href="%%b_allgroups%%" target="items">All Groups</a> <td><a href="%%b_follow%%">Post Followup</a>
This will display the directory of a group in the top window, and the actual items in the bottom window, just like a regular windows based news reader. This is totally implemented via the flexibility of DNewsWeb templates.
This means you have failed to tell your web server that the directory cgi-bin/ contains CGI programs and not WEB pages. Go back to your web server administration window and look for help on CGI directories. (This is the single most common question we get !!)
If DNewsWeb doesn't work try running it by hand, e.g.
cd cgi-bin ./dnewsweb.exe
That may give a better indication of the problem, if you get the DLL Initialization failed error that means the process DNews is running as (your web user code) does not have read access to the winsock dll's. To fix this change the security on your winnt and system32 directories.
Apache for NT has a fault with environment variables, basically it doesn't define them and that stops winsock from working, check the apache web site for a patch.
It will run with other news servers, however it is much faster with DNews and the 'list all newsgroups' function will only work with DNEWS. Also the buttons 'Related items' and 'Search' will not work.
To enable the full text searching button you need to add
to dnewsweb.ini (as well as installing the xmit process to build the indexes, see the manual for details on doing this, NOTE: the FTS database is resource intensive, especially if you try and index your entire news spool - plan on doubling your RAM if you want to set this up).
If you are looking at a large news group, then the threading will 'break down' because all you can see are parts of many different threads. You can increase the page size to reduce the extent of this problem. Also news groups which come from mail clients will not thread properly - for these use the 'subject' based sorting instead.
New ini settings:
|Defaults to the template directory, this directory is used to store information about
each user, e.g. groups they are subscribed to, and config settings etc. The data is
stored in hashed sub directories, this helps with performance.
DNewsWeb MUST have write access to this directory, typically on unix you would need to do this:
chown nobody /var/spool/dnewsweb
|Use this to authenticate users via your own specific pop server. If this is not defined then your nntp server will be used to authenticate users. However you should also define tellnews_pass|
|SORT_ORDER thread | subject | date|
|Specifies the default sorting order; new items will appear at the top of the list, and related items will appear indented and below the first item in that thread, threading on subject should be used for mailing lists where the references header is not defined correctly.|
|This list of groups is automatically added to the subscription list of new users. (It does not affect existing users), use this to specify local interest groups|
|Specifies the default domain to use for From headers in messages posted from this system.|
|If specified, then if a non logged-in user attempts to post a message, then they will be asked to log in first.|
|If specified, then top.tpl is never shown, instead the login template is shown and no reading or posting is allowed until the user has logged in. You may need to add a TELLNEWS_PASS setting (see below) if DNews requires user authentication.|
|If specified, this setting means DNewsWeb will treat web authenticated users as being logged in, they will not have to login again. To authenticate a user via the web you must set your web pages to require login on your web server. You may need to add a TELLNEWS_PASS setting (see below) if DNews requires user authentication.|
|If set, then the pop host entry field will be displayed when the user is asked to login, and DNewsWeb will authenticate the user via the specified pop server, this is a roundabout way of checking that the user really exists, it is still not 100% secure but at least stops people pretending to be other than who they really are.|
|Specifies that access.conf entries apply to DNewsWeb users and user authentication via DNews is possible for protected groups. Where xxx is the contents of the tellnews.pass file located in the workarea directory as defined in dnews.conf. Ensure your Web server is configured to not permit downloading dnewsweb.ini if it contains you tellnews password.|
|login.tpl - Used when a user is asked to login|
|config.tpl - Used to set/modify user config options|
|grpsrch.tpl - Used when searching for news groups|
|user.tpl - Main form used to show a user their subscribed news groups.|
Copy DNEWSWEB.exe into your cgi-bin directory.
Particularly with Version 4.7 you may want to try out the new templates provided. To do this copy your existing templates first, then copy *.tpl into your templates directory
The latest.tpl template allows you to present a single web page which displays the latest few articles for several newsgroups you specify with optional links to the newsgroups or articles themselves.
An example latest.tpl template is provided, to use it you setup a cron/at job to run DNewsWeb like this once a day:
.\dnewsweb -latest latest.tpl >d:\toppage.htm
This will generate a web page 'toppage.htm' which you can then use to hook users into your local disucssion groups. This command is run like this because you may use this page for your top web site page and you don't want that to be running a cgi and reading multiple news groups, in this way it's extremely efficient.
If you require logins on your server then to get the latest process to login with a specific user so it can read the groups etc do this:
Add to latest.tpl at the top:
And in access.conf add a line:
And in dnewsweb.ini add
tellnews_pass xxxx (where 'xxxx' is from the tellnews.pass file in
the DNews workarea)
New latest.tpl template variables.
|%%groups_to_show%%rec.humor,comp.lang.c%%||Specifies a comma seperated list of groups that should have their latest articles displayed.|
|%%body_lines%%10%%||Specifies the maximum number of lines to show of any single article before truncating it.|
|%%items_per_group%%3%%||Specifies how many of the lastest articles in each newsgroup should be displayed. e.g. The example specifes that the last three articles in each group should be displayed.|
|%%begin_list%%||Specifies the beginning of the article list.|
|%%end_list%%||Specifies the end of the article list.|
|%%group_ref%%||URL to the current items newsgroup.|
|%%item_ref%%||URL to the current item|
If you don't wish to include <pre> tags around %%body%% in the template then you should set 'format_html true' in dnewsweb.ini to ensure articles are formatted correctly.