RMDatabase README File
RMDatabase (RMdB) ver 4.1g
Written by: P. Eric Huber
moonlight@dbdev.biz		 Release Date: October 24, 2006
(dba Moonlight Design)
http://www.dbdev.biz

Many Thanks to...
Doug Schubert, Adam Bayless and Curtis Jewell for their original works on earlier versions of RMDatabase that gave me the foundation to go as far as I have gone with this. Thank you.
CONTENTS
DISCLAIMER

RMDatabase is not a commercial product and cannot be supported as such. I do try and help where I can, but sometimes it is just not possible. I will not be responsible for any data loss or damage that comes from usage of these scripts. By using them you agree to indemnify me from any liability that may arise from their use. I recommend routine backups your database (which is always a good practice anyway).



WHAT'S NEW IN VERSION 4.1?

RMdB 4.1 (MySQL) came about simply because I was doing more work with MySQL in my job and other areas that I decided to adapt RMdB to the popular back-end database as well. Since MySQL is open-source database (meaning, its free), it is gaining more popularity and is frequently offered as part of a hosting plan with most (good) ISPs. The main new feature of RMdB 4.1 is, of course, this change in structure. There are a few other enhancements that are listed below:

  1. Complete Bi-Language Capabilities - version 4.1 introduces a new language database format that allows for unlimited language values to be used on every page generated by the script. NOTE: Because of the difference of structure between version 4.0 and 4.1, old language parameters cannot be converted. The install comes with the default second language of Spanish. Other languages being used as the second language will need to be re-entered. Please contact me at moonlight@dbdev.biz if you use another language and have your database up-to-date, so I can get a copy of it for other requests.
  2. Optimized Broadcast E-mail Capability - version 4.1 uses a new method to generate e-mail broadcasts. Previously, large broadcasts always created problems for administrators due to browser timeouts. With this version, administrator broadcast messages are sent to the server to run as another batch process in the background, so browser response time is much quicker.
  3. Protected Personal Information - version 4.1 requires that all registered alumni have a login and password to be able to view e-mail and mailing addresses of alumni (This is controlled by the webmaster through the use of a new template called view_public). Non-registered visitors can still contact alumni using a form that generates an e-mail through the site (without the sender knowing the recipient's e-mail address).
  4. Photo Upload Capabilities - People have been asking for this since the beginning and I have finally listened. One photo (either jpg or gif) can be stored with the profile record. The administrator can turn this on or off globally if they choose, and the maximum size of file is also controlled through the administrator settings.



DATABASE SETUP AND ACCESS

In order to run RMdB 4.1, you need to have access to a MySQL database on your hosting provider's account. If you host your site on mission.net this is already available. To get a database setup on mission.net, contact support through http://webmaster.mission.net and indicate that you need a MySQL database for RMdB 4.1. Also indicate whether you wish to convert your existing RMdB 4.0 database already on the mission.net server to RMdB 4.1.

NOTE TO ADVANCE USERS ON MISSION.NET SERVER. If you wish to use the phpMyAdmin tool with your database, obtain your database user and password from LDSMN support and access from the following URL: http://www.mission.net/mydb.




INSTALLATION

NOTE FOR MISSION.NET USERS - This process is done for you when you request database setup. Skip Installation section unless you are installing the scripts on a server other than mission.net

To install RMdB 4.1, follow the steps below.

  1. Obtain the rmdb_41x.tar.gz file by sending a request to me at the e-mail address above.
  2. Place the rmdb_41x.tar.gz file in your home directory and type tar -xzf rmdb_41x.tar.gz This will extract the files from the tar file and put them in a new directory called rmdb_install just below your home directory.
  3. Next you will need to edit the install.pl file in the newly created rmdb_install directory. Adjust the parameters at the top of the file to correspond to your environment.
  4. Next run the setup script:
    type ./install.pl
  5. Answer the questions the install script asks and then it will run through the installation process. Once it is finished, you will get a message indicating a status of complete if successful.
  6. The install script creates a new script that is customized for your environment (based on questions answered when you run install.pl). To create your database tables and initialize or convert your previous version of RMdB 4.0 to RMdB 4.1, type dbsetup. NOTE: If this command doesn't work, then goto the bin directory under your home directory and run it from there by typing ./dbsetup
  7. If you made it this far, then installation is complete!

    The URL to use for script access should be (unless you have customized it):

    http://www.mission.net/your/mission/cgi-bin/rmdb41.cgi

    (obviously you would replace the "/your/mission" portion with the actual mission name used if you are on mission.net and if you are not on mission.net, then you would begin with your own domain instead of "www.mission.net")


PATH MAP

This path represents the structure for mission.net users. If you are installing version 4.1 on your own server or ISPs server, you will modify the install script to identify your html root directory and cgi-bin directory, but everything else should be the same.

  Home directory
  bin
  bmail.pl
  dbsetup (only run once - at install)
  load_db.pl (called by dbsetup)
  makedb.sql (called by dbsetup)
  Other files...
  rmdb4
  lib
  config.pm
  rmdb.pm
  src
  add
  admin
  bulk_list.dat
  bulk_msg.dat
  column
  default
  edit
  error
  home
  new_usrs.txt
  new_usrs.txt2
  ok_rpt
  rqst_pw.txt
  rqst_pw.txt2
  user
  view
  view_public
  mission_html
  index.html
  count.html
  other HTML files and directories
 
  cgi-bin
  rmadm41.cgi
  rmdb41.cgi
  other cgi scripts
 
  rm_photos
  Directories (1-9)
  Uploaded alumni photo files
  css
  rmdb41.css
  images
  bad_ip.jpg
  bad_mail.gif
  del_rec.gif
  error.jpg
  ldsmn-88x31-m.gif
  mailbutn.gif
  mldmark.jpg
  rmdb_banner.jpg
  success.jpg


CUSTOMIZATION THROUGH STYLESHEETS AND TEMPLATES

RMdB 4.1 continues to use the same templates that were introduced in version 4.0 but adds more template files and tags. This is an advanced level of customization offered. You must be cautious when editing these files. If you don't understand HTML and CSS very well then I would suggest staying with the default files provided. Any any case, I recommend creating a backup of your rmdb4/src directory (created at install time) before you begin to make any changes.

STYLESHEETS (CSS)

Upon installation, the rmdb41.css file is copied into the /css directory off the HTML directory that was defined for your account. This will be the only file in this directory (unless you had this directory previously). You may edit this file, add more classes, but be sure and not delete the classes that are there. The scripts utilize these classes when creating modules both for administrator options as well as regular user options. Again, you may modify the parameters on existing classes, just don't change the class names. Another good tip - be sure and save a copy of the original css file - just in case.

TEMPLATES

RMdB 4.1 uses 11 template files for all of its functionality. Each template file is nothing more than a regular HTML file with special tags that the perl scripts run "search and replace" functionality on. In some cases, these tags also pass parameters to the perl engine that perform extra tasks or retrieve specific information from the database. These tags will be explained in detail below.

The 11 template files that are used are explained here. Each filename is fixed (you cannot define your own templates) and is used for a specific function:

add This template produces the registration page and form an alumni sees when they first register in the database. It will probably be similar to the edit template, but it is seperate now to give the administrator more flexibility.
admin This template produces the administrator login page and all other admin maintenance pages with the exception of the customize settings admin page.
column This template is whenever an alumni list or results of a "search" are displayed.
default This template is used for the admin customize settings page and any other page that isn't defined elsewhere.
edit This template displays the form that is used to edit alumni information.
error This template produces error messages that are displayed to the user.
home This template produces the main entry point page for the database script.
ok_rpt This template produces success messages to the user when a function is performed without error, such as changing a password, or saving an e-mail template
user This template is used for special user functions such as updating lost contacts, maintaining presidents, requesting contact, changing or requesting a password.
view This template displays all information defined for a specific alumni record to only users that have logged in successfully.
view_public This template displays limited information defined for a specific alumni record to a user that has not logged in.


TEMPLATE TAGS

All RMdB template tags use the following format (within the quotation marks):

    "[<tag_name>:<param>]"

where <tag_name> is the name of the tag and <param> is the parameter string that is passed. NOTE: some tags do not require parameters.

Not all tags are available on every template. A list of the tags available as well as the templates they are available on and the function that they perform is explained in the table below.

Tag Name Valid Templates Description
[COLOR:<param>] ALL TEMPLATES This tag excepts a from the list below which corresponds to the values setup under the "customize settings" option:
MOD1_HEADModule 1 heading color
MOD2_HEADModule 2 heading color
MOD3_HEADModule 3 heading color
MOD_BG1Module 1 background color
MOD_BG2Module 2 background color
MOD_BG3Module 3 background color
[WIDTH:<param>] ALL TEMPLATES This tag excepts a <param> from the list below which corresponds to the values setup under the "customize settings" option:
LGLarge module width
MDMedium module width
SMSmall module width
[PATH:<param>] ALL TEMPLATES This tag excepts a <param> from the list below which will substitute the appropriate URL value:
IMAGEthe (URL) path to the images directory
HOMEthe (URL) path to the mission homepage
CSSthe (URL) path to the rmdb4.css file
CGIthe (URL) path to the rmdb4.cgi script
[COPYRIGHT:] ALL TEMPLATES This tag requires no parameter. NOTE: It is required to use this tag somewhere on all templates.
[BODY:] default
column
error		 This tag requires no parameter. It is used to display the main content on the default, column and error templates.
[HTML_BODY:] view This tag requires no parameter and must be used on the "view" template. It is used to create either a default (empty) <BODY> tag when no javascript alert message is present, or it creates a special <BODY onload...> tag that creates an alert message popup if a photo upload is attempted on an invalid file type or exceeds the size limit.
[TITLE:] ALL TEMPLATES This tag requires no parameter. It should be used between the <TITLE> and </TITLE> HTML tags on all template files to capture the page title.
[PAGEHEAD:] admin
default
column
home
user		 This tag requires no parameter. It displays a page header text message on each page dependent upon the template that is used.
[MAIN_REG:] home This tag requires no parameter. It displays the value from the language DB that represents the link to Register.
[MAIN_LNG:] home This tag requires no parameter. If a second language is defined. This tag will display the the other language name as a link to toggle that language active.
[MAIN_NEW:] home This tag requires no parameter. It displays the value from the language DB that represents the link to view newly registered alumni (last 30 days).
[ADM_MAILTO:] ALL TEMPLATES This tag requires no parameter. This tag will create an <a href="mailto:"></a> HTML link and display the administrator's name as the link (linking to the administrator's e-mail address).
[MISSION:] ALL TEMPLATES This tag requires no parameter. This tag will display the mission name (as defined in the "customize settings" option).
[ACTION:<param>] add
edit
home
user
view
view_public		 This tag will accept one parameter on all but the "add" and "edit" templates and one of two parameters on that template. They are explained below:

