Documentation
| 2002 - 10 - 24| First revision |

1. Introduction
2. License
3. Features
4. Installation
   4.1 - Installation Requirements
   4.2 - Installation Process
5. User's Guide
   5.1 - Login System
   5.2 - Browsing Articles
   5.3 - Stats
   5.4 - Search Engine
   5.5 - Article Posting
   5.6 - MyBox
6. Administrator's Guide

    6.1 - System
    6.2 - Server
    6.3 - Newsgroups
    6.4 - Users
    6.5 - Cron Jobs
7. i18n
    7.1 - How to Change MyNewsGroups :) language
    7.2 - How to add more languages to MyNewsGroups :)
8. Themes
    8.1 - Change the current theme
    8.2 - How to add new themes
9. Contact
10. Authors


1. Introduction

MyNewsGroups :) is a USENET news client, based totally on a web interface, written in PHP4. It's back ended with a database, which allows us to develop useful tools such as search engines, SPAM filters, subscriptions, stats, etc.

The web interface of MyNewsGroups :) is very easy to use, and has all the advantages of the modern webmail like systems: You can search through any news group anywhere in the world without the need of setting up any program.


MyNewsGroups :) is based on the great work of Florian Amrhein, the developer of NewsPortal. (http://www.florian-amrhein.de/newsportal). I simply took his code, GPL licensed, and modified it to add the power of a MySQL database for the storing of the articles posted in the news groups. With the use of MySQL and the complete library of Floh to query the News Server, MyNewsGroups :) can store all the articles in the news groups querying the news server only ONCE for each article.

MyNewsGroups :) purpose is actually to mirror public newsgroups so that you don't need a newsreader - just your internet browser. MyNewsGroups :) copies all messages from subscribed public newsgroups into a database and adds extra features such as: saving article per user, statistics on users, search functions and so on.

MyNewsGroups :) is aiming to people that have a website from where they want people to have access to newsgroups of same subject.

2. License

MyNewsGroups :) is released under the GPL License. You can get a copy of this license at the 'doc' folder or at http://www.gnu.org.

3. Features

- Multiple news servers support.
- Database backend. (PHPLib's database abstraction class).
- Login System (Optional).
- Search Engine.
- Article compression with Zlib.(Optional).
- Stats
- Installation Wizard.
- Web based Administration Interface.
- Subscription System.
- Save, print or send by email your favorite articles.
- New and unread messages highlighting.
- i18n. Multi Language system.
- Themeable.
- Cron Job Support.
- 'register_globals = off' compatibility.
- Optimized article downloading and indexing system.

4. Installation

4.1 - Installation Requirements

-
PHP 4.1.0 or above.
MyNewsGroups :) use the latest security improvements of PHP4, so we recommend the upgrade to the latest stable PHP.
-
register_globals = off.
MyNewsGroups :) has been totally redesigned and fixed to work with the newest security advices of the PHP group. Therefore, putting register_globals off in your php.ini is compulsory if you want to keep your server secure while using MyNewsGroups :).
-
Database.
MyNewsGroups :) works with a database for the backend. It has been tested with MySQL, but since it works with the PHPLib's database abstraction class, any database supported by this class should be valid. If you don't use MySQL, please read the PHPLib's Documentation at http://phplib.sourceforge.net.
-
ZLib Module for PHP4 (Optional)
MyNewsGroups :) supports the compression of the articles if PHP4 compiled with Zlib.
  
4.2 - Installation Process

The process is quite easy:

1. Upload to your server and extract the MyNewsGroups-x.x.zip:

2. Copy the complete folder 'MyNewsGroups' to the required path in your web server. Point your browser to the following location:
http://www.mydomain.com/MyNewsGroups/install.php (Replace this with your own information) and the installation wizard should appear.

3. The first installation form is divided into three main sections:

- Basic Configuration

At this section you'll find the 'Web Server Host' and the 'Script Path' fields filled, just check that the information is correct and choose the language of the MyNewsGroups :) system and if you want ZLib Compression support. (Zlib library installed is required, if your PHP installation doesn't support it, you won't be able to use the article compression feature.)

