PROGRAMMING_STYLE
07/28/2000
Freemed-YiRC Beta0.13
---------------------

In addition to the data models that are available for Freemed-YiRC, I am 
creating a Programming Style document that should assist in shortening the
learning curve associated with learning new open-source softare projects.

I consider myself a weird programmer, and so I want to make sure that the style
associated with Freemed-YiRC can be quickly understood to those who wish to 
modify Freemed-YiRC for use in their own situations.

All Freemed-YiRC PHP scripts generally look the same.  In order to keep each
one as simple as possible, they are divided into a header section, a body
section, and a footer section. 

A NOTE ABOUT SESSIONS:
The concept of a session isn't really a part of the foundation of a web server.
HTML makes no use of this.  One way to create the essense of a session is to
use 'cookies'.  PHP has some great cookie tools that can assist in making
sessions possible.  Hence, Freemed-YiRC uses cookies to create sessions.

===============
HEADER SECTION:
===============
<?php
	- Indicates the start of a PHP script.

include "freemed_yirc-vars.inc";
	- Include the global variable file.
include "freemed_yirc-funcs.inc";
	- Include the global function file.

fy_cookiecheck($cookie_user);
	- Makes sure that this user has a valid cookie.
fy_resetcookie($cookie_user, $cookie_id, $fy_cookietime);
	- Refreshes Cookies

NOTE:  The next 4 statements (except for the $sql= statement) are part of
Freemed-YiRC's 'SQL abstraction functions'.  Using these functions (and others)
Freemed-YiRC can work with EITHER MySQL OR PostgreSQL.  In addition it would
be a rather minor hack to make it work with any other databases which PHP has
functions for.  

# Check out $cookie_id with secdb.  Make sure 'ir' = 'X'.	- A comment (!)
$conn=fy_makeconn($fydb_type, $fydb_host, $fydb_user, $fydb_name);
	- This establishes a connection with the database
	  declared in freemed_yirc-vars.inc... as well as the DB user name
	  and DB server host name/IP.  This DB connection ends when the
	  script is done executing.
$sql = "SELECT * FROM fy_secdb WHERE loginid = '$cookie_id'";
	- This puts an SQL command into the variable $sql
$result_set=fy_execsql($fydb_type, $fydb_name, $conn, $sql);
	- This command actually executes the SQL command in $sql using the
	  database connection $conn and puts the number of the created index
	  into $result_set (if any rows are found)
$rows=fy_resultrows($fydb_type, $result_set);
	- This command simply figures out how many rows are in the index
	  $result_set

The next section (the first if statement block) gets the current users'
permissions (or lack thereof) from the security database.

The next section (the second if statement block) decides is this user does
indeed have permission to enter.  If not, then the user is given a message
stating that he/she isn't allowed in this part of Freemed-YiRC, and the
script terminates.

fy_starthtml("Freemed-YiRC: Incident Report Database","");
	- This function outputs the starting HTML necessary to start out
	  an HTML document.  The text in the first argument is used as the
	  <TITLE> data.  The second argument (blank here) is used it a 
	  <META> REFRESH tag is wished.
	
fy_startwindow();
	- This function outputs the HTML necessary to create the look 
	  of a 'window'.  It creates the black background as a table,
	  the grey foreground as another table, and the blue title bar
	  and the right-hand 'Main' and 'Close' buttons as the first line
	  in the table.  It then sets up a table which is left open for
	  the rest of the script.

fy_winprn("CENTER","","<B>Freemed-YiRC XXX<B>");
	- This function isn't just for the header, it is used to send a line
	  of text to the screen.  This function makes this easy because other-
	  wise, <TR> and <TD> or <TH> tags would be necessary everytime you
	  wish to send text to the screen.   The first argument defines the
	  alignment of the text.  The second argument is a number used if
	  a COLSPAN statement is wished.  The third argument is the text
	  itself.  Note that nearly any valid HTML may be used here.
	

=============
BODY SECTION:
=============

The scripts job is done primarily in this section

A few helpful functions for use in the body section:

fy_winprn (as described above)

fy_winback("","xxx.php3");
	- This function is used to create a link labeled 'BACK'.  This
	  function simply creates a link to the php script indicated in
	  the second argument.  The first argument is for use with a COLSPAN
	  statement, if so wished.  This statement is always centered.
	  Why use this function when the browser usually has this?
	  This function is helpful because the browser may not have a back
	  function!

fy_wincancel("","xxx.php3");
	- This function is used to create a link labeled 'CANCEL'.  This
	  function simply creates a link to the php script indicated in
	  the second argument.  The first argument is for use with a COLSPAN
	  statement, if so wished.  This statement is always centered.
	  This function is almost the same as the fy_winback function, execpt
	  that the link says 'CANCEL' instead of 'BACK'.  This is a good
	  thing to have in case the user screws up and decides that he may
	  not want to be where he/she is.  This provides a SAFE means of
	  transport to a safe place.  If not used in places where it should,
	  the user may decide to simply abort abnormally, and this may cause
	  the loss of data cohesion in places where it is not desired!


===============
FOOTER SECTION:
===============

fy_endwindow("User: $cookie_user");
	- This function sends the HTML necessary to end the appearance of
	  the 'window'.  This includes sending the end table tags, as well
	  as creating the last line of the window, which should usually display
	  the user name of the current user.  This is the only argument for
	  the function.

fy_endhtml();
	- This function simply sends the end HTML necessary to end the HTML
	  document.

?> 
	- This indicates the end of a PHP script.

I hope this document helps you out some!  Enjoy!
