ReadMe File for the BizDB Product Quotation Generator Facility ############################################################################# # # # Product Quotation Generator - An Add On Facility of BizDB Database S/W # # # ############################################################################# # # E-mail: cnctek@cnctek.com # # MINIMUM SERVER REQUIREMENTS: # # Runs on any Unix, Linux or Windows NT Operating System; # Provides full FTP access (or access via a Control Panel); # Supports Perl and cgi-bin; Allows creation of files and # directories by cgi programs; Needs BizDB Advance already installed. # # # COPYRIGHT NOTICE # All BizDB products are products of CNC Technology. All rights reserved. # Only the user with our permission can use and modify this software. # Also permission is granted to execute this software on one domain name # only. Without CNC Technology's permission, no part of this script can be # reproduced ( other than the backup copy ), resold or redistributed to # any other individuals, companies and organizations. # # DISCLAIMER: # # All software and templates are provided on a "As Is" basis. CNC # Technology will not be liable ( nor responsible ) whatsoever for # any direct or indirect damages caused by the use of this Software # ( or Scripts ). # ################################################################## Please read the following paragraphs carefully. This is essential if you want to have a smooth and successful installation. IMPORTANT NOTE: This Web based "Product Quotation Generator" software is an add on facility of our BizDB Database Software. Before installing and using this software, you must have either "BizDB Starter" or "BizDB Standard" or "BizDB Advance" database system installed on your server. Through your BizDB installation, you have demonstrated that you are able to add, update, delete, search and display BizDB database records. You should have no problem to define BizDB database fields and the associated Html templates. (You can test and order our BizDB software directly from our Web site located at http://www.cnctek.com/bizdb-html/ . Thank you.) ################################################################## TABLE OF CONTENTS: A. Contents in our ZIP file B. System Configuration Parameters C. How the "Product Quotation Generator" System Works D. How to build the "Quotation Request" Report Template E. How to build the "Review Basket" Html Template F. How to build the "Quotation Report Template" for the e-mail G. Installation Notes ################################################################## A. Contents in our ZIP file After decompressing the ZIP file by WinZIP/Win 95/98/2000, you should find the following files: (1) quotation-search.cgi - CGI script used for Searching and (program) displaying multiple database records at one time. This is an enhanced version of the BizDB Advance bizdb-search.cgi script with capacity to support the new online quotation facility. NOTE: "quotation-search.cgi" can be used to replace the "bizdb-search.cgi" script. You can either use "quotation-search.cgi" or "bizdb-search.cgi" for general search purposes. However you must use "quotation-search.cgi" to generate "quotation" e-mail for the selected products. (2) quotation-add - The sample Add DB record Html template. (template) All database fields are defined and referenced here. (See BizDB readme.txt) (3) quotation-edit - The sample Edit/Delete/Show DB record (template) Html template. You will use this template to retrieve and edit/delete a specific DB record ( based on record key ). (See BizDB readme.txt) (4) quotation-delete - The sample Delete DB records (Batch) Html (template) template. You will use this template to delete multiple database records by matching their creation dates against the date range specified by the Webmaster. (See BizDB readme.txt) (5) quotation-search - The sample Search DB records Html (template) template. You will use this template to specify search criteria ( keywords ) for the quotation-search.cgi program. (See BizDB readme.txt) (6) quotation-report - The sample "Display DB Records" Html (template) template. You will use this template to define which and how DB fields are to be displayed in the search report. Fields belonging to the same record will be displayed in a group. This will be repeated for each record until all records are displayed. (7) quotation_review_basket (template) - The sample "Review Records in Basket" Html template. You will use this template to define which and how DB fields are to be displayed in the "Review Basket" report. Fields belonging to the same record will be displayed in a group. This will be repeated for each record until all records are displayed. (8)email_report.tmpl - This template defines which and how DB (template) fields are to be displayed in the quotation report which will be sent by email to the requestor. Fields belonging to the same record will be displayed in a group. This will be repeated for each record until all records are displayed. (9) quotation-index.html - The sample home page for calling various quotation database functions, such as Add, Edit, Delete and Search. You can use this home page to test your database. **NOTE** You must have BizDB installed to support the Add, Edit, Delete and Search functions. Use this add on feature only if you want to send the Selected Records within the Search Result to the user's E-mail Address. (10) quotation-readme.txt - It's this document. (11) quotation-db - Sample Quotation (Product Details) database file. The format of this file is a standard BizDB database file. You can use a different name for this file if you like. Please reflect the correct name in the "dbname" FORM statement in your various BizDB templates. (See BizDB readme.txt) (12) log-db - Quotation Request Log file. This is a log file containing all the information about the quotation receiver and the database records transmitted. This file has the same format as the standard BizDB database file (see BizDB readme.txt). You can install a separate copy of BizDB system to search, view and update the contents of this file. This file must be stored in the same directory as the BizDB database files. (13) log_rec_nr_file.txt - Quotation Log Record Number Allocation File - This file must be stored in the same directory as the BizDB database files. If you have used our development assistance, we will include more files to meet your specific needs. This will be mentioned in a separate document or e-mails. B. System Configuration Parameters: Please make sure you have the following parameters in the new quotation-search.cgi program properly configured before uploading it to the CGI-BIN directory. NOTE: You should use bizdb-aed.cgi, bizdb_upload.cgi and quotation-search.cgi to set up your Product Quotation Generator database. Both bizdb-search.cgi and quotation-search.cgi are search engine programs, but only quotation-search.cgi is designed for the Product Quotation Generator database. Parameter Name Where Description (1) $maxfields quotation-search.cgi Maximum number of DB Fields. (2) $maxdisplay quotation-search.cgi Maximum number of records to be extracted in each search. (3) $maxdispscreen quotation-search.cgi Max Records to be displayed per screen. (4) $database_dir quotation-search.cgi Full pathname of the directory in which your database is stored. If possible, location of your database file should be stored outside the Html directories. (5) $template_dir quotation-search.cgi Full pathname of directory in which all Html templates are stored. (6) $upload_dir quotation-search.cgi Full pathname of directory where the uploaded (image) file will be stored. (7) $return_url quotation-search.cgi Return URL link used by OK and error messages. (8) @valid quotation-search.cgi These are the urls (separated by comma) that are allowed to execute this database system. This prevents any of our programs to be accessed by unauthorized Websites. (9) $this_cgi_url quotation-search.cgi Url of the CGI script you are working on. Include http:// (10) $sorttype_default quotation-search.cgi Define the sequence of sorting if "sortfield" exists. Default setting is "alpha-ascend", i.e. sort alphabets in ascending sequence. ################################################ * * * Parameters (11,12) are to be used together * * * (11) $days_for_new_entries If the record was just quotation-search.cgi submitted in the last so many days, the new.gif or new.jpg will be displayed. (12) new_image quotation-search.cgi Url of new.gif or new.jpg This image is used to indicate the record is a new one. ############################################# * * * Parameters (13,14,15) are to be used together * * * (13) $rotate_db_records Set this parameter to "yes" quotation-search.cgi if you want to rotate the database records at the change of a day when the database is searched. The program will ensure that this is done once a day. Otherwise set it to "". (14) $rotation_count quotation-search.cgi This defines how many records are to be rotated to the top of the database file each time. (15) $last_rotated_date_file This is the file containing quotation-search.cgi the date of last rotation. ############################################# (16) @inhtml_array quotation-search.cgi Webmasters can allocate 1 or more database fields to point to system files containing fixed Html codes which can be used for advertising purpose. Normally these database fields are defined as hidden fields in the ADD, EDIT and/or ACTIVATE templates, therefore their contents are not updatable by general users. For details of the use of this feature, please read Section J. ############################################# * * * Parameters (17,18,19,20,21) are used by this * * * * * * "Product Quotation Generator" ADD ON Facility * * * ############################################# * * * Parameters (17,18) are to be used together * * * These parameters are used for generating "Quotation E-mails". (17) $mailprog quotation-search.cgi Location of "sendmail" program. You need "sendmail" to send "Quotation E-mail" to the user if the "send_report_option" input form field exists in your "Search Report" Html template. Check with your ISP. (18) $webmaster quotation-search.cgi Webmaster email return address. This will appear in the "From" line of all "Quotation emails". ############################################# * * * Parameters (19,20,21) are to be used together * * * These parameters are also used for building the "Quotation Request Log" file. The format of the log file is identical to that if a BizDB database. All fields in the record are delimited by the character(s) defined by the parameter $delimitor. (19) $delimitor quotation-search.cgi Field delimitor. The setting here must be identical to that used in the bizdb-aed.cgi script. ** NOTE: If you set $delimitor to "\t" (tab), all the tab characters that exist in the database will be converted and stored as "_TAB_". If you set $delimitor to "," (comma), all the comma characters that exist in the database will be converted and stored as "_COMMA_". If you set $delimitor to " _ " (space+underscore+space), all the "_" characters that exist in the database will be converted and stored as "_UNSC_". You will need to convert them back to "tab", "comma" or "_" after downloading and importing to your local database software. (20) $uid_pwd_sep quotation-search.cgi Used in field-1 (f1) for separating the UserID(RecordID) from the password. The setting here must be identical to that used in the bizdb-aed.cgi script. (21) $superpwd quotation-search.cgi Supervisor Password. This will be used as the password for all "Quotation Request" Log records. ############################################# (22) $charset quotation-search.cgi Define the character set to be used by your database software and Html templates. This is required for some foreign languages. (See BizDB readme.txt) C. How the "Product Quotation Generator" System Works: The "Product Quotation Generator" system works as follows: (1) User displays the "Add Quotation Record" screen ( sample template fielname = quotation-add ) to add a new quotation record. This is a standard BizDB database function (see BizDB readme.txt). (2) User displays the "Edit Quotation Record" screen ( sample template filename = quotation-edit ) to start editing an existing record. Before Editing or Deleting a record, the user must display the content of an existing Record ID first using the "Show Record" function. This is a standard BizDB database function (see BizDB readme.txt). (3) User displays the "Search Quotation Records" screen ( sample template filename = quotation-search ) to start searching the Quotation Database. The user may use either the Quick Search or Complex Search method to search the database. This is a standard BizDB database function (see BizDB readme.txt). (4) If there are records matching the user's request, a report ( defined by the sample template with filename = quotation-report ) containing the key information of each record will be displayed on the screen. Also on the report are a number of fields available for the user to complete when he is ready to raise a "Product Quotation By E-mail" request. Some of the important fields are "E-mail address", "Contact Person, "Subject" and the "Check to Request" checkbox next to each record displayed. (5) By checking the checkboxes on the left of the search result, the user may select as many records as he like for inclusion into the "Quotation" e-mail. If one search is not enough, the user may carry out multiple searches. All record selected by the user will be saved in a cookie basket for later use until the basket is cleared or the browser is restarted. The user may also click the "Review Basket" button to review the records he has selected so far. If necessary, he can remove some of them by clicking the "Remove Item" link displayed next to each item. (6) When the system receives the "Product Quotation By E-mail" request, it will search the database again and generate an e-mail containing all the information of the quotation records requested by the user. The format of the quotation e-mail is defined by a template whose name ( sample template filename = email_report.tmpl ) is specified in the "Quotation Request" report template ( sample template filename = quotation-report ). (7) If the "Log Quotation Records Emailed" switch is turned on ( this is a hidden FORM field defined in the template of the "Quotation Request" report - quotation-report ), the system will also write the content of each record emailed, along with the user/requestor's contact information and a subject line to a "Quotation Request Log" file ( log-db, defined by the hidden FORM field "logdbname" in the "quotation-report" template file ) for further analysis. D. How to build the "Quotation Request" Report Template: Our sample template filename is "quotation-report". The structure of the template is as follows: ......... ...... ......
...... ...... ...... ......
...... ......
Check All -- Clear All
...... ......
...... ......
......
...... ......
...... (1) JavaScripts: You must copy the whole block of this Javascript to the header section (between and ) of your search report template without any modifications. (2)
Your E-mail: Contact Person: Subject:
This form defines how the "E-mail Quotation Report" is generated. You must have the name="quoteform" defined in the
statement. You must also have the parameter "key_list" defined as empty (""). If the parameter "send_report_option" is set equal to "by email", you must include the following INPUT statements in your "quoteform" form: Your E-mail: Contact Person: Subject: Our "quotation-search.cgi" program will use this formation to generate the "Quotation" e-mail. For definitions of other parameters, please refer to descriptions below. (3) This form statement must be defined once within the and statements. Everything defined in this FORM statement must not be changed. It is also important to know that the pair of ...
statements must be inserted just outside the ...
which is used to contain the .... block. Now if the checkboxes in this FORM is checked by the visitor, the "add" JavaScript function will be activated. It will extract the corresponding Record ID (record key) defined in this form and add it to the cookie basket for later use (The cookie basket will be used by the "sendQuoteRequest" JavaScript function when the "Send Quotation Request" button is clicked). (4)
Check All -- Clear All
The above optional statements can be inserted just before or after the record display table. If used, they will allow your user to set or clear all checkoxes on the current page at one goal. ***************************************
......
The "Review Basket", "Send Quotation Request" and "Clear Basket" forms must be inserted without change after the following Html statements:
...... ...... ......
If the "Send Quotation Request" button is clicked, the "sendQuoteRequest" JavaScript function will be activated. The value of the "key_list" parameter (defined in the "quoteform" FORM) will be constructed based on the content stored in the cookie basket. The content of the "quoteform" will then be forwarded to the "quotation-search.cgi" program for the generation of the "email quotation report". If the "Clear Basket" button is clicked, the "resetBasket" JavaScript function will be activated. The content of the cookie basket as well as all the checkboxes on the current page will be cleared. * * * * * * * * * * * * * * * * * * * * * * * * * The report defined by this template serves two purposes. * * * * * * * * * * * * * * * * * * * * * * * * * (1) Firstly it defines the exact content and layout of the search report to be displayed on the screen. Example: In the following Html codes, **key**, **f6**, **f7**, **f8**, **f9**, **f11** tell the system that only the record key and the content of field # 6, 7, 8, 9 and 11 of each of the selected records are to be displayed on the specified page position. **f6**   **f7**   **f8**   **f9**   **f11**   * * * * * * * * * * * * * * * * * * * * * * * * * (2) Secondly it acts as an interface for the visitor to tell the system what database records are to be retrieved and how the quotation report is generated and transmitted to the email address specified by the visitor. Example: The following codes tell the "quotation-search.cgi" program to search the "quotation-db" database file, generate the quotation report based on the format defined by "email_report.tmpl", log all "quotation report records" to a log file called "log-db" containing the user input fields "contact", "email" and "subject" as well as all the fields in the quotation records. The user fields "contact", "email" and "subject" are to be stored in field number 21, 22 and 23 of the Log database file respectively. This is defined by the hidden FORM fields "svto_contact", "svto_email", and "svto_subject". You can change these field numbers to other values as far as they are not overlapping with the field numbers in the quotation records. In our example, the quotation record has 11 fields, therefore f21, f22 and f23 can be freely used for other purposes.
--> This statement is to call the new version of quotation-search.cgi which can support the "Product Quotation Generator" feature. --> Your must include this ' name="quoteform" ' clause into this statement. This form will be used by the JavaScript on the same template. --> This dbname statement defines the name of the quotation database to be searched. --> This are standard BizDB command statements. See BizDB readme.txt --> This template statement defines the content and layout of the email (quotation) report to be generated. --> This template statement defines the content and layout of the "Review Basket" report to be generated. --> This logdbname statement defines the filename of the Quotation Log database file to be used. --> This statement is to turn on the "Product Quotation By E-mail" facility. --> This statement is to turn on the "Log Quotation Records Emailed" facility. --> This svto_xxxx statement tells the system to save the content of the FORM field xxxx to field 21 of the Quotation LOG record. Used only if "log_records_emailed" is set equal to "yes". --> This svto_xxxx statement tells the system to save the content of the FORM field xxxx to field 22 of the Quotation LOG record. Used only if "log_records_emailed" is set equal to "yes". --> This svto_xxxx statement tells the system to save the content of the FORM field xxxx to field 23 of the Quotation LOG record. Used only if "log_records_emailed" is set equal to "yes". --> This statement must exist in the "quoteform" FORM and must not be modified. The value of the "key_list" will be evaluated by the supplied "add" JavaScript. : : : --> User input field. This is the field referred by the "svto_email" FORM statement. : : : --> User input field. This is the field referred by the "svto_contact" FORM statement. : : : --> User input field. This is the field referred by the "svto_subject" FORM statement. : : : Please pay special attention to the Checkbox FORM statement: This must be inserted between the and tags. >>> It is also important to know that the pair of >>> ...
must be inserted just outside the ...
>>> used to contain the .... block. On the search report displayed on the screen, if the Record ID of the record to be displayed is "123", this form statement will be displayed as: This INPUT form statement will be generated repeatly for each record displayed on the screen. If this checkbox on the screen is checked by the visitor, the system will know that the report in the "Quotation E-mail" must contain the relevant information stored in record "123". E. How to build the "Review Basket" Html Template: Our sample template filename is "quotation_review_basket". The structure of the template is as follows: ......... ......
......
..... ...... ...... ...... ...... ......
... **remove** ...
...... ......
......
...... (1) JavaScripts: You must copy the whole block of this Javascript to the header section (between and ) of your search report template without any modifications. (2) The "quoteform" used by the "Review Basket" template must be identical to that used by the "Quotation Request" Report Template (see Section D above).
This form defines how the "E-mail Quotation Report" is generated. You must have the name="quoteform" defined in the
statement. You must also have the parameter "key_list" defined as empty (""). If the parameter "send_report_option" is set equal to "by email", you must include the following statements in your "quoteform" form: Our "quotation-search.cgi" program will replace the **email** tag, the **contact** tag and the **subject** tag by the values input by the user. (3) In the table that controls the display of database fields, you should remove the "CHK" column which contains the following FORM statement: (See "Quotation Report" template on Section D above) Instead, a new "Remove Item" column should be introduced at the last column of the table containing the .. **remove** .. statement. Example - See our sample "quotation_review_basket" Html template: **f6**   **f7**   **f8**   **f9**   **f11**   **remove**   When the "quotation-search.cgi" program receives a "Review Basket" request, it will replace the **remove** tag by a "Remove Basket Item" URL link. When the user clicks on this link which is displayed on the Web browser, the associated "Record" will be removed from the Basket. NOTE: The and
statements which exists in the "Quotation Request" Report template (see Section D above) do not exist anymore in this "Review Basket" template. (4)
......
The "Review Basket", "Send Quotation Request" and "Clear Basket" forms must be inserted without change after the following template statements: ...... ...... ......
F. How to build the "Quotation Report Template" for the e-mail: Sample template filename is "email_report.tmpl". Example: The sample "email_report.tmpl" template contains the following codes. They are plain ASCTT text without Html codes. Like BizDB, we still use and to instruct the software to display record fields repeatedly in that order. In the following example, the content of field # f6, f7, f8, f9 and f11 are displayed first, then followed by another record, and so on. If you want to leave some spacing, just insert somes space characters or space lines. NOTE: The software will replace **matchcnt** by the total number of records to be displayed in the email. This tag must be placed outside the / block. All **fxx**, **key** (record id) and **pwd** (record pwd) must be placed within the / block. QUOTATION REPORT REQUESTED ========================== Number of Products: **matchcnt** ---------------------------------------------------------------------- Product Code: **f6** Product Name: **f7** Descriptions: **f8** Unit Price : **f9** Minimum Q'ty: **f11** *** END OF REPORT *** G. Installation Notes: 1. Configure and copy quotation-search.cgi to the cgi-bin directory. Make sure the file access modes of this script is set to 0755 ( Unix command to set modes: chmod 0755 quotation-search.cgi ) Please refer to Section B. 2. Configure and copy all template files to the template directory defined by $template_dir in quotation-search.cgi. 3. If you want to log the content of each "Quotation" e-mail sent, copy the initialized "log_rec_nr_file.txt" file to the database directory defined by $database_dir in quotation-search.cgi. Set the file access modes of this file to 0777. ( chmod 0777 log_rec_nr_file.txt ) 4. Initialize your database files and start testings. Make sure the "add", "edit", "search", "report", "image upload", and "e-mailing" functions are fully tested before releasing the system to production. -------------------------------------------------------------------------- Now you are ready to run your "Product Quotation Generator System". Good Luck! Best regards, Webmaster CNC Technology Web Site Design, Hosting and Marketing Services