BookAdder Docfile:
Upgrading

BookAdder: Upgrading From Earlier Versions

About the name BookAdder: long ago, this toy used to be know as "Freebie", and I'd just as soon have kept that name, as it is now tolerably well known. Regrettably, I have found that a great many email programs' spam filters are so set that they will bounce any email whose subject line contains the word "Freebie", which often meant that emails from me (and perhaps to me) about this tool were never delivered. So I reluctantly changed the name. Though the tool is much improved in the 4.xx release, it is at bottom the same familiar "Freebie".

The 5.xx version of BookAdder has some notable difference from earlier versions, under either name; most of them are almost entirely "under the hood" (that is, not visible to visitors to your bookshops), but there is one big one, necessitated by major changes in the way Amazon dispenses data from its databases. That change is the need for you to have, and enter into BookAdder, a pair of "keys" (data strings) that you get from Amazon by enrolling in their "AWS" (Amazon Web Services) program; how, exactly, to do that is described elsewhere, but I'll just repeat it here for convenience:

  1. Go to Amazon's AWS enrollment page (clicking the link in this sentence will open it for you in a separate tab or window).

  2. Use your existing Amazon sign-in data (email address and password) to sign in as a "returning customer".

  3. Complete the simple and obvious enrollment process.

  4. When you are enrolled, roll your cursor over (but do not actually click on) the Your Account heading in the upper right of most or all AWS website pages; that will show a drop-down list of possibilities. In that list, click on Access Identifiers.

  5. One of the first major headings showing will be Access Key ID and Secret Access Key. The Access Key ID will be visible, while the Secret Access Key will initially be hidden; to show the hidden Secret Access Key, click on the + sign that says Show.

  6. Record both keys carefully, making sure you know which is which (the secret key is always 40 characters long). You could write them down, but it is better, to minimize the chance of error, to cut-and-paste them to a little text file.

  7. Log off the Amazon AWS site (click on Sign Out). You now have your keys. Using them in BookAdder will be explained in the Installation instructions.

And here's how you enter those keys into BookAdder:

Using any simple text editor, open the package file named access.php. In access.php, replace the strings of zeroes with your corresponding actual Amazon keys: obviously, $accesskey is your "Access Key ID", and $secretkey is your "Secret Access Key". Be very, very sure to change nothing at all in the access.php file except for the actual keys as placed between the single-quote marks. You should end up with something that looks sort of like this:

<?php
$accesskey='LETTERS7AND3NUMBERS9';
$secretkey='40characters6of7letters9andnumbers2mixed';
?>

Broadly speaking, the path I strenuously recommend for "upgrades" is to--in effect--entirely pitch your old shop and install as if anew; then, working from a saved copy of your old shop's files, you would customize the new one as you feel necessary or desirable. This docfile will explain how you can best proceed.

Remember that your bookshop may have to disappear during the changeover (for up to an hour or two), so try to schedule your new install for some slack time--very late at night or very early in the morning.

Critical Upgrade Note About Abebooks

If you are an Abebooks affiliate, you should already know that some while ago Abebooks moved its account from Commission Junction to Google-owned Performics. If you correspondingly set up a new Abebooks account at Performics, fine--but, if you did not (and thus are still using the now-dead Commission Junction links), you are throwing money away. In the new BookAdder setup, you will need to supply a Performics Abebooks Publisher ID: your old CJ ID is useless. If you haven't yet changed, click on the link in this box to set up your Performics Abebooks account. And there's no time like the present.

Preserving Customizations

If your current bookshop has minimal customizing--typically nothing but the handful of data entries in the customize.php (or, in really older versions, customize.inc), your job is quite simple. If you did massive customizations, even beyond what these docfiles discuss, you have a task in front of you; but, if that is the case, I ask you to spend a few minutes reconsidering, because--in my opinion--it is not needful that your bookshop pages conform to whatever may be the "look and feel" of your site's main pages, in that the bookshop is, in effect, a little "sub-site" of its own. So--again, in my opinion--it is not essential that your shop pages have whatever decorative images or side-column layouts or special fonts as may characterize your main site: save yourself needless work in trying to make everyting match exactly. That said, here's how I suggest you proceed.