On all defined templates use [ACTION:OPTIONS] to display the "Options Module". The options module will vary based on template and user logon state. If the user is logged in and currently viewing their own profile, then the options module will display maintenance options for that user's profile. If a user is logged in but not currently viewing their profile, then the options module displays a welcome message, the user's name and a link to go directly to their profile. If the user is not logged in, the options module will display a login user and password form along with a password request button.

On the "add" and "edit" templates use [ACTION:FORM_START] to setup your <form> tag and the appropriate action related to either editing an existing entry or adding a new one.

Also on the "add" and "edit" templates use [ACTION:FORM_SUBMIT] to setup your submit button within your form. This tag will also determine if it is new entry and ask the user to enter a userid and password.

On the "view_public" template you can use the [ACTION:CONTACT] tag to setup a message and link to contact the alumnus through the page without revealing the e-mail address in the alumni record.

[MODULE:<param>] ALL TEMPLATES* This tag will accept parameters that correspond to modules displayed on the the main database page (*all but NAV will only work on the home template). These parameters are described below:
MAINDisplays the main count line from the language DB
SRCHDisplays the search module
LISTDisplays the lists module
FOOTDisplays the problems/contact footer from the language DB
ADMDisplays the Admin Options module
NAVDisplays the navigation module with links to the main mission homepage and main database page

