Table of Contents

Setting Up A ReadingRecord Site

This document outlines how to setup a ReadingRecord site using the fictitious “Demo Library”. Examples & screenshots are included where useful.

IMPORTANT: If creating your own Demo Library site, you can use 'demo' as the host name, but you will need to use your library's DNS domain in place of '.readingrecord.org'. When applicable, text will be enclosed in square brackets & [highlighted in yellow].

Forms Review

The Demo Library has 3 programs: Kids, Teens & Adults. They have submitted the following forms & included a library banner, so it looks like we have everything we need.

DNS Record

ReadingRecord requires a valid DNS address (A) record to function. Reverse (PTR) records are optional. Depending on your network configuration, you may need both internal and external DNS records. Please note that external DNS records can take awhile to propagate.

Create Databases

Next we need to create databases. Since the Demo Library has 3 programs, we will need 1 config database & 3 program databases. You will need to decide on a DB prefix. In most cases the host portion of the URL is used, so we'll use 'demo' for the Demo Library.

Create MySQL User

Now we need to create a MySQL user account with appropriate privileges. You will need to decide on a MySQL username. This account will not be used by staff, but rather by ReadingRecord to add, update & delete records. In most cases the host portion of the URL is used, so we'll use 'demo' for the Demo Library.

Create The Config File

ReadingRecord uses a config file to provide MySQL database information & credentials. The name of the config file must match the full URL for the site plus '_config.php'. For the Demo Library the file name is 'demo.readingrecord.org_config.php'. Copy the file 'ReadingRecord/config/SAMPLE.readingrecord.org_config.php' to 'ReadingRecord/config/demo.readingrecord.org_config.php' [Use your own DNS domain to create the config file, eg: 'demo.mydomain.org_config.php'].

The finished config file looks like this: 

<?php
 
 
/*
Copyright (C) 2012, 2013 by the Free Software Foundation, Inc. http://www.fsf.org/
 
This file is part of ReadingRecord.
Created & developed by Eric Sisler <lbylnxgek@gmail.com>
 
ReadingRecord is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
 
ReadingRecord is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
 
You should have received a copy of the GNU Affero General Public License
along with ReadingRecord. If not, see http://www.gnu.org/licenses/.
*/
 
// Subversion: $Id: SAMPLE.readingrecord.org_config.php 448 2013-01-04 04:17:42Z esisler $
 
//
// Global configuration.
// NOTE: Most global & program configuration setting contained in the
//       global & program databases.
//
 
// Credentials for database access.
$configGlobal['dbHost'] = 'localhost';
$configGlobal['dbUser'] = 'demo';
$configGlobal['dbPasswd'] = '8NYWW4vGAVF29qfd';
$configGlobal['dbConfig'] = 'demo_config';
 
//
// End global configuration.
//
 
?>

Add The Library Banner

Currently the library / program banner is a separate file rather than contained within the ReadingRecord database. This will (hopefully) be fixed in a future release.

Configure Global Options

Now it's time to configure site-wide options, which are contained in the 'demo_config.global' table. The Demo Library submitted 1 setup form & 3 program customization spreadsheets, which we will use to set options in this and other tables.

FIXME: Full list of DB fields

Add Staff Accounts

Per the setup form, the Demo Library has 2 accounts for accessing ReadingRecord: One for staff & one for volunteers.

Configure Program Options

Next we need to configure program options, starting with the kids program.

Populate Tables For Drop-Down Lists

Next we'll populate the tables used to create drop-down lists on the registration form. This procedure is used for the following fields:

The Demo Library has chosen to track the age, city, gender, library (branch) & school fields for their Kids program.

Populate Table For Levels

Lastly we need to populate the table used for levels. The procedure is the same as for drop-down lists with one addition.

Test The Site

We are finally ready to test our site! [Substitute your library's DNS domain when testing the site, eg: http://demo.mydomain.org/]

Congratulations! You can add, update & delete readers & completed levels, which means the Kids program for the Demo Library is configured correctly & MySQL permissions are correct.

Setup The Other Programs

Making Adjustments

One thing I am frequently asked as libraries begin using ReadingRecord is: “Can we make changes to our configuration?”. For example:

The answer to all of these questions is “Yes!”. ReadingRecord was designed to be fairly flexible, and became more so in 2013 with the ability to change the label of all fields.

To add the e-mail address for the teen program

To add a couple of schools to the kids program

To move "HOMESCHOOLED" to the top of schools drop-down for the kids program

To combine the city & zipcode fields for the adults program

There are a couple of ways to solve this problem:

To fix the typo in the city drop-down of the adults program

In all cases, the changes take effect immediately. No need to logoff, close the browser, etc.

Tip: For changes as potentially complex as the “combine city & zipcode” example, I would recommend contacting the staff hosting your ReadingRecord site or me. Hopefully one of us can offer suggestions & help.

Things ReadingRecord can't do

Getting Ready For Go Live

Once all programs have been setup & tested, perform the following tasks before self-registration starts:

Tips, Tricks & Warnings About Drop-down Fields & Levels

About '_id' & 'sort_ord' columns

By now you may be wondering: “Why do tables used to populate drop-down fields & levels have '_id' & 'sort_ord' columns?”

id columns

One thing I learned from all those years of hanging around catalogers (Thanks Judy Houk - I miss you!) is the value of “authority controlled” fields:

Drop-down lists in ReadingRecord work much the same way:

Make sense?

sort_ord columns

Librarians like options, and to be able to change their minds about those options. This is not a bad thing, but can sometimes complicate things. One thing I learned from a number of ILS migrations (Yes, I still have hair! ;-)) is that sometimes “sort ascending” and “sort descending” aren't quite enough.

