----------------------------------------- Kaos news v0.8 - news management script ----------------------------------------- -[ About ]------------------------------- Ok, quick overview of what the script does.. It looks after your sites' news, allowing use of multiple categories and user profiles, with a few funky features in various places.. It uses an MS Access database for storing the news, -most- Windows-based hosts will allow use of these. Note: I (the author of the script ;) have only ever used scripts that I've coded myself - generally a custom solution for a website i'm building - this is my first script written with a view to quick implemention of a newsboard. Any feedback on it would be appreciated as it is definitely a work in progress. -[ Requirements ]------------------------ Kaos should run fine on a IIS 5 platform, but the minimum requirements are as follows. - MS Active Server Pages version 3 (IIS 5) - VBScript version 5 or higher - MS Access 2000 Database support - MSXML parser version 3 or higher The user interface is designed for use with the latest releases of either Internet Explorer (Latest is 6) or Netscape (Latest is 6.1) -[ Installation ]------------------------ Installation is fairly simple (I think ;) Note: Your webhosting should have a secure directory somewhere, below/alongside the web publishing directory. Database files should be kept in this secure directory to stop any webuser from accessing the file and/or downloading it. The Access database used by the script should be kept in this directory. This secure directory is often called 'private', while the publishing directory is 'htdocs' or 'html' etc. Although one of my hosts uses 'db' for secure and 'webroot' for publishing. Find out which yours are, and adjust the following instructions accordingly. I shall refer to them as 'private' and 'htdocs'. The script uses what is known as a DSN-less connection. You will -not- need to register the database with the server. ==INSTALLING THE SCRIPT CODE== 1. Tell the script how to find the database directory. - In the zip file there is a file called 'DBconn.asp'. Open this in a text editor. - On line 4 there is this: 'zstrDBFilePath = Replace(Server.MapPath("\"),"htdocs","private") & "\kaos\kaosnews.mdb"' Replace 'htdocs' with the name of your webpublishing folder, and 'private' with the name of your secure folder. - Save this file. Make sure name remains as 'DBconn.asp'. 2. Upload the files to your webspace. - Create a folder in your secure directory (at root) called 'kaos'. ie; yourspace\private\kaos - Upload the 'kaosnews.mdb' file to it. - Create a folder in your publishing directory called 'kaos'. ie; yourspace\htdocs\kaos - Upload all files except 'kaosnews.mdb' to it. 3. Login and set script options up. - Open http://www.yourdomain.com/kaos/ui_index.asp in your browser. - Use [username: admin] and [password: admin] to login to the system. - Be sure to change your username and password - for security, I recommend not leaving it at the defaults. - This initial login cannot be deleted. ==USING IN WEBPAGES== Note: I have tried to make implementation of the script as simple as possible, while still leaving control and display purely at the hands of the site designer. This means that most things in the script are set easily via webbased forms, but some require you to get your hands dirty with files and handcoding :) Implentation of the script is done by including the script code onto your webpage, then using special markup to insert the script elements such as news items, previous post index, etc. Design your page as normal - standard HTML stuff or whatever, leaving markers for where you want the elements to appear - a template of sorts. The extension of the file MUST be .asp - news.asp would be a typical example. Be sure to include the displayJScript.js file - this contains the neccessary javascript needed to power the expandable comments functions. This is done using the following code First, insert the following line somewhere on your page. I recommend having it on the line immediately before your first call for a script element. Then you are free to include the elements into your page. Simply use one of the following.. <% Call displayNews() %> - Writes the main news display to browser. <% Call displayPageNav() %> - Writes the multi-page navigation options. ie; 'Page 1 of 2 - Jump to: 1 2' <% Call displayIndex() %> - Writes the previous-post index. <% Call displaySearch() %> - Writes the post search options form. Finally, once all the elements you require have been included, use the following to shut the script down. <% Call Shutdown() %> - I recommend you to always remember to use this. Thats all you need to implement a 'standard' news page - set once and it functions the same way forever. All that remains is to set the options and display structure that the script will use (more on that below) But, as well as being able to power the 'standard' version, the script functions can be altered by overriding its default options at page level before the elements are included. See 'Possible tweaks to output' below for more information on how to do this ==SETTING DISPLAY OPTIONS== These are set in 3 parts. 1. Set the default options for output. Open ui_scriptoptions.asp in your browser. Simply change values in the form you are presented with. If you are running IE5+ then clicking on any text you get a help cursor on will give you appropriate info. 2. Set the repeating structures for posts, comments and the post index. This is done by opening ui_scriptstructure.asp in your browser and using the form to set them. Element structures are essentially HTML shells into which the post data is inserted - you write the HTML as you would in a static HTML page, but instead of writing specific information, you tell the script where to insert it. This is done using special tags that the script can recognise - [title] for where to insert the title, [content] for where to insert the post content, etc. - An example of a basic structure for a news item could be:

[title]
[content]

This would be interpretted by Kaos as:

- start paragraph. [title] - write the post's title. ie; 'Its official, counterstrike sucks'
- insert a linebreak. [content] - write the post's content. ie; 'Read more over at cs-sucks.com'

- end the paragraph. Kaos would then send the following HTML to the browser, which would then be displayed just like a static page.

Its official, counterstrike sucks
Read more over at cs-sucks.com

Individual elements such as date can be set on the ui_scriptstructure.asp page via a simple form. In the case of date, there are 2 preset options to choose from, or you can set your own. Kaos also has a predefined structure - the default output - which is available for use at any time. This can be used to forgo writing a structure yourself. - The default output of kaos is valid HTML 4.01 Transitional, and so assuming it is used in conjunction with a page that is also valid, shouldn't give any problems. It displays fine on recent versions of Internet Explorer and Netscape. The default structure is highly customisable when used alongside a Cascading Style Sheet (.css) - The script includes a prewritten CSS file which could be altered to suit your design. 3. Style the forms used for user-comments and searching posts. These 2 display pages use very little ASP code in them, so I've chosen to leave their construction with you :) As long as you follow these few rules, you can put pretty much any HTML you like in them. # User-Comments form. This file -MUST- be called displayForm.asp and kept in the /kaos folder with other script code. The form tag must take the following structure.
..
A hidden input must be included in the form. The code needed is below. "> The submit button needs to have the following attribute if you wish to have the browser check that a comment was entered before allowing submission - this can save on server page requests. onClick="zValidateForm(); return false;" If you wish to disable this check, remove the onSubmit attribute from the form tag. # Post-search form. This file -MUST- be called displaySearch.asp and kept in the /kaos folder with other script code. Well, describing this would probably take a lot of lines.. so I'm going to assume you're not a dumbass and at least know your way around HTML ;p Open up the displaySearch.asp file and use the form objects in that - just set the class/style attributes and the surrounding HTML. Not all form objects are neccessary. Make sure to keep the form name attributes intact, or they will be as good as useless as the script wont recognise them. The search by user/category selects use ASP code to populate the object instead of hardcoded HTML. Be sure to leave this <% .. %> intact, or the select will be empty. Other than that, all you must remember is to leave the first 3 lines and the last 2 lines intact. Again, so the script recognises the page when it tries to include it in the display. That's it. Unless you are using the default output. In which case, you will need to alter the .css file to suit your site. Other than that, you should have a fully functional page. ==POSSIBLE TWEAKS TO OUTPUT== It is possible to override the options the script uses when displaying elements. This is done in much the same way as including the elements - <% option = new value %> ## All option overrides must be done AFTER the ## Possible overrides are: <% PageSubCategory = "x" %> - Restricts the categories from which Kaos retrieves news from. x is a number, or numbers seperated by a comma. DO NOT use spaces in the value. Be sure to retain the quotes. The numbers represent category references. ie, x = 1,3 would restrict Kaos to using category #1 and #3. Note: I recommend using this only once, set before the first element is requested. <% PostsPerPage = x %> - The number of posts Kaos will include in the main display output. <% DaysPerPage = x %> - Restricts the main display to posts that were added in last x days. <% CommentsPerPost = x %> - The number of comments 'expandable' on the main display page. <% PostsPerIndex = x %> - The number of post headlines that are included in the index. <% PostSkipInIndex = x %> - The number of headlines the index should skip before displaying. The above options all use the same range as the equivalents on the ui_scriptoptions.asp form. ==ADDITIONAL ASP-RELATED INFORMATION== There is a variable which can be used to make site structure a little easier. To use it will undoubtedly require some knowledge of vbscript, but that could be as simple as writing an if..then construct. The variable, zblnSinglePost, is of boolean subtype. It holds False if the page is main postlist display (normal use) and True if a single post has been requested. A typical use for it could be 'If [page being used normally] Then [display search form]' This would mean that the script wouldnt write the search form if the page was being used for a single post. The code for this would be: <% If Not zblnSinglePost Then Call displaySearch() End If %> -[ About the interface ]----------------- Note: The interface that is included with this release is definitely not the final version. I have plans for some extra funky stuff, which I haven't included in this build due to time constraints. Any suggestions or feedback appreciated. [chrisb@webkaos.co.uk] Log into the system by opening 'http://www.yourdomain.com/kaos/ui_index.asp' and filling in the form provided there. The initial account when the script is installed is user/pass: admin/admin This account cannot be deleted by anyone, so provided you keep the user/pass safe you shouldn't have any problems. I recommend changing the details of this default account as soon as you have logged in. - This can be done by clicking the 'login details' link on the navigation bar at top of page. When you have logged in, at the top of the page you will see 7 hyperlinks. These are links to various pages in the user interface for the script. The link: The page function: login details [0] | Shows details of your user account. Allows all users to change aspects of their account. add post [0] | The webbased form used to add posts to the database system. manage posts [1] | Gives a means of editing or deleting posts/comments in the database. | Also contains file generation options; allowing XML or HTML files to be generated. manage users [2] | Allows admin to modify/delete any user account. manage categories [3] | Manage category settings for the script. Add/edit/delete. set options [3] | Sets the options for the script. set structure [3] | Sets structure of the display output. The [x] after each link shows the user access level required to view and/or use the page. Each user you add to the system can be given the ability to modify the script in different ways. The default user access is 0, which basically means they can add news and alter their own profile. At level 1, the user may also modify/delete posts. Level 2 gives the ability to modify/delete user accounts. Level 3 is the master level, it allows the user to alter anything in the script. The initial account is level 3. I may write a full set of documentation for the interface, but as I know it will be changed soon I don't want to waste my time writing one, then redoing it all later. As it stands at the moment, it is fairly straightforward to use (in my opinion ;) I have included some javascript checks in the interface - so on most of the pages (every page but options/structure setting) the page will not allow you to submit information that it deems is invalid. It will point you in the general direction of what you have done wrong. -[ Other stuff ]------------------------ I made this! http://www.webkaos.co.uk | chrisb@webkaos.co.uk It has taken me a good few hours to code, and is free to use for everyone.. so please don't steal it or try to make money from it or anything like that. ta :) If you use the script on your website, I would appreciate an email informing me of the URL for it. It would be nice who is using it, and for what purpose :) Props to: - 50sQuiff, who provided a little light encouragement to get off my arse and write this thing... - Iron Maiden, Metallica, Slipknot, Malmsteen.. for providing the music to pass the long boring hours :) Along with that, big shout to IIDogZ for upping a good few slipknot ch00nZ :D E n j o y.