- Database Configuration

Fill the required fields with your database information: Host, database name, username and password. If you have any doubt, contact with your system administrator or your Hosting Company technical support. BEWARE! The database must exist. You must create it first!

- Admin Configuration

At this section the Administrator of MyNewsGroups :) should fill all the required information in order to gain access to the Administration Interface or the Control Panel of MyNewsGroups :).

4. Once you have filled this information and sent the form, a new page tells you to click on the 'Download' button to get the required config.php file that you must upload to your server in order to get MyNewsGroups :) running correctly. The page will tell you the path you have to upload the file to. Done this, clink on the 'Finish' button to finish the installation.

5. If everything has been correct, you can now go to the administration interface to configure further your new MyNewsGroups :) installation. You can find more details about the Administration interface at section 6: Administrator's guide.

Pretty Simple, isn't it?



5. User's Guide

This section introduces the different pages of the web application and gives instructions about how to use the system. The user interface of the application is divided into four main sections: The header, the left column, the footer, and the main area. The header has the logo, the links to the principal pages of the application and the system info box, where important messages about the system status are shown. The left column shows the login form is the user is not in a session, and the user menu if the user has logged into the system. The main area is where each page offers its information: NewsGroups, articles, stats, etc. Finally, the footer shows some information and links about the project MyNewsGroups :) project.

5.1 - Login System

The login system of MyNewsGroups :) provides the users with a wide range of features that are not functional when it's desactivated.

The first step should be the registration of a new user. Click on the 'Register' link below the login form and you'll be redirected to the registration page. Once you provide to the system the correct information, a new user will be created and you'll be shown your Home page directly. Your session has begun.

If you log out and want to come back again to your Home page, you must login. Introduce your login and password in the login form and press 'Ok!'.

Notice that the Login System and the Registration of MyNewsGroups :) is quite secure without the use of SSL encryption protocols, because the password is not sent to the server in a readable format. A MD5 hash is applied and a Challenge - Response technique protects all the process.


5.2 - Browsing Articles

Well, that's what MyNewsGroups :) web application is for: Browse and read the articles posted to the UseNet. The article browsing begins clicking on the 'Newsgroups' link. It sends us to the page that shows the list of newsgroups registered in the system. We can get information about the number of articles, the group name and the description of each group. If any of the groups is clicked on, the main page for that group appears.

There, the newest list of articles is shown, with the date and the author of the post. We can see also if the articles have any replies and finally, with the page system and the calendar we have an easy access to all the articles posted to that group.

If we have found an interestign subject among all the articles, we can click on it to go to the article, page where the complete thread ant the text of the article are shown.


5.3 - Stats

One of the most interesting sections of MyNewsGroups :) is the Stats page, where you can find information related to the newsgroups, to the articles and to the Authors of the articles. You will know which are the most popular and the most crowded newsgroups, the hottest articles and the most readed, the most active users, etc.

5.4 - Search Engine

MyNewsGroups :) comes with a powerful search engine to help the users find the information they want in a quick manner. You can search in a group in particular, or in all the groups registered in the system. Click on the search link at the header section, or go to any newsgroup page to find articles in that particular group.

5.5 - Article Posting

Not only can you read and browse the different newsgroups. You can post new articles to any group with Post permissions. Post permissions are defined by the Administrator of the system.

You can post new articles that will start a new thread of discussion, or you can reply to existing articles in order to help or collaborate with others users of the UseNet. Notice that actually, you only can post if you are a registered user and the login system is activated. If the login system is desactivated any anonymous user can post to any group. If you are in a session, your email will NOT be shown clearly when the article is posted to avoid spam bots to fetch it. It will be transformed by this way:

yourname@yourdomain.com = yourname_at_your_domain_dot_com@foo.com

[ Currently MyNewsGroups :) doesn't support binary attachments, but as it's a requested feature, we're working on it. ]


5.6 - MyBox