Begin by preserving what you have now. In your local (that is, on your computer, not on your web-site server) directories, make a subdirectory off whatever directory in which you have these new package files (including this that you are currently reading) stored; name it something simple, like "OLD". Then simply download to that subdirectory a copy of every package file you are using now (that is, everything now in the main package directory on your server). That way, you don't take a chance on forgetting some file you tweaked outside of the supplied instructions.

With your old shop now fully preserved, you will--by following the step-by-step directions farther on in this file--next essentially wipe out that old shop and install as if anew. But note that the "wipeout" will not erase your current data-result files (nor your map files), so as soon as the new install is in place, you will again have an at least functional shop (unless your current version is so old that all the formats were different--but that will be no problem once you have done a first run with the new shop).

As part of the new install you will, of course, need to enter the basic data in the customize.php file, most or all of which will be in the corresponding file in your "OLD" backups. On the other hand, this is probably a good time to take a moment and reconsider whether you are satisfied with those data as they stand or might want to make some small changes. You can refresh yourself on that file and those data by reviewing the package docfile Installing BookAdder.

Once you have completed the new install, you can at once follow up with re-applying the most essential other customizations, the most urgent of which would be (if they apply to you) the Google AdSense Publisher ID (in adsense1.php) and the Digitalpoint Co-Op Network insert (in coopads.php); then, at your leisure, you can fill in the rest, such as "recommended books" or "look and feel" colors and fonts. Remember that in this new bookshop version, you can now set both the basic required customizations and the "look and feel" elements interactively on line, so I wouldn't bother trying to text-edit in those data prior to the install.

To remind you of all the other package files that you can customize, and what's in them, and how you customize them, read carefully the package docfile Further Customizing. In most or all cases, you will already have a like-named file in your existing setup from which you can extract the wanted data (which--again--you might take a moment to re-consider anyway if it's been a while since your last install). The only extra data I think critical to get fixed up right away, if they apply to your case, are the Google AdSense Publisher ID (in adsense1.php) and the Digitalpoint Co-Op Network insert (in coopads.php). The rest you can get to at your convenience.

In any event, though, if you are manually applying old customizations to this new package:

  1. do not simply copy an old file over the like-named (or similarly named) newer version! Read the data in question from the old copy (now stored in your newly made "OLD" subdirectory) using any text editor and enter it into the appropriate places in the new files; and

  2. remember that whenever you upload any package file or files to your server (other than at actual install time), you must immediately thereafter run reperm.php to correctly permission those uploaded files (re-read the other docfiles if you don't understand what I'm saying here).

(In seriously older versions, customizeable files now with names like something.php might be named something.inc.)

To refresh you in brief, the chief customizeable package files are (in rough order of likelihood you modified them) these:

  • customize.php
  • adsense1.php
  • looknfeel.php
  • coopads.php
  • recommendedbooks.php
  • rollyourown.php
  • freepasses.php

The less likely but possible candidates for having been customized are:

  • timer.php
  • pings.php

And the really unlikely but not impossible candidates are:

  • bookshop.htm
  • hold.htm
  • amazonmessage.htm
  • booksearch.htm
  • usedbooks.htm

If you customized anything else, you should know what it is, since any such other customizations would be beyond anything suggested anywhere in the package documentation.


Cleaning Up

These are the few things you need to consider and perhaps attend to before doing your new install.

Your .htaccess File

If you are using a package version so old that it relied on your site's main .htaccess file, be sure to remove any old "Freebie"-related entries whatever from that file. If you ever used such a version, be sure that there are no "leftovers" lurking in your .htaccess file.

(This refers to your site's main .htaccess file; don't confuse that with the local-only little .htaccess file included in the new package.)

Be aware that your .htaccess file is an extremely critical system file, so edit with extreme care, being absolutely, positively sure to have a backup copy handy. As soon as you make any change whatever to that file, you should always check, at once, that your regular (non-Freebie/non-BookAdder) web pages seem to be getting delivered OK to your browser.


Your robots.txt File

Although the install will make a suggested replacement for your current version, it helps to start clean if possible. So edit this file to remove anything in it associated with any prior Freebie or BookAdder version. Doing that is especially important if there are references to an install in a directory named differently from the one you will be using now.

