/* LabStoRe Version: 1.6.3 Date: 6 September 2014 Copyright: Santosh Patnaik, MD, PhD License: GPL 3+ URL: www.bioinformatics.org/phplabware */ -------------------------------------------------------------------------------- 1. About 2. Requirements 3. Installation - clean, and upgrades 4. Customization and modules 5. User system and authentication 6. Maintenance 7. Release notes 8. Donate 9. Bugs and issues 10. Importing data from other database systems Also see help/help.htm -------------------------------------------------------------------------------- About LabStoRe or Laboratory Stocks and Records is a modular, web-based software to assist biomedical research laboratories in building and maintaining a database of stocks and records. See help/help.htm for its rationale. It is based on PHP and the MySQL database system. The database holds tables for items such as proteins (antibodies, enzymes, etc.), plasmids, chemical reagents, etc. A web-based interface is used to access (populate and modify) the database. LabStoRe has two components. The modules (proteins.php, cell-lines.php, etc., inside labstore/modules) are the pages most users will see. They are used to browse, search, delete, insert, edit, etc., the data, that uses forms. How these forms appear to the users is configured by the second component, the Interface Creator (labstore/interface_creator). The Interface Creator also has ability to let the user browse, search, delete, insert, edit, etc., the data. But its main purpose is to configure the forms. Access to this sub-site can be restricted using .htaccess files lest users change the configurations for worse. The files in the LabStoRe folder dictate the application logic and interface, but the real data, including information on how the form fields appear, are stored in the MySQL database. For each module, there is a table (e.g., 'proteins' for the Protein module) that stores the actual data, and another table (with a 'dadabik_' prefix; e.g., 'dadabik_proteins') that holds information, such as which options to present, about the forms that are used to insert or update an entry for that module. A corresponding .php file, e.g., 'proteins.php,' is used to generate the web pages for that module. -------------------------------------------------------------------------------- Installing LabStoRe requires 1. A web server such as the free Apache server software. Tested with versions 1.3 and 2.2. 2. The free MySQL database system on the server computer - version 4.1 or above is required. Tested with 4.1 and 5. 3. The free PHP webserver module or engine - version 4.3 or above is required. Tested with 4.3.4, 5.1 and 5.5. A plain text editor (not MS Word) or a good HTML/code editor such as BBEdit, Text Wrangler (free), JEdit (free - http://www.jedit.org/), etc., is needed to edit the PHP code for configuration or modification. -------------------------------------------------------------------------------- Clean installation 1. To install, move the folder named 'labstore' to an appropriate place inside the web server root folder. If you wish, you can rename this folder. The address to access the inventory system will depend on the name and the placing of this folder. E.g., if placed at the root level as 'labstore', the front page of the system can be accessed at http://your.website.com/labstore/index.php. 2. Next, set up an MySQL database. You may call it 'labstore'. Use the labstore.sql file to populate the database. Please look elsewhere for help with general MySQL database and user setup. The free, web-based application, phpMyAdmin (http://www.phpmyadmin.net), is a very useful utility for MySQL database administration. There are 'regular' applications too, such as Navicat (www.navicat.com - not free) and MySQL Query Browser (free; http://dev.mysql.com/downloads/query-browser/). 3. Open file labstore/config.php and change the settings as per suggestions in those files. Preferably, use an HTML code editor such as BBEdit, JEdit, FrontPage (in code view mode), etc., but lacking one, a good simple text editor to do so. The configuration parameters should be carefully set. 4. The labstore folder should have execute permission, and the labstore/interface_creator/uploads folder should have write permission as well. If the website fails, check this aspect. 5. With default LabStoRe settings, access to most of the site will be open to anyone. 6. To restrict access, for example to enable user account- or IP address-based restriction, alter the settings in config.php. See 'User system and authentication' below. Further restrictions can be set up through .htaccess files. A sample .htaccess file is inside labstore/ as 'htaccess.' To use, please change the parameters and rename it as .htaccess. (Of course, the web server should have been configured to allow the use of .htaccess files.). 7. Use an internet browser to browse to the administration page at http://your.website.com/labstore/admin.php to change the default administrator password, to add users, etc. The default administrator username is root and password is letizia. You should change them. 8. Then browse to the front page (http://your.website.com/labstore/index.php) to start adding entries under the various categories. 9. You will most likely need to change some options in the 'insert (add) / update (edit)' forms. E.g., the lab may have four different -80 degree refrigerators, and you may want to provide each of them as an option for the 'fridge' field of a form (that specifies where an item is stored). The Interface Creator makes this possible. These changes can be done through links provided on admin.php page or through interface_creator/admin.php. Go to http://yourwebsite.com/labstore/interface_creator/admin.php and choose the table you want to configure. Then, click on the link to the configuration page. There, each form field can be configured. In fact, each of the dadabik_ prefixed table (every data table has a specific dadabik_ table) stores precisely such configuration data. For screenshots, see http://stanxterm.aecom.yu.edu/secondary/stocks/help/screenshot.htm. 10. For debugging purposes, for both MySQL and PHP, turn on (or off) the appropriate parameters in config.php. -------------------------------------------------------------------------------- Upgrading The way you upgrade from previous versions depends on how much data you already have in the tables and how much customization has been done. Before upgrading, you should make a copy of the existing labstore folder as well as dump the existing labstore MySQL database. (Please check on the internet on how to do so if you are not familiar.). To upgrade, replace all old files/folders with new ones. Then, copy settings from the old config.php to the new config.php file, and put in settings for any new parameter introduced in the new config.php file. Replace the interface_creator/uploads folder with the old one The files in the labstore folder dictate the application logic and interface, but the real data, including information on how the form fields appear, are stored in the MySQL database. For each module, there is a table (e.g., 'proteins' for the Protein module) that stores the actual data, and another table (with a 'dadabik_' prefix; e.g., 'dadabik_proteins') that holds information, such as which options to present, about the forms that are used to insert or update an entry for that module. A corresponding .php file, e.g., 'proteins.php,' is used to generate the web pages for that module. Upgrading from version 1.5.2 or higher -------------------------------------- Replace all files and folders except interface_creator/uploads (and possibly config.php, though not doing so and instead editing the file to copy the settings put in the old_config.php is recommended) Upgrading from version 1.5.1 ---------------------------- These files that were modified may be replaced - interface_creator/admin.php and help/. Using phpMyAdmin, etc., please manually edit MySQL tables - cell-lines, chemicals, others, parts, plasmids, proteins, and records - so the 'ID_user' field is set to 'varchar(64) NOT NULL' instead of 'int(11) NOT NULL.' You can also use the labstore.1.5.2.upgrade.sql file. Upgrading from version 1.5 -------------------------- These files that were modified may be replaced - interface_creator/business_logic.php, header.php Upgrading from version 1.4.6 ---------------------------- These files were modified from those in version 1.4.6; so replace these - interface_creator/index.php, index_long.php, index_short.php, business_logic.php all files inside modules/ For config.php file, either replace and put back your settings ,or edit your current config.php by adding these at the very bottom (before '?>') - submit_buttons_ar["copy"] = "Insert a new entry like this"; normal_messages_ar["insert_record_copy"] = "Insert a new entry similar to another"; error_messages_ar["no_authorization_copy"] = "You don't have the authorization to copy this record."; Upgrading from version 1.4.5 ---------------------------- Replace these files with the ones that were modified in version 1.4.6 - interface_creator/common_start.php Upgrading from version 1.4.4 ---------------------------- Replace these files with the ones that were modified in version 1.4.5 - interface_creator/common_start.php, header.php Upgrading from version 1.4.3 ---------------------------- Replace these folders/files with the ones that were modified in version 1.4.4 - interface_creator/check_login.php, interface_creator/login.php, interface_creator/login_form.php, interface_creator/header_admin.php, interface_creator/ReadMe.txt, interface_creator/help.htm, interface_creator/business_logic.php (2 lines added), interface_creator/functions.php (1 line added), help/ and admin.php. Upgrading from version 1.3 -------------------------- Following are needed to implement the user-based LabStoRe (new feature in 1.4; see note below) - 1. Using phpMyAdmin, Navicat, etc., add a field named 'ID_user' (INT 11, NOT NULL) to each module table. *** optional, see below *** 2. Change 'id' field name to 'ID_user' for table 'users.' 3. Add field named 'md5_password' (VARCHAR 32, NOT NULL) to table 'users.' 4. Change parameters in config.php to reflect these changes. The following is needed to add the new tables for the new modules added in version 1.4 ('parts' for equipments and accessories, and 'others' for miscellanea such as books, software, etc.). This will also delete users_tab and users tables installed previously. Also, a new users table will be created with just one user account: login - root / password - letizia; administrator. If you do not want the new users table, i.e., if you have already added many users to current users table, you may edit upgrade.sql to remove the lines concerning the users table, and then do steps 2-4 above. 1. Load data in labstore.1.3.upgrade.sql (with command-line MySQL or through phpMyAdmin, etc.). You may then wish to browse to labstore/admin.php to assign passwords, etc. Upgrading from versions older than 1.3 -------------------------------------- Do the following and then carry out the steps in 'Upgrading from version 1.3' Edit all dadabik_ prefixed tables in the MySQL database. The idea is to add a new field to all those tables and to edit another field in all of them. New field to add: linked_fields_extra_mysql. Of type varchar(255), not null, utf-8_general_ci Field to edit: type_field. Put 'select_multiple_menu' and 'select_multiple_checkbox' in it. It should look like this: ENUM ('text','textarea','rich_editor','password','insert_date','update_date','date','select_single','select_multiple_menu','select_multiple_checkbox','generic_file','image_file','ID_user','unique_ID') -------------------------------------------------------------------------------- Customization ADDING A NEW MODULE The system comes with seven 'modules,' one each for proteins (enzymes, lectins, antibodies, etc.), chemicals (RNA, chemical reagents, etc.), plasmids, cell-lines and records (freezer box records, protocols, other documents, etc.), parts (for equipments and accessories) and others (for miscellanea). Each 'module' has a php page to display the database entries (labstore/proteins.php for proteins, and so on), and has a table (proteins for proteins) in the database. A second table (dadabik_proteins for proteins) enables customization of insert/edit forms. Some of the modules can be disabled by changing parameters in config.php. These steps describe how a new module may be added - 1. Create a new MySQL table - use an application like Navicat or the free web-based phpMyAdmin software (www.phpmyadmin.net). You may name it, for example, for seed strains, 'seeds.' The table should have a column named 'ID_user' for authentication (if you enable it in config.php) to work. This column stores values from the ID_user column of the users table. It also should have a column named 'name,' though it can store information for not just name but description too (for example). If you cannot, you will have to modify top_part.php (look for the code for the default sorting clause). 2. Then browse to yoursite.com/path/to/labstore/interface_creator/admin.php and install the table by clicking the right link (towards the bottom). 3. You can then configure the form for the table - use the link provided on the page (above). When configuring, for field 'ID_user,' make it not to be shown in the insert/update/search forms or results, and set it to field type 'ID_user' - authentication system for the table will fail otherwise. See the Interface Creator help section. 4. You will now have to create a .php file for the module. Use a code editor such as BBEdit or TextWrangler (free) or a plain text editor (such as TextEdit or NotePad, but not MS Word). You can use the code in, say, 'chemicals.php,' as a guide. When done, name it, say, for seed strains, 'seeds.php.' 5. Alter the parameters in config.php to have the module included. MODIFYING EXISTING MODULES You may modify existing modules. For example, you may want to add a new field (to the table, and thus to the web form). Adding or deleting MySQL table fields (or renaming them) has to be done through a separate application. Afterwards, you should go to labstore/interface_creator/admin.php to 'input' the changes into the system. If you created a new field, you will also want to configure the corresponding web form field. It is recommended that the fields 'id', 'name', 'added_by', 'modified_by', 'added_on' and 'modified_on' not be affected. You can change them but you will then have to change many lines of the PHP code too. You can also 'break' a module into two, by creating a new module (as described above) and moving some of the 'purpose' of the old module to the new one. E.g., the 'proteins' module can be broken into 'antibodies' and 'other proteins' modules. STYLE CHANGES The CSS style-sheets that are used are in labstore/style.css and you can edit them to suit your needs. HEADER AND FOOTER CUSTOMIZATION By changing parameters in labstore/config.php, much customization can be achieved. If you wish you can still edit labstore/header.php, labstore/footer.php, labstore/top_part.php, labstore/bottom_part.php, labstore/interface_creator/header.php, labstore/interface_creator/footer.php, labstore/interface_creator/header_admin.php, labstore/interface_creator/footer_admin.php -------------------------------------------------------------------------------- User system and authentication Besides the IP-address-based restrictions that may be set through config.php, and any .htaccess file based restrictions you set up, LabStoRe also has an integrated authentication system that may be enabled to various degrees by affecting parameters in config.php. While the IP-system is a 'restrictive' one, the user system is a 'permissive' one, meaning that the former if set will apply on top of the latter - a user with the right username and password will be rejected if visiting from the wrong IP address. The user system depends on the 'users' table (or a different table if defined so in config.php) that stores user identities (usernames), user-specific IDs (ID_user), encrypted passwords, user type (normal or administrator), etc. User authentication enabled to a not-maximal extent merely requires visitors to log in before they can insert entries, etc. With user authentication enabled to maximum extent, every new record that is created is assigned the username value, and a logged-in user's username value is matched against it to allow modification, deletion, etc. Setting $enable_admin_authentication to 1 will restrict access to the admin page, and to the interface_creator admin page, to administrators only as defined in the MySQL 'users' table. Setting $enable_authentication to 1 will require user login (both administrator and normal users) for inserting, modifying or deleting table entries. Note that this can also be accomplished through .htaccess files. Because members of a research group are usually in an open-to-each-other community, further restrictions may not be necessary and can cause inconvenience and extra work. It can also defeat a major purpose of maintaining an inventory system (stocks wasting over time, stocks of members who leave the lab may be 'lost,' etc.) With other authentication settings set to 0, a user can edit or delete other users' entries. With them set to 1, however, restrictions may be placed. For example, with $enable_browse_authorization set to 1, only the user who created the entry can view its details. He (even if an administrator) cannot view the details of entries created by other users or of entries that have empty ID_user values. It is easy to revert from a maximal authentication system to none but the other way may make some entries 'invisible.' Through admin.php, it is possible to easily reassign ID_user values so a user may inherit another user's entries. Currently, the only way to share entries is to share the same user name and password. -------------------------------------------------------------------------------- The components of the system are - 1. The MySQL database and its tables - see labstore/help folder for more on the MySQL structure. 2. The interface_creator (labstore/interface_creator/admin.php) can be used to modify the insert/edit forms that users see. 3. MySQL connection settings and various other, editable parameters are in labstore/config.php. 4. Main page is index.php. 5. Help and similar information is in labstore/help. 6. Export support is provided by export.php. 7. Tables are displayed using modules/proteins.php, etc. 8. Administration is through admin.php -------------------------------------------------------------------------------- Over some years as newer PHP and MySQL versions are released and installed on your system, some of the code may fail. But, with little PHP and MySQL expertise, one may readily fix any problem. -------------------------------------------------------------------------------- Release notes September 2014 - Version 1.6.3 released > Minor fixes > Compatibility with PHP setup that uses MySQLi instead of the legacy MySQL extension (deprecated since PHP 5.5) October 2013 - Version 1.6.2 released > Minor fixes February 2013 - Version 1.6.1 released > Fixed syntax errors in PHP files for the Chemicals and Plasmids modules (thanks to mgcurri@emory.edu) April 2012 - Version 1.6 released > Fixes SQL injection vulnerabilities and other minor issues November 2011 - Version 1.5.4 released > Fix for an SQL injection vulnerability February 2009 - Version 1.5.3 released > Minor bug-fixes July 2007 - Version 1.5.2 released > Fixed correct assignment of values (usernames) to ID_user fields June 2007 - Version 1.5.1 released > Fixed two select_single/new options bugs > Configuable popup window August 11, 2006 - Version 1.5 released > Ability to copy a record added > Style error in cell-lines module corrected > Parent window refresh issue corrected July 1, 2006 - Version 1.4.6 released >A login issue was fixed by adding session_start() to interface_creator/common_start.php; thanks to Clare Giacomantonio of University of Queensland, Australia. May 16, 2006 - Version 1.4.5 released >A 'headers already sent' issue noticed by Balaji Ramanathan, Yale University and also observed on a Windows XP/WAMP 1.6.2 setup was fixed by adding a single line of code - ob_start(); - in two files February 10, 2005 - Version 1.4.4 released >A login bug was fixed - thanks to Alexander Griekspoor, The Netherlands Cancer Institute and Eric Tan, Agency for Science, Technology and Research, Singapore >Proper UTF-8 support by using 'SET NAMES 'utf8'' in function 'select_db' December 25, 2005 - Version 1.4.3 released >Uniformed all line-breaks to Unix-style >Uniformed all file encodings to UTF-8, no BOM December 22, 2005 - Version 1.4.2 released >Fixed bug in a function used to check if logged-in user was a record owner - thanks to Jean-Francois Lucier of University of Sherbrooke, Canada >Fixed bug that prevented Excel/CSV export - thanks to Stanislav Khoruzhenko, Johns Hopkins U., USA December 17, 2005 - Version 1.4.1 released > Fixed bug in password encrypter file > Fixed bug with multiple selection when a record being inserted was marked as possible duplicate but was still inserted by user October 23, 2005 - Version 1.4 released > Two new modules added - parts and others > Ability to remove modules > User system > Enhanced Interface Creator subpart August 20, 2005 - Version 1.3 released > Extra form configuring capabilities > More easily customizable > Some important Interface Creator bugs fixed > Restructured files August 12, 2005 - Version 1.2 released > Interface creator modified > XHTML 1.0 Strict compatibility expanded to the Interface Creator folder July 9, 2005 - Version 1.1 released > Better sorting and searching > XHTML 1.0 Strict compatibility May 25, 2005 - Version 1.0.2 released > Better sorting and searching May 12, 2005 - Version 1.0.1 released > Lab title and url now specified as variables (in header.php and in interface_creator/config.php and config_short.php) > Sanitized Updated date and Added date display (not seen if value is 0000-00-00 or empty) April 27, 2005 - Version 1.0 released -------------------------------------------------------------------------------- Donate If you would like to donate to appreciate and support this software (I have so far spent over 150 hours developing and testing LabStoRe), please use PayPal (www.paypal.com - works in over 50 countries) to send a payment to drpatnaik AT yahoo DOT com -------------------------------------------------------------------------------- Bugs and issues I apologize for any bugs in the code. Most of the issues are likely to be platform (OS) / browser / MySQL / PHP / webserver-related, and not because of problems with the LabStoRe scripts. IE on Mac will not lay out the pages properly. Old versions of IE, on PC, may also not lay out the pages properly. Improper settings in config.php (check for missing slashes (/), commas (,), quotes ('), etc.) and improper or incompatible configuration of form fields (through labstore/interface_creator) may also give rise to issues. For debugging, enable the right options in config.php. The error messages may help you troubleshoot the problem. For example, it could be because of your PHP settings and not because of the application logic. The Interface Creator that is an integral part of LabStoRe is derived from DaDaBik (www.dadabik.org), and the forums on that website may help you troubleshoot. Newer, better versions may be released at http://www.bioinformatics.org/phplabware where you may also find further support. -------------------------------------------------------------------------------- Importing data from other database systems You may wish to import data from a different (than MySQL, or a MySQL system with a different table structure) storage system. To do so, 1. Note the structure of tables in LabStoRe and in the other system 2. Modify OrderSys (MySQL tables, forms, etc.) - see Customization above, and/or your current storage system (getting rid of unnecessary fields, merging fields, etc.). 3. After you have matched the two structures, export data from your current system into a format that can be imported into MySQL. The format to choose depends on what software you have. E.g., Microsoft Access databases can be exported to an Excel file that can be imported into MySQL using the Navicat application in Windows.