The MyBox menu has the following sections: MyHome, MyGroups, MyArticles and Log Out. The first one is a direct link to the home page of the user registered in MyNewsGroups :). The last one logs the users out of the system. MyGroups manages the list of the user's favorite groups. He can add or delete new groups to his list and take notice of the new and unread articles of each group. It's a kind of newsgroups subscription system. Finally, MyArticles sections let the users store their favorite articles in a personal article box, in order to print them, email them to a friend or just to try to not forget about them.

6 . Administrator's Guide

The first page of the Administration interface is the Login Form. Fill this form with the username and password specified in the installation wizard to begin the administrator's session.

[ Since MyNewsGroups :) 0.5, the administrator has a special profile in the system, and has different privileges than the normal users registered at the MyNewsGroups :) site. It has exclusive access to the Administrator interface, and won't have access to a normal MyNewsGroups :) session. It can not login into the MyNewsGroups :) system to read or post articles new articles.]

The main page of the administrator interface shows us a welcome message and the principal administration menu on the left side. This menu is divided into the following sections: System, server, newsgroups and users. The administrator's interface follows the design pattern known as 'Master - Detail' administrations. Each section is divided into a master part and a detail part. The master is a list of elements and the detail shows information about each of those elements.

6.1 - System

The master part shows us the current configuration schemes of the system. At the beginning, just after the installation, the 'Default' Configuration should appear. Here you can click on the one configuration to modify or delete it, or you can add new configurations. You can only have one active configuration at a time. The detail part is quite big, and it's also divided in four main sections: System, download, visualization and security.

The first fields are for the own configuration: you can change it's name or label, the description and if that configuration is the active one or not. With this approach, you can have more than one configuration available and you can switch between them in order to react quickly upon external influences to the system. (You can have one configuration with a login system and another without login required; or you can have one configuration to run with the Online Indexing and downloading system or with the cron job.).

The
System part deals with the principal configuration parameters of MyNewsgroups :): The 'Prefix' is the path from the local root of your web server to the installation of MyNewsgroups, and the 'Root' shows the complete installation path of MyNewsGroups :). These two values have been automatically filled from the installation wizard and shouldn't be changed if you haven't changed the location of the MyNewsGroups :) installation. The 'Language' combo box changes the current language of MyNewsGroups :) and the following three radio buttons change important flags: The Debug flag shows a debug window if we roll over the 'debug' link at the footer of the MyNewsGroups :) interface. It should be yes if we're testing the system. The Login flag activates the login system. Important: If the login system is desactivated any user can post to any group. As the system administrator, you should restrict the access to some groups to anonymous users. If the login flag is on, only the registered users will be able to post new articles. The Work Online flag activates the new Downloading and Indexing system. This flag must be On if we want to download the new articles while the users navigate through the system. If we are downloading the new articles with the Cron Job support, this flag should be off in order to speed up the system.

The
Download part tunes the new article downloading and indexing system. This is a quite complex algorithm that downloads the articles while the users are reading their favorite groups. The power of the new system comes with a 'windowing technique' that benefits the most active newsgroups and allow the retrieval of the articles of the less crowded newsgroups. This system must be configured for working online and for working offline (with cron job support).

This algorithm has been introduced due to the hang of MyNewsGroups :) when trying to download and index into the search engine large numbers of articles. The solution to this problem is trivial: Instead of download 100 articles while waiting to view the newsgroups page at MyNewsGroups :), the system will download a small number of articles of a small number of groups every time a new php page is called at the web serve or each time the cron job is activated..

The system introduces a new Activity Index for each group to benefit the most active newsgroups. The system builds a list of N groups where ALL the groups registered in the system appear, but some groups appear more than others. This way we can download more articles from the most active groups. The more visits get your site running MyNewsGroups :), more up to date you'll have your groups because more articles will have been downloaded. If you work offline with cron job support, doesn't matter the number of visits you have, you'll alwaysa have your groups up to date.

