Location: PHPKode > projects > HB-NS > hb-ns/install/README.txt
########################################################################

	HB-NS (Harold Bakker's NewsScript) 1.3
	Harold Bakker, hide@address.com
	http://www.haroldbakker.com/

########################################################################


------------------------------------------------------------------------
WHAT IT IS

A simple php script meant to enable one to update a webpage with short to medium long pieces of text, without having to use an HTML editor and ftp client.
Useful for blogs, travelogs, siteupdate notes, homepagenews, changed visiting hours etc. etc.
The script accepts plain text, automatically converting returns to breaks or full fledged html so you can embed images and links when needed.
Latest additions: bugfixes, moderated comments, clicking Preview now saves a copy of your article in progress, should your browser crash you can use phpMyAdmin to retrieve it and not all wil be lost, preview early and often! and other stuff.

It is highly recommended you password protect the admin.php script using .htaccess or by using the inbuilt functionality.


------------------------------------------------------------------------
WHAT YOU WILL NEED

A Unix/Linux/MacOSX server with Apache 1.3.xx, PHP 4.x and MySQL 3.23.xx.
It might work with older and/or newer versions of those programs.


------------------------------------------------------------------------
WHAT IT COSTS

Nothing, it's free. You may even modify the script to your own liking/needs. If you do something really cool with it I would appreciate a note at hide@address.com though.
This script is released under the "Attribution-NonCommercial-ShareAlike 2.0" Creative Commons license: <http://creativecommons.org/licenses/by-nc-sa/2.0/>.
If you feel the need to pay mne you may do so by looking at my Amazon wish list (http://www.amazon.com/exec/obidos/wishlist/2WPUHKGRQ5ZOS/102-5193530-1870535) and purchasing something for me, this is entirely up to you.


------------------------------------------------------------------------
LAYOUT/STYLE

You can modify the script's output to your own layout and style by modifying the included header and footer files and changing the styesheet: head.php, foot.php and style.css.
Look in the stylesheet for the lines below /*	classes for news	*/. Also look at the optional modification section in configuration.php.
If you feel up to it you could also change the php code for more control/functionality (see WHAT IT COSTS).


------------------------------------------------------------------------
COOL STUFF

The script has a simple method to queue newsitems for later publication, please take note of the correct format in admin.php: (YYYY-MM-DD). 
In the add news functionality of the script you will find this named as "Push date".
The script can also automatically expire newsitems after a certain date, this uses the same format as 'Push date'.
If you are running a site where multiple people may add newsitems the script can notify you when someone adds or modifies a newsitem.
The script features a preview mode as of version 1.1.1, as of version 1.3 previews are saved in the case of a browsercrash. Posted comments can be edited by the poster if (s)he has set a password or the administrator. Comment are moderated as of version 1.3, however if a poster uses a password and a comment by her has already been approved the new one will be approved automatically.


------------------------------------------------------------------------
INSTALLING

To begin using the scripts change the first couple of lines in configuration.php and admin.php to reflect your setup, see also LAYOUT/STYLE.
Choose one of the two options below depending on your level of experience.

The easy way:
Upload all the files to your server and access http://www.yourserver.com/installdirectory/install/install.php.
You will be notified that three tables have been created: the data table, the preview table and the comments table. After that you may delete the entire install directory from your server, it is no longer needed.
Follow the instructions in install.php on making the rss.xml file writeable for the webserver.


The hard way:
You can also run blog.sql (from the install directoy) through phpMyAdmin (recommended, http://www.phpmyadmin.net/) or use the commandline. Consult the documentation that came with phpMyAdmin on how to create the table from a textfile if you're uncertain h

ow this works.
Make the file rss.xml writable by the webserver by issuing a chmod 664 command.


An important note on the rss.xml file:
This file should be writable by the webserver. Most of the time it is enough to CHMOD this file 664, but on some configurations it is necessary to issue CHMOD 666.


------------------------------------------------------------------------
UPDATING

UPDATING THE DATABASE:

From newsscript version 1.1.6 or later to version 1.3:
Run upgrade_from_1.2_to_1.3.sql.

From newsscript version 1.1.6 to version 1.2:
No changes in the database.

From newsscript version 1.1.1 to version 1.1.6:
Run upgrade_from_1.1.2_to_1.1.6.sql through phpMyAdmin.

From newsscript version 1.0.0 or 1.0.1 to 1.1.3:
Look in upgrade_from_1.1.2_to_1.1.6.sql and uncomment the line that starts out with "ALTER TABLE".


UPDATING THE PAGES:
All versions:
You should always upgrade the language files, configuration.php, admin.php, index.php and functions.php. Most of the time there is no need to replace head.php and foot.php. though it is still recommended as some small new improvements may have been added which I forgot to document.

From version 1.0 through to 1.1.3 to version 1.2:
It is recommended you start with a clean version of head.php and style.css and customise those as needed as there were some changes and bugfixes in the workings of the script.

If you don't want to start completely anew take a look at the files head.php and style.css and make the necessary changes yourself.
There are some comments to help you out there.

Make sure the file rss.xml is writeable by the webserver, see INSTALLING.


------------------------------------------------------------------------
DEMO

Feel free to use the demo located at http://www.haroldbakker.com/php/demonews/ to familiarize yourself with the script before downloading/installing. If this doesn't answer your questions feel free to e-mail me. This demoversion may not have all the functionality but should give a good idea of basic editing for admins.


------------------------------------------------------------------------
TESTED ON

Several different Linux flavors and Mac OS X 10.3 and 10.4 (Panther/Tiger) with Apache 1.3.2x, PHP 4.2.x, MySQL 4.1.xx

Minor testing has been done on Mac OS X 10.5 (Leopard) with Apache 2.2.6 and PHP 5.2.4.

------------------------------------------------------------------------
VERSION HISTORY

Version 1.3
- As of version 1.3 previews of new articles are saved in the case of a browsercrash or accidental closing of the browserwindow, you can use the admin interface to retrieve the text from the preview, remember to use the preview button!
- Comments are moderated as of version 1.3, however if a poster uses a password and a comment by her has already been approved the new one will be approved automatically.
- Minor fixes in the admin interface.
- Added an rss feed for unapproved comments.
- Added security fixes for comments: comments can only be deleted by admins (log in to admin.php first), if comments are disabled the form is no longer shown if you know the url to the form and comments are no longer saved even if they're posted by a script for example.
- Really long titles are now truncated in admin.php, this is merely cosmetic.



Version 1.2
- Better handling of old items that were imported from newsscript version 1.0 through to 1.1.2. As these have no date the permalink at te bottom of the article showed loads of zero's, now it just shows # date unknown #.
- Expired or not yet available items are no longer shown via their permalink, additionally comments to expired articles no longer show up in the sidebar if you use that module.
- RSS feeds now have the correct content-type (oops).
- A poster's name is now included in the commentfeed.
- On the admin page a newly added or updated item now includes a link to easily allow you to edit that item again, without the hassle of clicking to the update page and then on the item. Handy for those silly spelling mistakes.
- The listview of all items in the newsadministration is now much easier to read thanks to a special style which provides a dotted underline on each row.
- 'Show Topics' now shows the amount of articles in each topic so the reader has some idea of how many articles there are before clicking through, also handy for seeing how much you post in a particular category.
- Comments no longer show email adresses.
- URLs for user homepages in the comments are now forced to begin with http://.
- Links for the archive (Go to page:) page-navigation now use special classes (navlink and navlinkactive).
- Added a static RSS XML file, see INSTALLING.
- Deleted a NULL character in this readme that caused display issues in some circumstances.
- Fixed an date/time display issue in the admin interface for just entered newsitems.
- Added a calendar view (see index.php?action=list at the bottom)
- Added user input sanitizing to prevent XSS and SQL injections (kudos to Aliaksandr Hartsuyeu of http://evuln.com)


Version 1.1.7 (internal build, not released)
- Fixed a bug with extraneous slashes in the comments on some installations.
- Permanent links are now of the form index.php?article=n, without the action=list part (provides easier to read url's and will hopefully be easier for search engines to index).
- ?action=topic now lists the topics alphabetically instead of the order in which they were entered when you added the topics.
- Comments are now listed chronologically (oldest first) to ease discussion/reading.
- Enhancements to the code of the commentsystem (border around preview and much less scrolling when previewing, adding and editing comments).


Version 1.1.6
- The javascript for bbCode is no longer included in the file but referenced as an external file due to a bug in some newer PHP installation.
- bbCode can now also be used in comments.


Version 1.1.5
- Removed a duplicate edit link in the comment section that appeared when you've got both an administratorcookie and have a passwordcookie for a comment entry.


Version 1.1.4
- Squashed a few bugs when register globals was off.
- Squashed bug where there was a conflict between the latest headlines and/or latest comments and the main script, if the latest ... was put in the layout before the main script.
- Added tooltips to the admin form elements for adding and updating items (using localised title attributes).
- Fixed some annoying problems with slashes in the comments and the admin module.
- Added a link to show all topics in an installation.
- Added general enhancements to allow for better customisition with CSS.
- Added bbCode for abbreviations: [abbr=HyperText Markup Language]HTML[/abbr].
- bbCode can be used in comments as well, though there is no interface (like in the admin script) for doing so (as of yet).
- Added a passwordfield to comments so people can edit their own comments, also added a cookie for admin users so they can edit ALL comments.


Version 1.1.3
- Added a comment option.
- Added an RSS feed for the latest comments (the script defaults to showing the last 10 items, overrule in rss_comments.php, line 12 or on a case-by-case basis: http://www.yourdomain.com/rss_comments.php?rss_limit=n, where n is an arbitrary number).
- New lay-out.
- Topic system introduced.
- You can now only show certain topics in your feed: call the rss feed like so: http://www.yourdomain.com/rss.php?topic=x, where x is the topic of choice (you can still add a certain number of items to show by appending the following: &rss_limit=n).
- Greatly enhanced administrative module.
- Install script added for those without phpMyAdmin or commandline access.


Version 1.1.2
- Added localisation options (included languages: Dutch and English). If you want to add languages make a copy of lang/en.php and lang/bbcodeen.js and change "en" to the countrycode of your choice. Also change $language = "en"; in configuration.php to ref

lect this country code. If you are happy with your changes you can submit the changes and they will be included in a future release.
- Added the files in the directory "extra" as small examples to enhance your site. Please read the comments at the top of these files carefully about usage and limitations, in particular take a look at the filepaths if you move these files.
- Squashed a small bug in the previous version that prevented the display in the admin interface when you just added a newsitem but selected preview first. The item WAS added, the admin interface just got confused.
- Added listview (shows all titles) option to the newsscript, call it by adding "?action=list" to the url
- Added the possibility to include a permanent link to the article at the end of the text (it will add a # character with a link)
- Probably one the most usefull additions is the RSS feed module to syndicate news (in "extra"), you can adjust the amount of articles retrieved by using the parameter rss_limit=n where n is the number of articles to retrieve (example: http://www.haroldba

kker.com/rss.php?rss_limit=4). The directory "newspics" includes a small logo called "xml.gif" that is commonly used to indicate an rss feed. Place the image anywhere you want in a document and wrap it with a link to rss.php, using normal html like you wo

uld do with any image that is wrapped with a link.


Version 1.1.1
- Steamlined workflow in newsadmin.php so much less clicking is required when doing maintenance.
- The email a webmaster receives when a newsitem has been updated is much more readable.
- Lots of code modifications and added comments to enhance readability.
- Fixed a bug that could lead to double entries in the database when updating newsitems.
- Made the dateformats for news expiry and queueing a bit more readable.
- The script now correctly deals with apostrophes ( ' ) in text and titles, like in Persons's Home.
- Fixed a problem with the titles of the user interface.
- Added a much needed preview mode so you can freely change, add or remove text, see how it looks and only if you're completely satisfied commit those changes to the database, previously the item would become available immediately allowing visitors to see

 all your spelling mistakes.
- The script now not only accepts HTML but also a subset of bbcode, you can easily add hyperlinks, images, quotes, bold, italic and monospaced text. I have decided not to include font formatting like: <font face="Times" color="#FF0000" size="-1">small red

 serif words</font> as this kind of thing is deprecated in HTML 4, which the script outputs. If you want to add such styles you have a couple of options: modify the code or write html.
- Almost all options to modify the script to your liking have been moved to configuration.php, you will no longer need to add the database specifications to both the index and newsadmin pages.


Version 1.1.0
- Added an expiry field to newsitems so items can automatically not be shown after a certain date, also added indicators in newsadmin.php?action=update.
- Added authentication in newsadmin.php for those who aren't able to use .htaccess (read the comments carefully!).
- Added a mail function so you can see when collaborators have put up a newsitem.
- Changed the devider between newsitems to a new tablerow with grey background, you can easily change this in index.php in the optional modifications section near the top of the script.
- Added classes in the stylesheet for newstitle and newsbody to facilitate easier customisation.


Version 1.0.1
- This version fixes a small problem where the current pagenumber wasn't shown correctly in the header.


Version 1.0
- First version, based on different scripts I developed for my own private use on http://www.haroldbakker.com/ and my work for the library sites of the Hogeschool van Utrecht: http://www.mediatheek.hvu.nl/


------------------------------------------------------------------------
TO DO:

- documentation in HTML
- disable comments on specific posts
- filter for specific topics or exclude specific topics at top of document
- add config option to hide or show queueing/expiery fields in admin.php 
- backup databases from within admin.php
- Stuff ???
	You tell me:	hide@address.com
Return current item: HB-NS