This tag also accepts an additional parameter that will override the default width of the module called (EX: [MODULE:ADM,150] will display the admin options module using a table width of 150 pixels).

[LANG:<param>] add
edit
column
error
home
ok_rpt
user
view
view_public		 This tag is new to version 4.1. It accepts a parameter that directly links to the lang_code field in the new language table. This parameter is the key to truly having bi-lingual pages. You can even put varying image tags inside your language database and have a different image display whether the first or second language is active.
[FIELD:<param>] edit
view
view_public		 This tag will accept a value corresponding to list of fields below and display that value:
RECNOThe alumni record ID
MISSIONARYMissionary title lastname "Elder Jones"
FULLNAMEFirstname Lastname (now)
SPOUSESpouse
SERVETIMEStartdate to Enddate
EMAILE-mail address (or "None" if blank)
HOMEPAGEhomepage (as link)
WORKWork/School (as link if workURL)
CITIESCities and Companions comments
OTHEROther comments
CURADDCurrent Address
CURPHNCurrent phone
PERMADDPermanent Address
PERMPHNPermanent Phone
PRESMission President(s)
CHILDRENChildren
LASTUPLast updated date
MISSIONMission
OCCUPATIONOccupation
PHOTODisplays photo along with header defined in the language database if photo is present. If not, the whole table row (<tr>) is ommited
[INPUT:<param>] edit
add		 This tag requires a parameter that represents the input field on a form. It optionally can accept a second parameter which represents "size" for HTML <input> tags or "cols" for HTML <textarea> tags.