In order to adjust the behavior of this algorithm, four parameters can be changed: 'Days of Activity Index' is the number of days the Activity Index is calculated for. If it's 10 days, the days before won't be evaluated in order to calculate it. 'Items in list' specifies the number of items of the newsgroups list that we can fill. This number must be greater than the number of registered groups. for example, if you have 20 groups registered, this number should be between 50 and 100. 'Number of NewsGroups' tells the system how many newsgroups will ask for new articles. The higher the number, the slower the system will run if 'Work Online' is set to Yes.. 'Number of Articles' counts the number of articles that will be downloaded for each of the groups asked each time the algorithm is running.

The
Visualization part deals with the visual interface of MyNewsGroups :). One of the most important parameters that can be changed here is the 'Theme' because it changes all the interface of MyNewsGroups :). The 'Number to Flames' parameter controls the number of articles required to change the folder icon of the newsgroups.php page into a burning one. 'Navigation bar items' counts the number of items that appear in the 'master' section of the administration interface and the number of articles shown at 'tree.php'. 'Navigation bar pages' counts the number of pages between the symbols <<  < and > >>. 'Time to highlight new' controls the time that should last the highlight of new articles.

The
Security part deals with some security checks that MyNewsGroups :) performs. If the flag 'Send Poster Host' is true means that a header-line named "X-HTTP-Posting-Host:" will be attached to every posted article, set to the hostname of the user who wrote the article. If 'Test Group' is true, each time that a operation is performed with a newsgroup the system checks if the group is registered in the system, in order to avoid cross posting and other security flaws. If the 'Validate Email' flag is true, apart from the typical sintax check, an MX or A record is checked for the domain-name of the e-mail address. MyNewsGroups :) performs a hostname lookup. [Beware! The 'Validate Email' flag must be false in Windows servers.] Finally, the 'Secret String' is used to generate a proper challenge required for the secure login system. It must be changed before putting the system in production.

6.2 - Server

MyNewsGroups :) support the use of several news servers to work with. At his sections, you can add new servers, modify existing ones and delete oldest ones. The master part of this section contains a list of the registered news servers, and the detail part shows a form with all the required fields to register a new server into the system: The 'Host', the 'Port', the'Login' and the 'Password' if authentication is required. The last field, the 'NewsGroups list' is not filled just after a new installation, and is automatically filled if we click on the 'Get Newsgroups list!' button. This button opens a Pop Up window where the system tell us that the list of available newsgroups will be downloaded to the system. This process may take several minutes to perform, so be patient. When it finishes, a file with the name of the server and the .list extension will have been saved at '/upload/lists/'. [Beware! This folder will probably need the following permissions in order to get the new file saved there: 777. Remember that the system is creating and writing a new file there.] This file helps the system to build a menu to choose the newsgroup from at the NewsGroups section.

6.3 - Newsgroups

At this section we can manage the newsgroups registered into the system. Just after the installation, there are any groups registered so some new groups should be added. To do this, just click on the 'Add a new NewsGroup' button and the detail form should appear. There you can choose the server from the newsgroup articles will be downloaded and the newsgroups itself from the Menu built with the file downloaded at the server section. Click on the 'Choose a Newsgroup!' button and the Menu will appear on a Pop Up. This Menu normally takes several time to fill with the newsgroups names, so be patient. You can also type directly the name of the group you want to register. Once the newsgroup name has been filled, you must choose if the new newsgroup should be writable or not. If you allow posting to that group, any user of MyNewsGroups :) could post new articles to that group. [Beware! Use this feature responsibly. You are granting writable access to a public newsgroup].

If we have several groups registered already, we can modify some parameters of them. Click on any group at the master part of this section and a bit different detail part will be shown. There, we can change the description of the newsgroup, change the writable state of it, and apply one of the most requested features of MyNewsGroups :) - You can now delete the old articles from the database clicking on the '--' button and then clicking on the 'Modify' button. Just that simple.The old articles will be gone from the system.


6.4 - Users

The last section of the Administration Interface deals with the users registered in MyNewsGroups :).
[ To Be Defined ]

6.5 - Cron Jobs

