LaNewsFactory User's Guide
Maintained by Christophe Brocas
10/10/2003
This is the LaNewsFactory User's Guide. It covers the installation, configuration
and usage of the 0.8.5 LNF version.
1. Introduction
During 2000 summer, I start to search an easy to use and install software for
web news management. I found a lot of interesting things with nice and sophisticated
features. Unfortunately, almost all of them require MySQL or others RDMS software.
Databases provide powerfull functionnalities but when you use a free ISP for example,
MySQL is not often included. So, I start to code LaNewsFactory under PHP.
1.1 What is LaNewsFactory ?
LaNewsFactory (LNF) is a PHP web news and forums engine. It requires
no database stuff, only a PHP enabled web server. LNF stores news in XML files.
1.2 Features
LaNewsFactory provides following functionnalities :
- forums and news system behaviors,
- topics,
- threaded comments,
- moderation and news management with edit/delete/commit functionnalities,
- XML format to store news in files,
- HTML templates support,
- image insertion for easy topic identification,
- 4 user authentification levels : site admin, topic moderator, poster and
reader,
- automatic email notification for the moderator when a news is post and for
the original news poster when a reply comes,
- search capacity,
- accurate news display status on the main screen : number of answers, writer
name and date of the last update,
- web interface for site and topics options, moderation and news management,
- support for 11 languages (french, english, spanish, german, dutch, swedish,
italian, portuguese, turkish, slovak and "finland").
1.3 License
LaNewsFactory is free software distributed under the GNU General Public License
(GPL). See the files "Copying" and "Copyright" supplied with the distribution
for additional info. For more info on GPL, see the Free
Software Foundation.
2. Installation
2.1 Getting it
LaNewsFactory can be downloaded from LaNewsFactory web
site. New version announcement are made on freshmeat
site and by lnfannounce mailing-list : to
subscribe.
The only thing you need is a PHP-enabled web server. But, I currently
test LaNewsFactory under a linux 2.4.19 & Windows XP/ Apache 1.3.26 & 20 / PHP 4.2.3 & 4.0.6 configuration.
2.3 Installing LaNewsFactory
Installing LaNewsFactory is done via an unzip/untar of the distribution file
in the directory you want to install it. Current distribution contains 4 directories
:
- a subdirectory called "images" with LNF images and "images/topicimages"
that contains default images for topics,
- a subdirectory called "templates" and "templates/lnf.tpl"
that contains default HTML templates files (*.tpl) .
- a subdirectory called "news" that will contain the topics files and the
news files,
- a subdirectory called "news/mod" that will contain the news up to moderation
for all the topics,
- a subdirectory called "lang" that contains the language files.
IMPORTANT : your web server has to allow access to the LNF directory.
If it is not configure for it, you have to configure your web server before
starting using LNF.
That's all.
2.4 Upgrading LaNewsFactory
The most important change of the 0.8.4 version is the change of the PHP scripts file extension.
To complete a migration of a 0.8.3 to 0.8.4, follow the following steps :
- TAKE CARE : as always before an upgrade process, backup your current LNF diretory,
- unpack the 0.8.4 LNF archive in your current LNF directory,
- edit the sitesettings.php3 file,
- add the following line $LNF_file_extension=".php"; before the ?> sign,
- copy the following files onto the same .php file (ex. : cp sitesettings.php3 sitesettings.php) :
- sitesettings.php3
- news-*pass.php3
- pass.php3
- usersettings.php3
- delete all the .php3 files of the LNF directory,
- delete all the .php files of the LNF/news directory,
- rename all the .php3 files of the LNF/news directory in a .php form.
3. Configuration
3.1 First step
- Edit the "sitesettings.php" file in your LNF directory.
- Put the URL of your LNF install directory in the $url variable
instead of the current "http://127.0.0.1/lnf/" value.
Example : http://www.my-site.com/lnf/
IMPORTANT : Don't forget the last /.
3.2 Permissions
If it is not already done, set the following permissions :
- read permission on all files in install directory for the user under which
the web server runs,
- read/write permissions on "*pass.php", "original-*.php"
and "*settings.php" files in install directory for the user under
which the web server runs,
- general (rwx) permission on "news", "news/mod" directories
for the user under which the web server runs,
- read/write permissions on "*.tpl" files in "templates"
and "templates/lnf.tpl" directories and those directories for the
user under which the web server runs.
Setting permissions with your FTP program (courtesy of "gallery"
program readme file): If you use CuteFTP or some other FTP program, you
may need to hunt around a bit to find the CHMOD command. In CuteFTP, right-click
the file you would like to CHMOD, select "Change File Attributes", then enter
the mode manually (ie. 755) in the "Manual" text box. If you can't figure it
out, try asking your ISP or reading the documentation for your FTP client.
3.3 Setting password
Because LNF uses PHP crypt function whose results have OS dependencies, you
have to generate original password (value : LNF). Do the following tasks :
- type the following URL : http://.../lnf-directory/init.php.
- copy "original-pass.php" to :
- "pass.php", "news-pass.php", "news-readerpass.php",
"news-posterpass.php" and "news-modpass.php" files
in the LNF install directory
(cp original-pass.php pass.php; cp original-pass.php news-readerpass.php;
cp original-pass.php news-modpass.php; cp original-pass.php news-posterpass.php)
For security purposes, please change the original password by using the admin
menu.
IMPORTANT : if you are into trouble with password, you can come back
to original value (ie LNF) by copying "original-pass.php" on "pass.php"
in LNf install directory (Site Admin password). For problems in topics, copy
"original-pass.php" on "<topicname>-modpass.php"
(topic moderator's password) or "<topicname>-pass.php" (topic
admin's password) scripts.
3.4 Running LaNewsFactory
Now, you just have to type the following URL : http://.../lnf-directory/listdir.php.
It is going to be the only URL you need to have access to all LNF functionnalities.
Now you just have to go in the admin menu to create your first topic. There
is no more default topic, you have to create it.
Select the "Login" item on the top of the screen. Choose Admin
as login type and enter LNF as password or the value you set if you have already
change it when it is asked to you (see Setting password).
The only site options you can set are :
- URL
is the URL of the LNF install directory. Don't forget the last "/".
- Title
is the site title that appears on top of the client's browser.
- Site behavior
is the way you want your site to work. You can choose between a news system
and a forum. In a news system, users can view all news on the same page or
news that talk about a specific topic. In a forum, users can access only to
a single topic at the same time. In an admin point of view, in a forum, each
topic has its own options, moderator and admin. In a news system, topic has
only got its own moderator.
- HTML style
Choose between available HTML style.
- Time difference between server and users
You can set the time you want to store for news creation and update. Usefull
when your site is hosted.
The rest of the configuration is available :
- by clicking on "topic options" link for a FORUMS site,
- by clicking on the "site options" link for a NEWS site
as seen on the following screen capture. For a detailled description of the
following screen, see the topic section :
4. News system VS Forums system
LaNewsFactory allows you to choose between 2 behaviors :
- News behavior : your site will display the news only in time order
from the newest one to the oldest one. No matter of the topic of the news.
- Forum behavior : your site will display the news on a per topic basis.
You can access the news of one topic at a time.
5. Access and posting Policy
LaNewsFactory allows you to set your own access/posting policy on a site (news
behavior) or on a topic basis (forum behavior). You can choose between the following
rules :
- site/topic news can be read by everyone or by logged users.
- posts can be done by everyone or by logged users.
When login is required, the user can choose to select the login type (reader,
poster, moderator or admin) and type the corresponding password.
- Reader It allows you to read the news if read access is locked.
- Poster It allows you to read the news and to post a news under this
site or forum.
- Admin It is the site admin profile. You can create/delete a topic,
modify site and all topic options, change all passwords, edit and moderate
news of all topics.
- Moderator You can moderate and edit news of this topic.
6. Topics
6.1 Understanding
What a topic is :
- a topic is a theme for news.
- a topic is created by the site admin.
- a topic could have a moderator [for a forums or a news site] .
- a topic has its own set of options
TAKE CARE : Most of the options are configurable at a topic level only
in the case of a forums site.
Topic options in a FORUMS site :
- Font
is the font that will be used in the HTML display of your news.
- Language
is the language used by LNF for text outside the news contents. You can
choose between : french (fr), english (us), spanish (es), german (de), portuguese
(pt), swedish (se), turkish (tr), dutch (nl) and italian (it).
- Number of news per page
is the number of news displayed per page on the main screen.
- Moderated site
is the setting of the site behavior against posting. Yes implies that a
news post has to wait for moderator agreement before publication.
- Moderator's email adress
is the adress (if a value is entered) which is going to receive an email
at each news submission if site is moderated.
IMPORTANT : the PHP version of the server needs to have PHP mail
function enabled and the given adress needs to be correct.
- Allow HTML in news
is the capability of allowing/prevent display of HTML statements in
news. Allowing it can be unsecure. Anyway, it does not prevent the user
to write HTML statements. If you prevent HTML, HTML statements will be displayed
as-is.
- Number of lines per news header
is the number of lines displayed in the preview form for a news on the main
screen.
- Depth of displayed answers
allows you to manage the depth of answers displayed on the same page. A
link to an other page is displayed instead of the news not displayed.
- Display links on top of the page
to choose if you want link on of the news
- Logo
is the image that will be used to illustrate the topic.
- Posting policy
Choose if users have to log in before posting a news or not.
- Access policy
Choose if users have to log in to access the site and read the news.
- Email notification for reply posting
Choose if a mail notification has to be sent the original news poster when
a reply is post to his news.
- Description
is the description of the current topic.
Topic options in a NEWS site :
6.2 Operations
List of the different possible operations (site admin toolbar displayed, TAKE
CARE : see "Options" instead of "Topic/Site Options") :
- create/delete a topic :
- click on topic creation/delete.
- login type required : site admin.
- the topic name can only contains letters and figures.
- change options :
- click on "options".
- login type required : site admin,
- manage/moderate news :
- click on news management or moderation.
- login type required : site admin, moderator.
- change password :
- click on change password,
- login type required : site admin.
7. Moderation
7.1 Understanding
Topic moderation status is the topic behavior against posting
:
- If the topic is moderated, news that are written will wait after
the moderator choice before being published. Since 0.4.5 version, you can
either select a group of news to delete or accept them. You can also, after
reading a news, choose to publish the news, to delete it or to modify it.
TAKE CARE : For the moment, only original posts are currently moderated.
Not the answers. It is simply due to the fact it is not obvious to code it.
It is on the TODO list to answer to the hope of Krzysztof Kudlacik ;-).
- If the topic is not moderated, all written news are directly published.
7.2 Operations
- You can switch the topic moderation status by web interface (topic options)
as seen in the "running LaNewsFactory" section.
- You have to click on "Moderation" menu to see if news are up to
publication.
- To read each of them, click on its title and then choose if you want
to modify it, publish it or delete it.
- To directly delete or publish news, select options boxes and click on
the correct button.
In fact, on unmoderated sites, news are directly written in the "news"
directory. On moderated sites, news are written in "news/mod" directory.
8. News management
News management is the possibility of deleting/editing an already published news.
Since 0.4.5 version, you can either select a group of news to delete them. You
can also read a news to delete or modify it. Click on "News management"
to do it.
Since 0.8.5 version, you have a "Trivial Edit" feature that provides a way to direct
edit the source of the news. To do it, click on the link at the right of the news title.
9. RDF/RSS export
You just have to execute rss.php script from a browser or a PHP script. You
receive then a file in RSS 1.0 format containing the first lines of each news. Interesting
with RSS
format is that RSS is a normalized (RSS 1.0 is at a specification proposal stage
in fact) export format. You can trust it to run automated LNF import job from a script
on another web site to display site headlines for instance.
10. Customization : HTML Templates
Since 0.6.1 version, LaNewsFactory's HTML aspect is stored under HTML templates
files. Thoses files are in the "templates/lnf/template_name" directory.
Look at the source of a LNF HTML page under your browser : comments will help
you to identify the HTML template file to modify.
The 4 files allow you to set up your page : head.tpl, left.tpl, right.tpl and
tail.tpl.To insert PHP coding, you can only do it in menu.php and tail.php
scripts : follow the insertion tag.
For colors, I use 3 files (colour1.tpl, colour2.tpl, colour3.tpl) that I use
in the PHP scripts. Change color values in it to set your LNF colors.
From a technical point of view, I use PHP
FastTemplate library. Thank to Sascha Schumann for his clear and straightforward
FastTemplate tutorial.
A. Appendixes
Main documentation is provided by this document.
Three mailing-lists are opened :
- developer mailing-list.
- announcement mailing-list.
- translation mailing-list.
Subcribe.
To make a bug report, use the LNF bug report tool and give :
- problem description,
- the different error messages that appears on the screen,
- the LNF version you use.
Final notes
LaNewsFactory intends to be an usefull web news software with less product
dependencies as possible. I am always interested by your suggestions and even
more by code ;-) Just send me both to me.
And, last but not the least, thank to Richard M. Stallman and the FSF crew for
creating GPL without nothing could have been happened.
Christophe Brocas.
PS : Sorry for my english but I am french ;-)