(EX: [INPUT:LASTNAME,15] would generate an input tag with "size=15" as an element of the tag). If no size value is included, the default size for the field in question is used. The valid input names that can be used are listed below:
LASTNAME Last name (while in the mission).
FIRSTNAME First name
SPOUSE Spouse
BEG_MONTH Starting Month select box
BEG_YEAR Starting Year select box
END_MONTH Ending Month select box
END_YEAR Ending Year select box
EMAIL E-mail Address
HOMEPAGE Homepage URL address
WORK Work or School name
WORKURL Work or School URL
CITIES Companions and Cities text
OTHER Other comments text
C_ADD Current street address
C_CITY Current city
C_STATE Current state
C_ZIP Current zip code
C_CTRY Current country
C_PHONE Current phone
P_ADD Permanent street address
P_CITY Permanent city
P_STATE Permanent state
P_ZIP Permanent zip code
P_CTRY Permanent country
P_PHONE Permanent phone
DEFAULT_PRES NOTE: This is only available on the "add" template. This is the main mission president for the alumni record. Once a profile record is created, then maintaining mission presidents is done through the user options and is not available as an input field on the edit template.
CHILDREN Children's names
MISSION Mission name select box
TITLE Missionary title select box
OCCUPATION Occupation
LAST_NOW Last name (now - married name for sisters)
PHOTO Photo upload input (and status). Indicates of photo is currently present and allows user to remove photo if desired. New photo upload will always replace existing photo.

For the best example of how to use tags, study the default templates that come with the installation. Make sure to save them for future reference as needed.

A WORD ABOUT COPYRIGHT AND LICENSE

Now finally, please be respectful of my copyright notice. I know to some, it may be considered a nuisance and I didn't require it on earlier versions - in fact, I even allowed the admin to customize the copyright line as they saw fit. I appreciated those that kept me (Moonlight Design) listed even when they were not required to do so. The "footer" class within the stylesheet controls the display of the copyright. You can adjust it how you see fit but I do ask that it be large enough to be readable.

This version of RMdB is freely available to affiliated LDS Mission Network sites only. It is not available to download freely, without contacting me first. I will send the tar file to those who request it, but I ask that it not be distributed without my permission. I don't have any problems with people tweaking the code for use on their mission sites (although with the use of templates and stylesheets, this should be minimized), but selling, distributing, or profiting from the code is strictly prohibited. If you wish to use RMdB for other purposes outside of the above stipulations, please contact me.



CONTACT INFORMATION

Eric Huber (dba Moonlight Design)
Home: (801) 299-0851
Work: (801) 297-1654
moonlight@hubernet.com