The 'sort_ord' column does just what the name implies - determines the sort order of items in drop-down lists & levels:

Tips & Warnings

WARNING: Because IDs rather than descriptions are stored in various places (in particular the 'reader' & 'record' tables), you should NEVER:

  1. Delete records in “authority control” tables, including:
    • age
    • city
    • gender
    • grade
    • level
    • library
    • school
    • zipcode
  2. Change the value of any column ending in '_id'.

Doing so can mangle your data. You have been warned!

Now that that's out of the way, let's look at some instances where this might be necessary & how to safely go about doing so:

I need to add records between two existing records, but there not enough unused 'sort_ord' values

If you've gone through the process of setting up the Demo Library, you should have noticed that I incremented the 'sort_ord' value by 10 when creating the CSV file for import. This is in case you need to change the sort order and/or add new records after the initial import.

For example, let's say you've setup your own site and the school table currently looks like this in sorted order:

school_id desc sort_ord
3 HOMESHOOLED 5
4 NOT IN SCHOOL 7
1 Avista Elementary 10
2 Bradburn Elementary 20

You need to add the following schools, but there aren't enough unused 'sort_ord' values (which must be unique) between “NOT IN SCHOOL” & “Avista Elementary”. You have 3 schools to add but only 2 available sort_ord values - 8 & 9:

It looks as if all 4 records were part of the initial import, but that “HOMESCHOOLED” and “NOT IN SCHOOL” were originally at the bottom of the list. In this case there isn't any need to delete any records or change any IDs, but we need to “shift” Avista's 'sort_ord' before we add the new schools. Using phpMyAdmin, change Avista Elementary's 'sort_ord' to 15, the school table now looks like this:

school_id desc sort_ord
3 HOMESHOOLED 5
4 NOT IN SCHOOL 7
1 Avista Elementary 15
2 Bradburn Elementary 20

Now add the new schools, using the following 'sort_ord' values. Remember that MySQL will automatically fill in the 'school_id' column:

desc sort_ord
Abel Elementary 9
Accel Academy 11
Apex Learning Center 13

When sorted by 'sort_ord', the completed table should now look like this:

school_id desc sort_ord
3 HOMESHOOLED 5
4 NOT IN SCHOOL 7
5 Abel Elementary 9
6 Accel Academy 11
7 Apex Learning Center 13
1 Avista Elementary 15
2 Bradburn Elementary 20

You could use sequential numbers for the new schools, but the example above leaves space for one school between each new school. If you later need to add more schools between “Accel Academy” & “Apex Learning Center”, repeat the “shift” procedure until you have enough unused 'sort_ord' values. You can also shift the 'sort_ord' of records before the insertion point.

Success! We added new schools in the correct order without deleting any records from the school table or changing any 'school_id' values.

I need to change a school's name & sort order

To expand on our previous example, let's say the “Accel Academy” has changed its name to “Colorado Virtual Academy”. You might be tempted to add a new school to the table with a 'sort_ord' value that puts it after “Bradburn Elementary”, then delete the record for “Accel Academy”:

school_id desc sort_ord
3 HOMESHOOLED 5
4 NOT IN SCHOOL 7
5 Abel Elementary 9
7 Apex Learning Center 13
1 Avista Elementary 15
2 Bradburn Elementary 20
8 Colorado Virtual Academy 25

Doing so would violate rule #1: NEVER delete records in “authority control” tables. This would orphan records in the 'reader' table where “Accel Academy” (school_id=6) was selected. More specifically, these records would have an non-existent value for 'school_id', which would make statistics incomplete and exported CSV data incorrect.

A better solution would be to simply change the 'desc' & 'sort_ord' fields of the “Accel Academy”. This way you avoid invalid data & incomplete statistics, plus all readers formerly attending “Accel Academy” have automatically been updated to “Colorado Virtual Academy”.

school_id desc sort_ord
3 HOMESHOOLED 5
4 NOT IN SCHOOL 7
5 Abel Elementary 9
7 Apex Learning Center 13
1 Avista Elementary 15
2 Bradburn Elementary 20
6 Colorado Virtual Academy 25

I need to delete an invalid zipcode

After go live, staff reports an invalid zipcode, 80931:

zipcode_id desc sort_ord
1 80030 10
2 80031 20
3 80931 30
4 80221 40
5 80224 50

You run the zipcode report & discover that some registrations are using this zipcode. You decide to “merge” this with the correct zipcode of 80031. There are a couple of ways to do so:

Once all records have been updated, delete the invalid zipcode.

What if self-registration hasn't begun and I need to make major changes?

If your site is still in test mode and you need to make major changes, it can be easier to simply start over. Let's say you need to completely re-do the school table. Your library district just grew and you find your service area now includes many new schools. Additionally, staff testing your site discover some missing schools & some that have changed names. In this case I would:

Navigation

Previous: Install & Configure ReadingRecord | Next: Database schema information