# # NeonBase Small Database Script README File # README or Readme # # =Written By=============|=Version====|=Date========|=Comments===============================| # ------------------------|------------|-------------|----------------------------------------| # Grant Mongardi | 1.00 | 02-11-2000 | Created | # | | | | # | | | | # ============================================================================================| # # This file contains information about the NeonBase Database System. The program itself has been tested on Windows NT using the /cgi-bin/ model, and Apache on Solaris and DEC Unix (True64). It was written to Perl 5.0, and probably won't work on anything lower, as it uses referenced hashes, and several other 5.0 features. WARNING! THIS SCRIPT IS NOT INTENDED TO BE TRULY SECURE!!!! If you need a database with true security, then you should contract NeonEdge Design to create one for you. We also offer the NeonBase Pro Licensed Version, which offers numerous security features that are not available in the demonstration version, however neither script is intended to be used for applications where it would store sensitive information. Perl just does not offer that level of security on it's own. NeonEdge Design can create Web-based or other applications for you and your organization that will offer you the level of security that you need for your sensitive data. History: ============================================================================================= 02-04-2000 - Grant Mongardi I created this program from scratch. I was finding that I was writing a lot of custom mini-database programs for things like seminar calendars, phone lists, equipment records maintenance tasks, and various other specialty items. After writing the first one, I found myself having to re-write the script to configure it for every instance. I decided that there must be a better way, and that's when I wrote NeonBase. Configuration: ============================================================================================ The Files: neonbase.pl - the database script itself. This file contains all of the display functionality for NeonBase. You should never have to make any changes to this file. neonadmin.pl - the administrative script itself. This file contains all of the various add, modify, and delete functionality. You should never have to make any changes to this file. neonbase.cfg - the default configuration file for the script itself. neonbase.fld - the default field specification file. book.log - the default database file debug.txt - where some raw data is written for troubleshooting purposes. AddEntry.html - the default template file for Data entry forms. header.xhtml - the default template file for the HTML page header. footer.xhtml - the default template file for the HTML page footer. data.xhtml - the default template file for displaying each data item. modify.xtemp - the default template file for modifying existing entries. README - This file. Prerequisites: To configure NeonBase correctly, you will need a text editor (like EditPad, Vi, or BBedit), a webserver, Perl, and a place on the webserver to put the scripts. THE TEXT EDITOR MUST SAVE TO UNIX FORMAT TO USE IT UNDER UNIX! To effectively use NeonBase, a general understanding of Databases, and the ability to follow direction is very important. You will also need a good understanding of HTML if you want to customize the pages as well. You will need to know how to change permissions on the server where the script will run. If you intend to edit the script directly, you should very likely have an extensive understanding of Perl 5.0. NeonBase is a fairly complex script (over 780 lines of code), and should only be edited by an experienced Perl programmer. Setup: To setup NeonBase for your particular application, you may need to edit the configuraton files, as well as the templates used in diplaying and editing the database. The following takes you through the process step-bystep, file-by-file. NOTE: When editing the setup files any lines starting with an exclaimation point (!) are considered configuration directives. No other lines should start with (!), as they may cause problems running the script. For safety's sake, any comments that you add to the setup files should begin with the pound sign (#). 1.> Uncompress the files to the directory in which you want to keep the database. If you are only allowed to run from cgi-bin, you should put the neon*.pl files in the /cgi-bin/ directory, along with the neonbase.cfg file. the other files can go anywhere. IF YOU ARE UPLOADING TO A SERVER USING FTP, THE TRANSFER MUST TAKE PLACE IN 'ASCII' MODE (See your FTP client documentation or Help files). If you don't use 'ASCII' mode, you will get a '500 Server Error - Premature end of script headers'. If you have to locate the neonbase.cfg file outside of the cgi-bin directory, then you will need to change the "neoncfg=" line in the two *.pl files to reflect the full path where the configuration file is located (i.e., "/home/users/my_home/www/neonbase.cfg"). 2.> You can now change the permissions for the neon*.pl files to "rwxr-xr-x" or 755. This can be done in two ways. One, you could telnet to the machine on which the script is located, cd to the directory in which the file is stored, and type "chmod 755 ". If you can't do that, you can try to use an FTP client such as wsFTP to connect to the server, select the file you want to change permissions on, and set the permissions to the values specified above (see the FTP client documentation or Help file for how this is done). I must warn you, however, some servers do not recognize 'chmod' as a valid FTP command, and therefore will not let you change permissions using an FTP client. 3.> Using the instructions in item 2, you need to change the permissions for the book.log file to "rwxrw-rw-" or 766, as well as the debug.txt file. The rest of the files should be set to "rwxr--r--" or 744. 4.> Now that all of the files have the proper permissions (if you have any wrong, you'll get an error), you can start editing the configuration files. The first file to edit is neonbase.cfg. This file tells the script where all of the resources it needs are. The fields are as follows: !VERSION - This field tells the script what version is running - DO NOT CHANGE! !NOAUTH - This is used to tell the script whether or not to use Password- controlled administration. ON SOME SYSTEMS, CRYPT() IS NOT IMPLEMENTED, RESULTING IN SCRIPT FAILURE WHEN AUTHORIZING OR AN INABILITY TO LOGIN IN EVEN IF THE PASSWORD IS CORRECT. !LOCK - This is used to tell the script whether or not to use file locking when editing the database. It does not work on systems that do not implement the flock() function. !DEBUG - This field is useful for debugging a database. If set to anything other than '0' (zero) then the script will write various raw data to the debug.txt file. AFTER THE SYSTEM IS UP, BE SURE TO DELETE THIS FILE!!! IT WILL CONTAIN THE CLEAR-TEXT PASSWORD! ALSO, SET THE DEBUG VALUE TO '0' (zero). !BACKUP - This is set to a non-zero value to indicate that a compressed backup should be created of the DATAFILE any time an edit takes place. The backups are name based upon an index (i.e., "book.log.0.Z","book.log.1.Z", ...). !DELIM - This is the delimiter character. If you don't know what one is, then you should probably leave this field alone. !AUTOKEY - This field, when set to anything other than '0' (zero), will cause the script to associate a unique value with each database entry. This SHOULD BE SET TO ONE IF YOU THINK THAT THERE MAY BE MULTIPLE ENTRIES WITH THE SAME PRIMARY AND AUXILLIARY FIELDS. If you're not sure, you can still set it to '1' if you don't mind the fact that it will add around 15 characters to the length of each entry. If you set this to '0' (zero) and then have entries with the same Primary and Auxilliary fields, then only the last item entered will be displayed. !ADMIN - This is the administrative login and encrypted password. It cannot be edited by hand. The default is user "admin" with a password of "admin". !FIELDFILE - This field specifies the name and path of the field specification file. This can be left as-is if the entire system is installed in a single directory. If you have to move things around, or change the filenames, you'll need to enter the full path from root("/"). !DATAFILE - This field specifies the name and path of the database file, and has the same rules as FIELDFILE. !HEADTEMPLATE - This is the file that is printed to the client prior to processing the data that is to be displayed. It is not a complete HTML page. !FOOTTEMPLATE - This is the file that is printed to the client after processing and displaying the data entries. It is not a complete HTML page. !DATATEMPLATE - This is the file that is used to display each data item. It contains special tags that are replaced by the script with database information or values. !MODIFYTEMPLATE - This is the template that NeonBase uses to create the page that allows modification of existing database entries. It contains special tags that are replaced by the script with database information or values. If you modify this template, do not remove any of the comment tags (""), because it will cause NeonBase to perform incorrectly. !ENTRYTEMPLATE - This is the template used to create a form for entering the new data for the database. And that's it for the 'neonbase.cfg' file. 5.> The next file to edit is the 'neonbase.fld' file. This is the file that describes specifics about your database, as well as defines some variables as to how you would like NeonBase to display the data. This is a fairly complex configuration, so you should go over this section thoroughly, as well as reading the instructions in the file itself before beginning to edit it. The fields are as follows: !NUMFIELDS - This value reflects the number of fields that you will need for the data that will be stored in the database. Think about this for a while before you assign a number. You are much better off to have a field you never use, than to have to reset, reconfigure, and re-enter all the data you needed to add another field two months down the road. For instance, if you only ever plan on entering a First Name, a Last Name, and a Phone Number, then you would specify '3' in this field. !ITEM(#) - This defines each field of an entry (or each column) in the database. The number of !ITEMs must be no less than the value in the !NUMFIELDS setting (if !NUMFIELDS is equal to '3', then you will need to enter '!ITEM1', '!ITEM2', and '!ITEM3). Each !ITEM describes various parameters associated with the data in that field. The values are separated by commas, and each needs to be entered, even if the value is not to be used (i.e., Even if you don't need to enter values in some of the positions, you need the commas - 7 commas per). These are the order and purpose of each entry: !ITEM(#)= Field Name, (The name associated with the field) Field Type, (Text, Drop-down, textArea, Radio, Check) editbox width, (columns) editbox height,(rows) Wrap value, (none, soft, hard) Index Value, (order on form) ContentType, (*See Below) TypeData (Target for ContentType *) Valid Values for 'ContentType' are as follows: CLINK - A constant Link Value, wherby the data in the 'TypeData' field is a URL. DLINK - A variable Link Value, whereby the numeric value specified in 'TypeData' is a reference to the '!ITEM(#)' field that contains the URL. CEMAIL - A constant email address, wherby the data in the 'TypeData' field is the address. DEMAIL - A variable email address, whereby field 'TypeData' specifies the 'ITEM(#)' to use as the email address. CDATE - A constant date field. This causes NeonBase to fill in the field with the record creation date. UDATE - An updateable date field. This field is updated to the current date whenever the entry is modified AND the form contains a value for the fieldname that indicates that an update should be carried out. The 'TypeData' field is set equal to the 'true' value for the update field (i.e, 'yes' or 'true') OBJECT - An object Reference - Indicates that this field contains a reference to a user-created custom operation. This and the 'TypeData' field are generated automatically when you use the ObjectManager that comes with NeonBase Pro. TEXT - This value, or any other non-valid value indicates that the field contains simple text values. LEGACY DESCRIPTION OF 'ContentType' LEFT IN FOR CLARITY: One valid value for 'ContentType' is "CLINK", which means that the field is a link or HREF anchor field, and the 'TypeData' field specifies the location to which that anchor or link will point. Another is "DLINK", which means that the field is a link or HREF anchor field, and the 'TypeData' field contains the number of the field or !ITEM that will be the target of that link or anchor. Another valid value is "CEMAIL", which defines that field as an email link in which the TypeData field specifies the email address for that link. Again, there is also a "DEMAIL" field in which the TypeData field specifies the number of the field or !ITEM which contains the email address for the link. And Lastly, there is a "TEXT" value or any non valid value, which specifies that the field will display as text. If you enter more !ITEMs than specified in !NUMFIELDS, the additional ones are ignored. !MAXENTRIES - Maximum number of results to display per page. !SORTDESCENDING - Non-zero value specifies to reverse the sortorder. !SORT1FIELD - Specifies the primary field to sort by. !AUXFIELD - Specifies the auxilliary field to sort by. 6.> If you have installed the files in different directories from the NeonBase script, you will need to edit the variables '$debugFile' and '$neoncfg' in the NeonBase script file to reflect the new locations for those files. If you installed everything in one directory, then you can (and should) leave the script alone. You should avoid making any unnecessary changes to the script itself, as it can be very complex to troubleshoot. You can also call the script with the location of the configuration file in the URL by specifying a 'query string'. This is done by specifying the URL of the script, followed by a question mark (?), followed by the designator and file, like this: http://www.yourserver.com/neonbase.cgi?sourcecfg=/path/to/config.cfg DO NOT USE SPACES IN THE URL OR QUERY STRING! 7.> You will now need to edit the AddEntry.html file to reflect the layout of your new database. Also, you need to change the "FORM ACTION=" to reflect the location of the script if it is in a different directory. However you design the page, You must leave in the "hidden" fields, and each of the inputs must have a "VALUE=" exactly equal to the corresponding Field Name. For example, if !ITEM1 has a 'Field Name' value of "First Name", then in the AddEntry.html file there needs to be an INPUT field with a 'NAME="First Name"' within the tag. If you don't know what that means, then you need to know more about HTML Forms before continuing. 8.> Now you will need to edit the modify template. The default name for this file is "modify.xtemp", but you can name it anything that you want, provided that you change the configuration file to reflect the new name. Within the template file there are some special tags that are used to automatically fill-in the form with the existing field data for the entry being modified. The two tags are in the following format: a. DATAITEMNAME[n] - This is replaced by the script with field name for the 'nth' field of the particular entry. For example, if you wanted to create a text box that was to take a string for the field in the database designated by '!ITEM3' You would put the following string in the modify template file: This, when submitted, would then add whatever the user typed in this box into the field of that entry that is designated by 'ITEM3' in the Field configuration file. If that Item line looks like this: !ITEM3=Last Name,T,25,1,0,0,TEXT,n then if the user selected an item to be modified, the final HTML source displayed would look like this: a. DATAITEMVALUE[n] - This is replaced by the script with value for the 'nth' field of the particular entry. For example, if you wanted to automatically fill in the field in the example above, you would edit the line in the modify template like so: then if the user selected an item to be modified, the final HTML source displayed would look like this: whereas your last name would be what is actually in the database. 8.> All that is left now is to edit the data template file so that the design is whatever you want for your page. Again, this file contains the same special tags as the modify template file. You use these in the same way as the modify template to display the values within the HTML page. They are replace by the script in exactly the same way. 9.> If you think everything is done right, you can now delete the book.log file. 10.> Hopefully if everything went as planned, you should be able to start entering data into the database. THAT'S IT! # =END OF README=============================================================================|