EZ Perl -*- EZDB 3.0 User Manual

EZDB 3.02 ©

By Stephane Barde
webmaster@ezperl.com
January 31 2001
http://www.ezperl.com

@table of content

COPYRIGHT NOTICE:

Copyright 1998-2001 Stephane Barde. All Rights Reserved.

This program is being distributed as a FREEWARE.

It may be used and modified by anyone, as long as this copyright notice and the header
above remain intact, but any usage should be registered. (See the
chapter XIII- for registration information.) By using this
program you agree to indemnify Stephane Barde from any liability.

Selling the code for this program without prior written consent is
expressly forbidden. Obtain permission before redistributing this
program over the Internet or in any other medium. In all cases
copyright and header must remain intact.

Contributions are welcome and will be used exclusively to enhance
the script (contact EZ Perl at webmaster@ezperl.com)

I would off course appreciate to have some feedback about the
use you are doing with this script.

It also would be nice to make a link to the EZ Perl site http://www.ezperl.com

VERSION HISTORY:

3.02 1/31/01
- Binary uploads with NT.
- Updated examples set.

3.01 11/17/00
           - External query bug fixed
           - <header> and <footer> parsing fixed in the line display
           - Category Assignment right added at the group level
           - <select> form tag parsing fixed
           - HTML template at group level fixed
           - EzTree new global variables added

3.0 10/30/00
           - Bad word parsing (reject add/edit)
           - Bulk update fixed + file_name=~s/ /_/g;
           - Password expiration
           - EzTree optional
           - Password reminders
           - header-footer replaced by a single HTML template
           - cart system
           - crypted pwd
           - ~date, ~group, ~group_owner. Must use _*date, _*owner... and _~date,... to display special fields
           - Global vars interface
           - IP address login restrictions
           - Invalid login attempt counter
           - Order by insertion date sorting fixed
           - html_line_display at group level
           - cookie session check
           - html_line_display with

and

language	This variables defines which language pack must be loaded. You should specify a 2 letters value. By default, EZDB support english ('en') and french ('fr').
script_name	You can rename ezdb.cgi into any other name by changing this variable and renaming the script.
script_url	This is the script url. '.' by default.
session_max_duration	$session_max_duration is a variable defining the maximum duration of a session in seconds. If you log in and want to access the database $session_max_duration seconds after you signed in, you will have to log in again... $session_max_duration=86400; # This value clean the session file about every day...
log_archiving_duration	To prevent the log files to grow too much, log_archiving_duration define the number of seconds for which a record remains in the log files. In other words, this defines the range of the backup in seconds: ex: $log_archiving_duration=86400*7; this would keep a track of change made during the last 7 days.
enable_ip_check	Set this variable to 1 to enable IP check, 0 otherwise. When enabled, each time a user sign in, his IP address is registered by ezdb. Then, for each request of the users, the session number of this user is checked against his IP address. This enforces the security controls for accessing ezdb. BUT, some users can change their IP for each web request: 1 user having many IP addresses during the same session (AOL users) AND, some users can come behind firewalls (they work within a same company and share an Internet connection): 1 IP address for many users. (Note that theses users don't have the same IP within their LAN so that's no problematic for an intranet application). So what should you do? MOST of the users have a fixed IP during a given session (usually, you connect to your ISP and it gives you an IP that is fixed as long as you are connected). In an intranet environment, user are often running fixed IP. The good answer is: It depends... on what you are doing and on where your users are coming from...
ip_log_restriction	This variables enables ip based restriction at the login. For example, you might want to restrict the authorized IP address for the Administrator. The authorized IP are defined as regular expressions in the user_data table.
cookie_session_check	This variable enables cookie checks on every connection made with ezdb. Upon authentication, a session number is assigned to the user and carried on in the URL. When cookie checking is enabled, a second session number is sent to the user as a cookie and is controlled for each transaction.
max_invalid_attempt	This value block a user from being able to log in after x attempt. When a user is blocked, the Administrator (or any user being able to do updates on user_data) must reset the user's invalid attempt count to zero. Leave empty if you do not want to use this.
password_expiration	This variable defines the time a user can use an account without updating his password. When the user has reached the time limit, he cannot log in until he changes his password.
setup_on	This variable enables the setup report (ezdb.cgi?setup) when set to 1 We suggest that you turn it off once your setup is ok.
system_file_path	This is the path to the system database folder. Default value is ./system_db
generic_html_file_path	This is the path to the directory where the generic HTML files (ask_for_keywords.html,...) are located. The default value is ./system_db_html
default_html_template	This is the HTML template used unless connected for a database with a specific template (templates are replacing former html headers and footers).
eztree_on	Set to 1 to enable EzTree use
eztree_html_directory	The path to the directory where the EzTree generated file should be located ('./my_html' by default) This directory should be http readable.
eztree_data_directory	The directory path to the EzTree data file ('./my_db' by default)
eztree_html_url	The url to the generated EzTree files.
eztree_html_template	This defines the HTML template file used for the EzTree directory. This file should contain the special tag %%content%% that will be parsed and replaced by the EzTree content using the following content template:
eztree_html_content	This file is the HTML content file used to shows the content of EzTree
mail_from	The email address of the notifications sender
mail_signature	The signature of the mail.
mail_routine_path	The complete path to the mail subroutine (EZDB was tested with sendmail only). Under NT, you suggest you use Blat.