(Mind, there's no harm in having entries in robots.txt that refer to non-existent directories; but it's good to have a file that reflects reality, so you don't get confused later on about what that file is doing.)

(Any entries associated with old "Freebie" should all be recognized by having in them whatever Freebie or BookAdder package directory name you assigned.)


Your Main Sitemaps_index.xml File

Later BookAdder versions, including this one, keep all their files within their own directory structure: that includes the sitemap files they automatically generate, and the index file for those maps. If you have any bookshop-related sitemap files in your root directory (or elsewhere), including a map-index file, delete them. That also includes any entries in any all-site sitemap-index files.

Take care! Be sure that no old bookshop map-index file contains an index entry for a main (non-bookshop) site map, such as one named staticmap.xml; if it does, transfer that entry to an all-site sitemap-index file (or make one anew if you don't already have one, or just separately register the all-site map, such as staticmap.xml, with the search engines).

(If all that is not perfectly clear to you, you need to review at least the docfiles of this package where they discuss sitemaps, and going elsewhere for help wouldn't be a bad idea.)

Recall that if you have a staticmap.xml file made in whole or part by an earlier Freebie or BookAdder version, it may contain references to some old bookshop files; you should eliminate from any such staticmap.xml any references to any bookshop-related files--as noted, those are now all handled in the bookshop's own sitemaps (which, in accordance with the instructions elsewhere in these docfiles, you should register separately with such search engines as you please (see the package docfile Tuning Your Search at the heading "Setting Up Sitemapping").


Doing the Install

Because your bookshop will be down for the duration of this process, do not start it till you are completely prepared. That means you will have done all the things described above, and have ready to hand all the data needed to proceed with the configuration of customize.php. You could even pre-edit that file, and any other customizeable ones, before starting the install; just remember, as always, to use a real text editor, not a word processor (because those can insert all sorts of extra junk in a file).


Preliminary Wipe-Out

Do not yet upload any of the package files except the one ominously and warningly named bomb.php. When you run that file, it will erase most of your current bookshop! More exactly, it will do these things (in this order):

  • It will re-name any files extant in your bookshop's Backup subdirectory (those are the ones most likely to have been customized) with a tag using the current date and time. For example, a file in your backups/ subdirectory named customize.000 would be renamed to something like customize.000.20090103112341 (depending on the actual date and time of the run). This step is not necessary if you have followed the instructions here and downloaded your entire current package main directory contents to a local subdirectory, but "belt and suspenders" never hurts.

  • It will put a one-line entry in your current logfile (logs/Shop.Log) recording the cleaning out.

  • It will erase all files in your main package directory--which is whatever directory you uploaded the bomb.php script to, so be awfully careful that you put it in the right place! (Note that the erasure includes bomb.php itself.)

  • It will erase all files in your working/ subdirectory (those are work products generated during search runs, and not part of what your visitors see).

  • If there exists a subdirectory named originals/, it wipes out the contents of that as well (older versions mostly don't have that subdirectory).

Note that bomb does not wipe out any of your actual data files--if worst came to worst, you could re-upload your backed-up old directory contents and be right back in business as you were.


Re-Install

Just do a normal install, as if from scratch, following all instructions in the Installing BookAdder docfile. (If you have pre-customized some or all of the customizeable files before the upload, things will go faster, but do stick to the plan: start with tryme1st.php and go on as instructed.)

If you did not pre-edit your old customizations into the new package files, you can now do so, once you have ascertained that the re-install has taken satisfactorily. (Again: this might be a good time to review your old customizations, to see if they are still the way you want things to look and work.)

(Note well that both customize.php and looknfeel.php are now editable interactively on line via the package scripts setup.php (for customize) and showstyle.php (for looknfeel), and also that what wants or needs customizing in those has changed slightly since earlier versions.)

You should now be left with a perfectly functional new set of bookshops (but make sure automatic daily updating is correctly in place). If you have any problem, e-mail me at once and we'll work it out with you.


Moving On

BookAdder Documentation Files Available

They are:


What to Read Next

Rather obviously, Installing BookAdder.