Since version 0.5, MyNewsGroups :) support Cron jobs directed to the new 'cron.php' script. You can setup a cron job in your server to let it do the task of downloading and indexing the new articles. If you do so, you can now turn off the 'Work Online' option of the System configuration section in order to let the pages dowload quicker and not disturb your users. For example, the you can setup a cron job to run each minute the following command:

GET http://yourserver.com/MyNewsGroups_Path/cron.php > /dev/null

Remember that you must configure the indexing and downloading system as explained before even if you work Offline. The cron.php script uses the same algorithm than the other php scripts of MyNewsGroups :) to download the articles.

7. i18n

Since the 0.4 release, MyNewsGroups :) supports a multi-language system. With the use of this system, you can view the GUI of MyNewsGroups :) in your mother tongue, if defined.

[Beware! The new Installation wizard and Administration Interface have not been yet integrated into the i18n system and are only available in English. For next releases we'll fix this with a complete language files in English and Spanish at least.]

7.1 - How to Change MyNewsGroups :) language

Just point you browser to the Administration Interface, go to the System section and in the system part you'll find a combo box called 'Language'. Just change it and the MyNewsGroups :) system will change the language of the user interface.

7.2 - How to add more languages to MyNewsGroups :)

You know any of the supported languages and also your mother tongue? Is not your mother tongue currently supported? Please support us translating the files under the '/lang/<language you know>' and create the new 'lang/<your mother tongue>'. The MyNewsgroups :) team and all the community will appreciate very much that time you spent. Thankx in advance. There're also a few comments in the language files, please be careful with them and try not to make any PHP syntax mistakes.


8. Themes

MyNewsGroups :), since the 0.4 release supports the use of several themes that allow a total change in his GUI. This is done using the PHPLib's template class, that allow the themes designers to avoid changing system code (PHP4 and SQL) and to concentrate at the HTML and graphics designing.

8.1 - Change the current theme

Below the 'themes' directory, you have all the themes that come with MyNewsGroups :) official release. The default theme is the 'standard'. You can change the current theme pointing your browser to the Administration Interface, System section and Visualization part. There you'll find a combo box called 'Theme' that shows the current available themes. Choose the favorite theme, click on the 'Modify' button and that's it!, the GUI of MyNewsGroups :) will have changed.

8.2 - How to add new themes

Are you a graphic designer and want to add a new theme to the MyNewsGroups :) official release ? It's quite easy. Just follow the 'standard' theme's characteristics: All the official themes must have the same directory structure: '/themes/new_theme/styles' and '/themes/new_theme/templates'. The first one has the CSS style sheet and the templates has all the HTML files. You can change or create whatever you want in the new theme, but BEWARE!! The links showed in the *.htm files must remain the same, ALL the brackets {} expressions can NOT be touched, and all that you find between the tags like <!-- BEGIN ....> and <!END-- ...> must remain likely the same structure of information. You can visit the PHPLIb's Template class tutorials to learn a little about template generation.

Feel free to join us and support us creating new themes to MyNewsGroups :) !


9. Contact

It is pretty easy to get in contact with the developers if you need help or if you find bugs that need to be reported. The best way to contact us would be through our mailing list which is actively monitored. Just send an email to:

mynewsgroups-list@lists.sourceforge.net


10. Authors

The email addresses of the authors must NOT be used to ask for support or help. Please send your support questions to the MyNewsGroups :) mailing list, and your question can be answered not only by the authors but also by the MyNewsGroups :) community. Any email regarding support or help topics received at the following addresses will be redirected to the mailing list.

MyNewsGroups :) Active Developers

Carlos Sánchez Valle - Txarly :) txarly@users.sf.net
Eckhard Zemp - wikinger@users.sf.net
Eugeny Yakimovitch - ewger@users.sf.net

MyNewsGroups :) Demo (http://mynewsgroups.ods.org)

Administrator & Beta tester
Jeff

NewsPortal 0.23 (Core of MyNewsGroups)
Coded by Florian Amrhein - http://florian-amrhein.de