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