			 PHPGen README

What is it ?
============
PHPGen is a PHP-script I use to make a framework for a new
PHP-application. I noticed after I'd done my first few applications
that most of the time I was editing old code to make new. That is
good, but why not make it a little more automatic ? (and reduce
stupid errors).

I sat down and made the first version of PHPGen. I've used it many
times since then, and even if it's not perfect it has saved me a lot
of typing.

Maybe you also find it useful? If not, it's easy to uninstall !

And also, maybe this is a humble start to something REALLY
useful? Together we can rule the world (or at least get some free
beer as a well-known person puts it....)

Basic theory
============
PHPGen generates a one-file script(update: if one wishes, he could tell phpgen
to generate many files, one file per functional block of code, which could
be shared between different scripts) that calls itself with the parameter
"$func". $func determines what should be done with the rest of the
data.

The script allows listing, searching, appending and editing of data
in an SQL database (or rather in one table of a database). The table
is supposed to have one field that is an unique index for each record.
(personally I always has an autoincrement field as an unique index)

In the start-form (genform.php3) you specify:
* The name of the themefile
* The name of the database
* The name of the table
* The filename of the generated file (without .php3 extension)
* The name of the unique field and if it is numeric or not

For each EDITABLE FIELD in the table you specify:
* The title (what the user sees, leave the title empty if you want to 
  hide the field from the user)
* The name (MySQL fieldname)
* Maximum input size (number of characters)
* Field width (in the edit/new-form)
* The type of field
* The sort of input tag you want for the field
* Depending on type of input tag, possible extra data to generate
  the input the right way.
* If the field should be searchable
* If the field should be shown in lists

When you press "Generate" the script is generated and stored with
the choosen filename in the directory projects together with its
associated project file (can be used to regenerate a file).

*** In version 0.4 and higher a new form, pregen.php3 can assist you with filling
in the form by reading the database/table directly from the SQL
server. This obviously requires you to have a working connection
with the server. Please note that this help is OPTIONAL, you can
still go directly to genform.php3 and enter the data manually.

Thats it. If you have any suggestion, comments or otherwise just like
to communicate, feel free to send a mail to laplace@hem1.passagen.se

Sharing files between scripts
=============================
It's a new feature of PHPGen. In genform.php3 under the tables with
descriptions of SQL tale columns, you have table with filenames from which
script is being generated. It gives you great oportunity of selecting, which
files should be shared (and which not) and specifying path of file, where
this sharable source code should be stored. You can choose the way the piece
of code is incorporated (or not) into generating script:
  * include
  * copy
  * force copy
  * ignore

If you choose "include" option, piece of code will be physically written
into main script, as it was in previous versions of PHPGen.
If you choose "copy if it doesn't exist" option, source file from first
editable column will be copied into file you specify in second column if the
destination file doesn't exist.
"force copy" will do what "copy" does, overwriting previous contents of
destination file.
"ignore" will ignore this piece of code completely, allowing you i.e. to not
include Java Script at all.

Let's say you generated some script and you choosed to use shared files. You
edited file browse.php3, because default behaviour of this code didn't suit
your needs. Now, You need to add some column to the SQL table. You do it,
you want to re-generate script with new column and not to loose changes made
to browse.php3. You take phpgen, load project file and just need to put your
edited browse.php3 filename into second column (destination file, PHPGen probably
saved its name into project file and you don't have to change it) and select
"copy if it doesn't exist". Your own browse.php3 file won't be overwritten,
because it exists and proper inclusion code will be put into main script.

With this feature you can share database settings (database host name, SQL
user, password and database engine type) between your generated scripts
(these settings are called 'common settings').

If you choose to use shared source files, you got additional benefits, I.e.
You generated hundreds of scripts, and it occured, that in sql.php3 a bug
exists, it appears when you have more than 1000 records in your table.
You correct shared sql.php3 file and you have correct behaviour of your
EVERY generated script! The same could be done i.e. when new version of PHPGen
would be released, featuring some nice fancy menus.


Themefiles
==========
(Reside in ./themes)
A themefile is a file with regular PHP-variables which inserted to
the generated code at appropriate places. 
Please send me nice-looking themefiles, as you may have noticed I'm
not much of an artist......

The variable "language" selects which "*.NLS" - file (resides in ./NLS)
that should be used to insert all visible text in the generated file. If you
make your own NLS-files (in another language) , please send them 
to me so I can redistribute them. 

Were did you find it ? (if you forgot...)
=======================================

You can fetch the latest version of PHPGen via HTTP from my homepage:

	http://www.byggsoft.se/~mikaelu

Suggestions and stuff:
	laplace@hem1.passagen.se, mikael.ulfenborg@byggsoft.se

There is also a mailinglist for PHPGen. Visit
http://hlug.org/mailman/listinfo/phpgen-discuss
(Thank you Chauncey Thorn at hlug for this one)

Enjoy!
