PHP GEN Documentation
Last modified: 25 Dec 2006.
- PHP: latest version of PHP GEN was developed on a machine running PHP 5.1.4.
- Database: latest version of PHP GEN was developed on a machine running MySQL 5.0.21.
- Pear::DB: Database Abastraction Layer. Installation Instructions. Currently supported database backends are listed here (middle of the page).
- Smarty: 'Template/Presentation Framework' (unmodified copy included in PHP GEN, in php_gen-x.x/common/Smarty/).
- GD Graphics Library: version > 2.0.1 (only required if you want thumbnails or image resize)
Optional:
- Pear::BBCode: a parser to replace UBB style tags with their html equivalents.
Taken from the README file.
- Make sure Pear::DB package (http://pear.php.net/package/DB) is installed
on your system.
!!IMPORTANT: Make sure php's magic_quotes_gpc is enabled while using PHP GEN!!
You can set this in php.ini or per directory using htaccess (if supported
by your webserver).
An example .htaccess:
php_value magic_quotes_gpc 1
- Decompress the tarball (OK, I guess you already did so)
- Move the contents to a directory accessible by the webserver (referring to as /www/php_gen/ from now on)
- Create .htaccess shown above in /www/php_gen/ if necessary
- Make following directories writable to the user running the webserver:
- /www/php_gen/engine/templates_c/ (used by Smarty for storing compiled templates)
- /www/php_gen/table_config/ (used for storing table configurations)
- /www/php_gen/output/ (used for storing generated scripts)
Also make sure all (if any) files and subdirectories contained in those directores are writable by that user.
- Configure the folder and database connection settings in /www/php_gen/common/config.php.
! Don't just copy this file from an older release, as new configuration settings might be added !
- Point your browser to the web page corresponding to /www/php_gen/engine/install.php
- If all tests ran succesful, you can continue to "Select Table"
To use the sample tables:
- Create a database testdb.
- Execute the SQL queries listed in /www/php_gen/testdb/testdb.mysql (warning: this file contains queries to drop tables 'product' and 'brand' should they already exist).
- Configure PHP GEN to use testdb in /www/php_gen/common/config.php (set 'DB_NAME' to 'testdb')
- Point your browser to /www/php_gen/engine/select_table.php.
- Generate scripts for the table 'product', restoring configuration from testdb.product.php. Configurations for tables 'brand' and 'category' are included but they don't do anything special.
On this page you can select for which table you'd like to generate scripts. A checkbox is available for restoring a previous config file (if available in /www/php_gen/table_config/)
On this page you can enter basic configuration for each table column.
- Field: name of column in the database.
- Name [text]: specify the visual name that the user will see for each field.
- Type [select]: choose the HTML widget that will be used in the forms for handling the field.
- text: text input on forms.
- checkbox: checkbox input on forms.
- select (fix): select from fixed options (specified in 'Additional Info').
- select (master/detail): select from foreign table (specified in 'Additional Info').
- textarea: textarea input on forms.
- password: password input on forms.
- file: file input on forms.
- datetime: use Smarty's functions html_select_date and html_select_time to render form element.
- date: use Smarty's function html_select_date to render form element.
- time: use Smarty's function html_select_time to render form element.
- year: use Smarty's function html_select_date to render form element.
- ID [checkbox]: specify which fields make up primary key. As of version 1.3 multiple columns can used to construct the primary key, there's only one limitation (for now): values of the columns used in primary key may NOT contain the following string '___;;___'.
- Search [checkbox]: include field in search form.
- List [checkbox]: show field on list pages.
- Add [checkbox]: show field on add pages.
- Edit [checkbox]: show field on edit pages.
- Details [checkbox]: show field on details pages.
- Mandatory [checkbox]: mandatory on edit/add forms.
- Records per page [text]: number of records per page on the list page, use a value smaller than (or equal to) 0 to list all records.
- MAX_FILE_SIZE [text]: maximum filesize for uploaded files, in bytes.
- Links [text]: if you want to link the scripts of this table to other tables, fill (or leave as suggested) the link values, otherwise make them empty.
Following options are common to all types, which was configured for each field in the previous step:
- Attributes [text]: code which will be added inside
<input> tags. Use it for assigning CSS styles/classes, defining the sizes of a textarea (eg. rows="10" cols="60"), etc.
- Form Hint [text]: HTML code which will be displayed next to field on add/edit forms. (make sure you encode special characters like >, <, ...)
- Content Type [select]: how content of each field will be treated (not for password, checkbox, datetime, date, time, and year type of fields.)
- text: rendered as plain text, any special characters are converted. In case Type is textarea, also converting linebreaks to
<br>-tags.
- html: rendered as HTML code.
- url: rendered as hyperlink, any kind of link (http, ftp, ...). If no scheme is specified in the values, http is assumed.
- generic file: rendered as hyperlink to the actual file on list and details pages
- image file: rendered as image on list and details pages
Following options are 'Type' dependent, which was configured for each field in the previous step:
- Select (fix): configure the fixed values and outputs to be used.
- Values [text]: comma-separated list of actual values that will be read from or written to the database (e.g.: 1,2,3)
- Outputs [text]: comma-separated list of values seen/choosen by the user in the generated pages (e.g.: Poor,Regular,Good).
- Select (master/detail): select the database fields used to retrieve the values and outputs. Both of them should be from the same table
- Values [select]: actual values that will be read from or written to the current database, normally the foreign key.
- Outputs: as seen/choosen by the user in the generated pages.
- [select]: select a single column from the foreign table
- [text]: by supplying a custom pattern, it is possible to show more advanced output to the user. This pattern is searched for strings encapsulated in curly braces ({}), those strings must specify column names in the foreign table (just the column name, table name may not be included). If you need curly braces in the actual output, you must escape them with a backslash.
For example: in the sample tables we supply a pattern like '<b>{name}</b> ({brand_id})' instead of just selecting 'brand.name' from the HTML select.
- Store outputs by [text]: comma separated list of columns to sort outputs by. Prefix a column with '-'(minus sign) to reverse sort order on that column. eg. 'name, -id'
- Allow add? [checkbox]*: Whether to allow a new master/detail record to be added through add/edit forms of a detail/master record.
If enabled, a text box will appear next to the HTML select on add/edit forms. When a value is inserted in that text box, it will be used to add a record to the foreign table, setting the column selected in 'Outputs [select]' to that value. So be sure to select one, even when you use a custom pattern. (This feature only works on single-attribute foreign keys.)
WARNING: blatantly assumes the column selected as 'Values [select]' to have MySQL's auto_increment-option set (so we can use LAST_INSERT_ID()). There are no checks in place yet!!
- Generic File:
- Restrict file extensions [text]: comma-seperated list of file extensions to be allowed (whitespace ignored), leave this option empty to allow all file extensions. For the extension, PHP GEN uses the part of the filename after the LAST dot (so no 'tar.gz' but 'gz')
WARNING: this is an insecure method for restricting file types (hoping server software AND users will do the right thing). We're looking into alternatives (like the PHP extension 'Fileinfo') to offer more security.
- On change delete file [checkbox]: delete the stored file when new file is uploaded or record is deleted.
- Image File:
- Restrict file extensions [text]: comma-seperated list of file extensions to be allowed (whitespace ignored), leave this option empty to allow all file extensions. For the extension, PHP GEN uses the part of the filename after the LAST dot (so no 'tar.gz' but 'gz')
WARNING: this is an insecure method for restricting file types (hoping server software AND users will do the right thing). We're looking into alternatives (like the PHP extension 'Fileinfo') to offer more security.
- On change delete file [checkbox]: delete the stored file when new file is uploaded or record is deleted.
- Maximum image size [text]: specify maximum image width and/or height for uploaded images. (only supports JPG, PNG and GIF for now)
- Thumbnail size [select]: image size for generated thumbnails.
- Show thumbnail on details [checkbox]: if enabled, the thumbnail will also be shown on details pages.
- On change delete thumbnail [checkbox]: delete thumbnail when new file is uploaded or record is deleted. If 'on change delete file' is enabled for this field, this setting has no effect: thumbnail will be deleted along with the image.
- Date & Time Options:
* only supported when using MySQL (for now)
If everything went OK, you should be offered a link to the list page and a link to step 1 to configure more tables.
If something went wrong... double check your configurations (of both PHP GEN and current table) or you can leave a message at the support forums.
Past changes to this document include:
- 07-Jul-2006:
- 27-Apr-2006: updated link to support forums
- 16-Apr-2006: updated documentation for v1.6: new field types datetime, date, time and year; 'sort outputs by' for select (master/detail)
- 04-Mar-2006: made sure document was valid XHTML.