Customizing the Package Pages

What Can Be Customized

Two package pages both can and should be extensively customized by you, so that their "look and feel" melts seamlessly into the rest of your site. Those two are your new bookshop's "front door", mybookshop.shtml, and the template file holder.shtml that sets the appearance of the 28 pages that list all your shop's titles.

(There are three other pages, mentioned farther on here, that you will probably also want to customize, though they are less critical.)



Customizing the 28 Title-Listing Pages

The 28 pages created daily in your new /golf-books/bookpages subdirectory have the general file-name form--

     book-titles-@.shtml

--where the @ shown above may really be @, or may be ~, or may be any of the 26 letters of the alphabet. Those 28 pages are the ones that list the various titles your new bookshop offers your visitors.

You can--and probably should--customize the look of those pages, something you do by customizing a single template file, holder.shtml.

Here is what you need to know to safely safely customize those 28 pages. Each has this general internal structure--

pagetop
   <table> open:
      actual-titles dropin
   </table> close
pagebottom

--where pagetop and pagebottom are nearly the same from page to page, the only difference being the use here and there of the actual alpha (or other) character appropriate to that particular page.

The "actual-titles dropin" is represented in the template file, and the 28 resultant actual files, by an shtml include statement that includes in that page, whenever a visitor calls it, the content of the corresponding alphabetical package-generated search-results file (each line of which is one title's data as a table row).

You can make the page look like whatever you want, subject only to these four rules. (Looking at the supplied sample template file holder.shtml will illustrate the use of these rules.)

  1. Wherever you want the title character of the page to appear in the actual, individual page, use the three-character symbol ^^^ (three carets, the caret being the symbol normally found on the upper-case of the number 6 key of the regular keyboard area). When holders.php runs, it replaces any such symbol with the actual character appropriate for that file (A - Z or @ or ~).

  2. Wherever you want the search terms you are using to appear in the actual, individual page, use the three-character symbol @@@ (three "at's", the "at" being the symbol normally found on the upper-case of the number 2 key of the regular keyboard area). When holders.php runs, it replaces any such symbol with the particular search phrase you have specified (which is why it is important to properly initial-cap it in your customize.inc file).

    (If you are using a "complex search", you should manually replace all instances of @@@ with a term of your choosing that sums up in a pithy phrase what it is that the complex search is looking for.)

  3. Be sure to leave the shtml include statement--exactly as it appears in the supplied template--where you want the actual title blocks to be dropped into the file. That line will look like this:

    <!--#include virtual="/golf-books/bookpages/dropins-^^^.html" -->

    Don't fiddle with it unless you know exactly what you are fiddling! (You do not need to customize that line--the holders.php does customizing on the fly when it builds the 28 files from this template).

  4. The individual-title dropins are all "table rows" (<tr></tr> blocks), so you need to bracket that "include" statement with a table-open and table-close line pair, as in the supplied sample holder.shtml page; but you can set the table width, background color, alignment, and so on to suit your needs and tastes.

Note! Any changes you make in holder.shtml can be made effective immediately after re-uploading it (see below) by simply running the script holders.php (this link will actually run it). You do not need to do a new search: the search results are the separate dropins, which are left unchanged by holders.php Just don't forget to follow the upload procedure--shown in a box a little farther down this page--whenever uploading a modified holder.shtml file.

Beyond customizing the generic parts of the 28 title-listing pages, you can also customize the look of the individual-title blocks that are dropped in by the shtml include. These things you set direct in your customize.inc file (these changes, of course, will only take effect with a new search run).

What they are, and what you can change with them are:

  • at Step 6 in customize.inc:

       $itembkground='ffffff';

    This, in standard html color-designation form, is the color that will be used as the background for each title block; as you see, it defaults to white. You can set it to anything you like: be aware that the package checks nothing about your setting save that it is exactly 6 characters long, so you can mess up your pages badly by using invalid settings. (Also keep in mind how your "link" and "visited link" colors will look against your chosen background color.)

  • at Step 7 in customize.inc:

       $itemtext='000000';

    This, in standard html color-designation form, is the color that will be used as the text color in each title block; as you see, it defaults to black. You can set it to anything you like: be aware that the package checks nothing about your setting save that it is exactly 6 characters long, so you can mess up your pages badly by using invalid settings. As usual in html, regardless of this setting, links will appear in the colors set for them in the <body> area of the template holder.shtml file.

  • at Step 8 in customize.inc:

       $itemshrink='1';

    This, in standard html relative font-size form, is the shrinkage that will be applied to the text font for each title block; as you see, it is preset to 1. It accepts only three values as valid, and defaults to 0 if it finds an invalid value. The three values are 0 (text will be the same size as on the rest of the page), 1 (the font will be one size smaller than that on the rest of the page), and 2 (the font will be two sizes smaller than that on the rest of the page). I recommend against using 2 unless you feel you simply must use a page format that allows only a relatively narrow column for the title-listing blocks. Never forget how many users have weaker eyes than yours, and smaller and poorer monitors than yours.

One other thing--perhaps small, but one you might look at: the use of quotation marks around the search word or phrase. They are present in the supplied template, and can do no harm if left in; but, if your search phrase or word can stand alone, you might want to remove those quotation marks for esthetic reasons. The difference is in uses such as "Vegetables" Books versus History Books. In the first case, the words without the quotation marks would look a bit bizarre, whereas in the second case they don't, and so the marks might be an unneeded complication. (As you see, singular and plural have a lot to do with this, but it needs case-by-case judgement). As I say, a small thing, but there it is.

That's it! You can leave the template just as it is, or play with it to your heart's content, or replace it completely (as long as you keep the tabled shtml include statement in it!). To upload a modified holder.shtml (or any file modified since the original install process), follow this procedure:

How to upload edited files:

Do not just upload the file!

Make a copy of the file with an "at sign" @ in front of the name:

   example: @holder.shtml

Upload that "at-sign'ed" copy to your /golf-books directory.

Run the script finstall.php (which can safely be run any time).

After finstall.php has made an "un-at-signed" duplicate, delete the
"at-signed" copies from both the server and your local directory.

After uploading any modification of the holder.shtml template file, just run holders.php to effect the changes at once, without doing a new search.

(Do not get confused if you are making file copies manually: the name of the template file, holder.shtml, is in the singular--no s--while the name of the script, holders.php, is in the plural.



Customizing the Bookshop "Front Page"

Tools and Techniques

The page mybookshop.shtml is what describes your bookshop and links to the various parts of it. It is essentially equivalent to the physical front door of a bricks-and-mortar bookshop.

For your convenience in working with this file, the installer sets up two special files, an shtml page and a php script. The shtml file is a near-copy of mybookshop.shtml, named shoptest.shtml, that resides with the rest of your package files in your /golf-books directory; it differs from mybookshop.shtml only in this: the links in it have been adjusted to accomodate its position one directory down from your root, which is where the "real" mybookshop.shtml is expected to live. So, you can view shoptest.shtml with your browser and, even though it is in the "wrong" directory, its links will work. You can thus play with editing a local copy of mybookshop.shtml without exposing your site's visitors to your work-in-progress.

The php script is named mbsconvert.php, and when run it will make--from the copy of mybookshop.shtml in your /golf-books package directory, not the one in your root directory--a new copy of shoptest.shtml. In short, you:

  1. edit your local copy of mybookshop.shtml;
  2. upload the edited copy to your /golf-books package directory (being sure to follow the procedure shown in the box a bit above);
  3. run mbsconvert.php (which is in your /golf-books package directory; and then
  4. look at shoptest.shtml to see what your changes look like.

(There is a shortlist for doing this, with links, at the end of this section.)

In that way, you can have a working mybookshop.shtml in your root for site visitors to see and use, while at the same time you are experimenting with new looks to that page in your package directory.

All that has an important consequence: regardless of what you actually name your "front-door" page (perhaps something like widget-books.shtml), you need to keep an exact copy with the particular, exact name mybookshop.shtml in your package directories--both local and, especially important, remote--because it is that file that is, one, used as a source for the shoptest.shtml file, and two, that is backed up by the package.

So: Whenever you make any change to your true front-door file in your root, copy that changed file to mybookshop.shtml in your package directory, and upload that copy to your host package directory.



This and That

The original install will provide you with a working sample of mybookshop.shtml. That working sample page is for a hypothetical site whose main topical theme is "widgets". It will already have been customized by finstall.php with your site's URL, package directory, and site title, so that mechanically it would actually work as is--but it quite obviously requires substantial reworking to properly reflect your site, your site's theme, and your site's "look and feel."

Some particulars to mind:

  • The page is shtml, and it has a server-side include that will display the exact number of books you are listing each day; naturally, that number will not be present until at least one search has been run. It occurs in the third paragraph, which begins Today, we have books on widgets . . .; normally, it will read Today, we have XXXX books on widgets . . . Be sure to leave that include as it is.

  • There is a sample book title block displayed that needs replacing. The only simple way to place a satisfactory sample book block on this page is to extract one from an actual search run. Download a copy of one or another of the 28 files named dropins-X.html, where X is one of the 28 letters and symbols, then transplant some one line (they are very long lines) of that file into the appropriate place in the mybookshop.shtml file (removing the sample there now). It behooves you to pick a title that is pretty well tuned to your site's theme, and that has a cover image at Amazon, and that has some editorial and reader comments (you find those things out by actually looking at titles as a visitor to your site would--in this case, by using shoptest.shtml and selecting a particular alpha page, then clicking on a particular title on that page).

  • You will notice that there are a couple of subsections in the sample especially recommending a few particular (hypothetical) titles. You can just delete that whole part if you're not into such recommending, but I reckon that mentioning a few books that you feel you, as an expert in the field, can get behind gives your page, and your bookshop, the look of something you care about and have labored long and hard over. (Here's an actual example of such selecting, and of customizing in general, from a real site.) You be the judge . . . .

If you want to use one of your site's existing pages as a template, the important actual text of the file is demarked by two lines:

<!-- BEGIN SIGNIFICANT TEXT: -->
<!-- END SIGNIFICANT TEXT: -->

You can just plug whatever is between those lines into a template page from your site to duplicate your site's "look and feel". (Of course, you can and should also edit the text, especially Header levels and and font effects.)

You can start your modification by doing a global search-and-replace of "widgets" with the theme topic of your site. Then, just go through the page manually. When you are done to your satisfaction, re-read, re-read, re-read!

Here again is the modification sequence, but with working links you can use as you go:

  1. Edit some revisions into your local copy of mybookshop.shtml.
  2. Upload your revision to your /golf-books package directory (being sure to follow the procedure shown in the box a ways above).
  3. Run the package script mbsconvert.php.
  4. Use your browser to look at the page shoptest.shtml in your /golf-books package directory.

Repeat that cycle till you're perfectly satisfied that mybookshop.shtml is fully ready to be a page in your site. Then upload your local copy to your actual root directory. (This upload you can just do, since the file is not acted on by PHP, so that its "permissions" are not significant.)

If you are setting up for the first time, be sure to then provide internal links from elsewhere on your site to your new bookshop's front page. And it wouldn't hurt to try to get some links to that page from outside.

If you would like to rename your actual "front door" file to something other than mybookshop.shtml, you are quite free to do so--no other part of the package refernces it by name. There is one thing, though, that you need to keep in mind: you should continue to keep an up-to-date exact copy of this file in your /golf-books package directory under its original name of mybookshop.shtml; that will assure that it always gets backed up, and that you can use mbsconvert.php to make a shoptest.shtml copy of it at any time.



Other Page Customization

First, besides all the things already mentioned, do be sure to pay some attention to such matters as the actual page titles and <h1>, <h2>, and so on headings, and all the other usual SEO things: set them as you think they should be for optimum SEO.

Then, there are three other pages that this package adds to your site:

  • amazon-message.shtml
  • book-search.shtml
  • used-books.shtml

Each of those should be, at your convenient leisure, reviewed for both "look and feel" and SEO matters. The book-search.shtml page in particular contains an elaborately detailed explanation of how Amazon searches work; I like it as it is, and so use it on my sites, but you might want something more terse. It is, as always, quite up to you. I just mention it here so nothing gets overlooked.

In the amazon-message.shtml file, make sure that the line down near the very botom, the one that specifies your "front-page" URL, has the correct file title in it--the installer will assume that that title is "mybookshop", but if it isn't, your visitors could get lost here (though it's unlikely many will ever visit the page).

And I emphasize again, whenever uploading any package file modified since the original install, always follow the boxed procedure a ways up this page, else you might run into file-permissions problems.

(And here, for your convenience if you want it, is a link back to the main Install.html docfile.)