Difference between revisions of "Folios"

From TNG_Wiki
Jump to navigation Jump to search
Line 110: Line 110:
 
:Images must be named in alpha order because that is the order in which they will be displayed. Numbers in the image name are treated (somewhat inconsistently) as alpha characters on most servers.  That means, for instance, that 10 may well sort before 2. To have them treated more like numbers, keep number strings all the same length.  Thus, in the above example, 02 will come before 10, as you would expect. We recommend you avoid using capital letters in file names because Unix servers treat names as case sensitive (that is, c is not the same as C) and they sort differently -- you can eliminate confusion by using all lower case file names that will sort the way you expect them to.
 
:Images must be named in alpha order because that is the order in which they will be displayed. Numbers in the image name are treated (somewhat inconsistently) as alpha characters on most servers.  That means, for instance, that 10 may well sort before 2. To have them treated more like numbers, keep number strings all the same length.  Thus, in the above example, 02 will come before 10, as you would expect. We recommend you avoid using capital letters in file names because Unix servers treat names as case sensitive (that is, c is not the same as C) and they sort differently -- you can eliminate confusion by using all lower case file names that will sort the way you expect them to.
  
=== Create folio subfolder index ===  
+
=== Create Folio Subfolder Index ===  
  
 
Create or place a copy of folio_index.php into your folio's subfolder and pattern it after the folio_index.php you just downloaded. Only two lines need to be customized:  
 
Create or place a copy of folio_index.php into your folio's subfolder and pattern it after the folio_index.php you just downloaded. Only two lines need to be customized:  

Revision as of 19:20, 6 October 2009

Script Under User Acceptance Testing
Check the TNG Forum thread for any changes and to provide feedback.

The following is an Easy Multipage Documents approach copied from Kazooter's post in the TNG Forum on 4 October 2009

I notice a number of people looking for an easy way to display multipage documents in tng. I have attached a script that does that. It implements a media type I call Folios, and defines a folio as any collection of related documents. A folio consists of an abstract or summary page with a link button to "View Original Documents." Clicking on the link displays the first document image (page number 1) in the folio, and provides page navigation buttons for the rest. There is no practical limit on the number of pages a folio may contain. Each document page has the site title and normal site navigation. Closing the documents returns the user to the abstract page.

Folios Concept

Folios are a TNG media collection based on Histories. The Folio page can be used as a summary, transcription or table of contents. When a document page is selected, a processing script creates a sorted list of all the images in the folio, constructs a navigation bar, and displays the requested document. TNG media records do not need to be created for page images. A page is added to a folio by dropping its image into the folder. It is deleted by removing it.

Folio Cover Page

An folio cover page is desirable for a number of reasons:

  • It organizes the underlying documents;
  • A transcription may be included here for difficult to read documents;
  • It can contain a table of contents with links to each document page; and
  • The cover page may be all users need to see, especially if they are on a slow connection.

Possible uses for a folio might be a Civil War Pension file, a probate file, land records, or a collection of personal records pertaining to a single individual. The latter is useful because only one Folio needs to be linked to an individual, rather than multiple individual documents. It is even more useful because folio pages (images) can be added by simply dropping them into a folder, or removed by deleting them from the folder.

Here's how to implement Folios.

Two script files are required:

  • docview.php which goes into the TNG root directory to manage page images, and
  • folio_index.php, a small file in each folio to initialize docview.php.

Revisions

4 Oct 2009 - Original script release 6 Oct 2009 - Revised scripts

Based on early feedback, we have revised the script files and instructions for installation.

What's new:

  • Corrected minor errors in the script.
  • Improved documentation inside the script.
  • Revised installation instructions.
  • Renamed index.php to folio_index.php to allow Mod Manager to install and manage it.
  • Added a folios_body_text_template.html to assist in creating text for the abstract.
  • Added a folios_abstract_example.html.
  • It is no longer necessary to deal with icon files (unless you insist on it).
  • Added Prev - Next buttons to the bottom of the image pages.

Installation

Automated

Config file for the Mod Manager will be provided.

Manual

Get the Files

Download the attached files in the TNG Forum Entry:

  • docview.php.txt -- folios display script
  • folios_index.php.txt -- used as a template to create the index.php file in each folios/subfolder
  • body_text_template.html.txt -- used as a template to be copied to your media record Body Text field
  • abstract_example.html.txt -- an example of a Folios media record Body Text field

Remove the .txt extension.

Place docview.php in the TNG root directory. You will need to create your own index.php file in each subfolder in the media collection where you want to use folios using the folios_index.php file as a template. The other download files are intended to serve as templates, so just hold on to them for the moment.

Add style definitions

Note that the text for the folio cover page is enclosed in a DIV tag that has a unique class name folio so you can style it. Although the default style applied by your website will probably be fine as is, if you want more control over the look of your text and background, you can add a style definition for the folio class to mytngstyle.css. Here is an example of folio styles you can paste into your mytngstyle.css file, then modify it to taste:

.folio { /* cover page styling */
    padding: 3em;
    background-color: #fffff0;
    border-width: 1px;
    border-style: solid;
    border-color: #aaaaaa;
}
.folio p { /* paragraph styling */
    font-size: 14px;
}
.docimage { /* document image styling */
	margin-top: 5px;
	border: 1px solid #aaa; 
}

If you have created other forms of Folios (see Create Folio Subfolder Index below), and you want to style them differently than Folios, replace the folio class in the DIV that encloses your text in the cover page with some other class name that you can style in mytngstyle.css in a similar manner to folio.

Folios Implementation

Create the Media Collection

In TNG Admin, create a new media collection where

  1. CollectionID = folios -- Note that if you use multiple languages, the collectionID is used to find the $text variable so if you use Folios then your variable in cust_text.php should be $text[Folios]
  2. Display Title = folios -- Note that if you do not use multiple languages, you may want to Upper case the Display Title as Folios
  3. Folder Name = folios
  4. Click the Make Folder button
  5. Icon File = tng_doc.gif
  6. Same setup as = Histories.

Folios collection.jpg

Set Up the Folder Structure

Create a subfolder in folios or other media collection folder with which you want to use the multi-page folios scripts, that will contain all the page images for folio.

Images must be named in alpha order because that is the order in which they will be displayed. Numbers in the image name are treated (somewhat inconsistently) as alpha characters on most servers. That means, for instance, that 10 may well sort before 2. To have them treated more like numbers, keep number strings all the same length. Thus, in the above example, 02 will come before 10, as you would expect. We recommend you avoid using capital letters in file names because Unix servers treat names as case sensitive (that is, c is not the same as C) and they sort differently -- you can eliminate confusion by using all lower case file names that will sort the way you expect them to.

Create Folio Subfolder Index

Create or place a copy of folio_index.php into your folio's subfolder and pattern it after the folio_index.php you just downloaded. Only two lines need to be customized:

  • the $returnID value will need to be set to the mediaID number for the new folio you will create below (I'll remind you later); and
  • the $docTitle must be assigned the string that will be displayed at the top of the browser when viewing the images.

Optionally, two other values may be added to folio_index.php. If, for some reason, you are creating a folio-type collection, but need to name it something other than Folios (like Military Records), and want to use a different icon, uncomment the following two lines in folio_index.php and edit in missing values indicated:

$icon="path_to_your_icon/icon_file_name"; $titlestr="My_Custom_Doc_Type";

Create a Folio

Create your first folio in TNG Admin -> Media -> Add New, where Media File->Collection = Folios. Create the text for your abstract using the folio_body_text_template.html. When you are satisfied with the content, copy and paste the text into Body Text of the media record you are creating.

Important! The first and last lines of the pasted text provide links/buttons to "View Original Documents." These must be pointed to the index.php file in your new folio subfolder (e.g., href="folios/h47/index.php").

If the abstract content is very short and does not fill the page, feel free to delete the last button (last line in the folio_text_template file. If your abstract is a table of contents, with each item linked to an underlying document, it might make sense to delete both buttons (first and last lines).

Finally, note that the text of the abstract is enclosed in a DIV tag that has a unique class name to allow the abstract to be styled in your mytngstyle.css.

Note that if the Body Text abstract is a very short one, you may want to delete either the top or bottom View Original Documents button

	<p><a href="folios/subfolder/folios.php" target="_self" class="snlink">View Original Documents</a></p>

either before the <div> or after the </div> in the Body Text of the abstract media record.

Update your index.php

While still on the Folio abstract media record creation page,

  • Add a title in the Media Information section. You should use this title information in the $docTitle in the index.php file.
  • Link the folio persons as appropriate and save it. Don't forget to save it.
  • Note the mediaID number, returns a message such as "Changes to item 348 were successfully saved."
the item nnn is the value that you need to enter as the $returnID= value in the your index.php for that folio subfolder.

Copy folio media

Copy all the images you want to display in a folio to your media collection subfolder.

Note that

  • you do not need to create TNG media records for these images.
  • the images will be displayed in Unix collating sequence so Upper Case will be displayed before Lower Case and numbers will be displayed xxx
  • the collation sequence will be different on a Windows WampServer testing environment.

Test the Result

Obviously, there is no magic in the name of the collection (Folios), folder names, class names, or icon file. Change them as you will.

If you want to see my implementation of folios, go to my A Bisbee Family History website home page, click on the Media drop down menu and select Folios or Military Records.

Disclaimer

There is no warranty. Use the script at your own risk. I have not tested it in all the TNG template styles, so it may need to be modified to suit your environment.

I hope someone will find it as useful as I have.

Site Using

A Bisbee Family History TNG Forum user Kazooter's site