Database name	this is the alias followed by -- and then by the entire path of the flat file (with extension and path): ex: phone--/usr/home/database/phone.csv
Path to the HTML Display and Form File	HTML files location: this is the path to the HTML files for display (full and line mode, cf VII) and input (You can put them anywhere but specify the path correctly... cf IV for more info)
Delimiter	the field separator used in your flat database file Note: \| will be translated into 'pipe'
Path and URL of the Static Output directory	You can associate One (1) static file per record: specify here the server path to the directory storing these html files, and the URL to access these files through the web.
Files' extension	It is possible to select the files’ extension, which allows for example to generate XML or WML files from your flat database
Field used for files' name	Used to name the output files using the name of one of the field. Note: The Static Output directory must be 666 and allow http access for the generated files.
EzTree Fields	Specify here which fields will be used in the eztree file. See discussion in the EzTree Chapter for more information Syntax: record_name--field1--field2
Path to the HTML Line Display File	Path of the HTML file used to display results in line mode (see Display Mode).
Path to the No Match HTML File	Path of the HTML file used when no record match a query.
Field displayed and Color used (Default Result Mode)	This is for Default Display Mode Only. When you are searching for a record, EZDB first display every record matching the search. It shows then (in order to let you choose the one you want to see) the field listed here and use the colors as cell background and text color. Field Syntax: Alias1:field_name1--Alias2:field_name2--... Color Syntax: background1/text1--background2/text2--... If You do not define any text color, the default color will be used. Ex: Fields displayed for result: User Name:name--Phone No:phone Colors used: ff5533/ffffff--cecece Tips: If the alias is the same as the filed_name, you can just specify the alias (it's not case sensitive): Fields displayed for result: Name--Phone No:phone
Search Result Mode	c.f. ch V and VII for detailed information
Direct Full Display	When there is just one match for a search, EZDB can directly format the result (display phase) or present it with the regular search result interface (retrieve phase).
Order By	You can specify which fields will be used for sorting the results in alphabetical order. Just enter a list of database field separated by -- or a comma, Use 'reverse to sort by reverse order: Ex: order_by = reverse name would sort by name with a reverse order.
Password protection field	One of the database field used as a password to protect EACH record of a database. Ex: you could setup the 'nickname' field of the contact database to be used as a password protection for each contact.
Bulk Delete	Set to Yes to enable bulk deletion of records: You do not have to display the records one by one to delete them if turned on.
Mandatory Fields	Defines fields that are required for insertion. Syntax: field1--field2--field3...
Unique Constraint	Defines uniqueness constraint for fields or group of fields. Syntax: field1+field2+field3+...--field11+field12+...--... Ex: Let's say you have a phone database: you want the phone numbers to be unique (a phone number appears 1 time only in the database) and you also want the couple of identifier (first_name, last_name) to be unique. Here is the syntax: Unique Constraint: phone--first_name+last_name
Bad Words Parsing	This is used to block users from submitting unwanted words. Syntax: field1--field2--field3--...:bad_word1,bad_word2,... Ex: hobby--passion:iis,windows,asp Let's say you don't want ms fans in your database...
File Upload	EZDB allow automatic file upload. When you want to store files in your database, define the Target Directory where the files will be stored (this is the server path to this directory), the Target URL which is the URL used to access this directory through the web, and the Maximum File Size you authorize for files' upload. To use File Uploads, you must use this form definition in your HTML form template: <form method="post" action="_CONTEXT_" ENCTYPE="multipart/form-data"> You must name the file fields file_xxx (file_word_resume for example) and use this field in your form: <input type="file" name="file_xxx" value="_file_xxx"> Ex: <input type="file" name="file_word_resume" value="_file_word_resume"> Note: The File Upload directory must be 666 and allow http readable access
AUDIT Options	You can keep track of every modifications made to your databases. Ex: A certain user delete a record by mistake. As administrator, you can backup this record and rollback the deletion. THIS FUNCTION IS ONLY ACCESSIBLE BY ADMINISTRATOR. - If you want to track the changes made, set check the Enable Log box. This will keep a track of every action taken on the database and write a log file (database_name.log) under the ./log_files directory: you should make sure it exists and is writable - We have then 4 options to define which actions we want to trace: Add: If you want to archive every addition to the database. Delete: If you want to archive every deletion made in the database. Rollback: If you want to archive every rollback made to the database. Modify: If you want to archive every modification made to the database.
HTML Templates	WARNING: The syntax has changed with the version 3.0. EZDB now uses a single template file containing the %%menu%% and %%content%% markers. You can use you own HTML template to customize the look of EZDB. The file is defined for each (context,phase) pair. Syntax: context--phase--template_path The Template file MUST contain the %%menu%% (replaced by the menu bar) and %%content%% marker (replaced by the EZDB output) By default the template used is the default_html_template defined as a global variable. Ex: add----./my_html/product_template_for_add.html This will display the product_header_for_add.html and product_footer_for_add.html for the add context and any phase. --process--./my_html/product_templte_for_process.html This will display headers and footers for every context during the processing phase. Note 1: You can use a template for Login, Authorize and Connected phases: It will only work if the table name is specified in the url. In this case, the phase specified MUST be : Ex: login----./my_html/product_template_for_login.html connected----./my_html/product_header_for_connect.html authorize----./my_html/product_header_for_connect.html Note 2: Within the templates, the special markers _CONTEXT_, _LOGIN_ and _SESSION_ will respectively be replaced by the context, the user’s login and session id.
Email notifications	The mail notifications are a list of values SEPARATED BY CARRIAGE RETURN. Syntax: ((condition)+)->((email_address),)->((Alias:fied_name)+)->Subject The condition can be: * (Always TRUE) OR (field_name=string)+ OR (field_name!=string)+ For the condition, the field_name can be replaced by: _LOGIN_ this will evaluate the name of the user login _GROUP_ this will evaluate the name of the user group Ex: company_name=ABCD+dpt=Accounting->jdooe@here.com->Company Name:company_name+Reference No:ref _GROUP_=manager->webmaster@dob.com->Manager Name:name+Problem description:pb_desc _LOGIN_!=default->me@here.net->Date:date+Email address:email *->me@here.net->Date:date+Email address:email->Something happened on the Job database
MAIL TEMPLATES	You can also use mail templates: Just write a regular mail text and save it under mail_templates. In order to send this text as mail notification, you just have to use this Syntax: ((condition)+)->((email_address),)->(Template:filename) The Mail Template file MUST be under ./mail_templates (check that the directory exist and is readable). Ex: ->me@here.net->(Template:add_invoice.txt) To make it fancier, you can use special caracters in your template so that it will be parsed and populated with database fields: Syntax: %_field_name_%* Ex: In our invoice_add.txt template, we use: Dear %_contact_%, Your invoice # %_ref_% has been received and will soon be proceeded. Thanks for shopping at EzStore. The Manager. This produces a very nice result.

Database name	The table name!
User Group	The user group!
Permission	Authorized actions for that group on this database
Menu	Visible menu options for that group on this database
HTML Display	HTML display file for that group on this database. (By default, the files specified in the "tables" database are used)
HTML Form	HTML form file for that group on this database (By default, the files specified in the "tables" database are used)
HTML Template	HTML Template file used to access the database for this group. By default, the files specified in the "tables" database is used. (The syntax is similar to the one used for the table definition.)
Display Mode	Display mode for that group on this database
Access Restrictions	Defines restrictions depending on the value of certain fields: will block certain records from being accessed depending on the specified conditions. Syntax: ((context:(field_name=string)+);) String can be _LOGIN_ or _GROUP_ Ex: 1) manager_group=_GROUP_+company=ABCD 2) owner=_LOGIN_ 3) group_owner=_GROUP_ 4) modify:name=_LOGIN_;search:paid=yes : When modifying, only show the record belonging to the user who’s logged. When searching, displays only records for users that have paid Important Note: The combination of ownership fields (owner, group_owner, ~owner, ~group_owner) and of _LOGIN_ and _GROUP_ parameters is very powerful. This allows to restrict access to self created records, or to group owned records.
Direct Full Display	Display mode when retrieving one (1) match for a query, for that group on this database
Authorized Fields Restriction	Defines which fields are allowed to be submitted (leave blank otherwise). Block users from submitting unwanted field values. Syntax: field1--field2--...
Default Fields Values	Defines default values for specified fields. Syntax: field1=value1--field2=value2--...
Display Line HTML	Line Display file path for that group on this database
Group allowed to use EzTree Assignment	Set this parameter to Yes to allow users to assign database records to the EzTree structure.