Folios - old

From TNG_Wiki
Jump to: navigation, search
Caution Please note that this version is for TNG V8 only. If you are using TNG V9 please see Folios V9. Caution


Folios Add-on for TNG V8
Summary Multipage images and documents facility
Validation {{{mod_validation}}}
Mod Updated {{{mod_last_update}}}
Download link folio_v304.zip
Download stats {{{download_stats}}}
Author(s) Rick Bisbee
Homepage Folios (This page)
Mod Support TNG Forums
Contact Developer Support for Folios
Latest Mod 3.04
Min TNG V 8.0 (not tested in earlier versions, but probably compatible)
Max TNG V 8.1.2
Files modified
None
Related Mods
None
Notes
Handles jpg, gif, png, htm, html, and php. Tested in IE8/9 and FF3/4.


Introduction

Create multipage documents as TNG media. Folios first appeared in Kazooter's post on the TNG Forum on 4 October 2009. Please check the TNG Forum thread for any updates and to provide feedback.


Folios is a method for gathering and displaying related media (images and/or html content files) in TNG as if they were a single, multipage document. Opening a folio displays a cover page (optional) and page navigation links to the rest of the images, all using your website's TNG styling. Folios does not modify any native TNG files or database.

Possible uses for a folio might include Civil War pension files, probate files, land records, diaries, letters, or a collection of personal records pertaining to a single individual or family. Only one folio needs to be linked to an individual or family, rather than creating each page as a TNG document and linking them all separately.

The latest version (3.04) is also available for download from the TNG Forum.

Folios Concept

Folios is a method, not a document type. A folio folder contains page files (jpg, gif, png, htm, html, and/or php) named so they will alpha-sort in the order you want them displayed. Page files are added or deleted simply by adding or deleting them from the folder. In addition to the page files, each folder contains an index.php file that is called by TNG when the folio is selected for viewing. Index.php sets some options specific to that individual folio, then grabs folio.php from the TNG root directory to display the contents.

See Creating images from a PDF for one approach on generating the files for a folio folder.

Revisions

Version Date Released What's New
version 3.04 24 Oct 2011
version 3.03 30 Aug 2011
  • adds capability to restrict access to registered users only.
version 3.02 17 June 2011
  • fixes a bug in folio.php that generates a Page Not Found Error when the user clicks on the 'Go to page' button.
version 3.01 1 June 2011
  • corrects problem with links in TNG Websites having more than one family tree.
Version 3.00 25 May 2011
  • no longer need to deal with, or even know about, mediaID numbers
  • adds global preferences initialization file
  • global preferences may be overridden in the folio index.php file
  • user can set magnifier and tool tip styles
  • redesigned page heading
  • all TNG links to folio are shown at bottom of each page
Version 2.08 12 May 2011
  • updates the magnifier to work with Firefox 4
  • corrects a minor problem in folios magnifier implementation
Version 2.0 16 Jan 2011
  • docview.php has been replaced by folio.php
  • easier to install and maintain
  • makes use of the TNG Database for document icons, titles and links
  • supports other languages
  • optional magnifier lens for hard-to-read handwritten documents
  • styled tool tips with language support
Version 1.2 18 Feb 2010
  • adds htm, html and php page file types to folios
  • restricts file types allowed within each folio
  • customized page subheadings
  • improved internal documentation
Version 1.0 10 Oct 2009
  • Corrected minor errors in the script.
  • Improved documentation inside the script.
  • Revised installation instructions.
  • Changed the download name of index.php to folio_index_template.php and added user customizations.
  • Added a folio_cover_template.html to assist in creating text for the cover page.
  • Added a folio_cover_example.html.
  • Added Prev - Next buttons to the bottom of the image pages.
  • Removed the requirement to deal with icon files (unless you insist on it).
Original 4 Oct 2009 Original version of script

Installation—Automated

Config file for the Mod Manager is not currently available.

Updating

If you are updating from folios v3.02 to v3.03:

  • download folios_v303.zip and unpack it in a convenient location.
  • replace your folio.php file in the TNG root directory.
  • if you don't want to restrict any of your folios, you are finished.
  • if you want to restrict all folios, edit your existing folio.ini.php file and add the following line: restrict=true and you are done.
  • if you want to restrict a few selected folios, edit each of their index.php (init.php) files and add the following line: $restrict=true; (note the semicolon at the end).

Remember, whatever is set in the folio.ini.php initialization file can be overridden in the individual index.php (init.php) files.

Installation—Manual

Get the Files

Download the latest folio_v3.xx.zip package from the TNG Forumand unpack the following files in a temporary location:

folio.php -- document handling script for folios.
folio.ini.php -- global preferences file in classical 'ini' format
init.php -- custom initialization for the folio
readme.txt -- instructions for installing folios
tjpzoom folder -- contains script for the magnifier and tool tips

With files in hand do the following:

  • copy tjpzoom folder to the tng root directory overwriting previous versions if necesary (do not rename it)
  • place folio.php and folio.ini.php in the TNG root directory.
  • put init.php aside for the moment--We will use it later.

Set Global Preferences

Open folio.ini.php in an editor such as Notepad or Editpad and set the variable options according to your website design and your own needs. Following table explains how to set them. Note that in 'ini' format no semicolon (;) is necessary at the end of statements and that there is no need to put string values in quotes.

Section / Options Description
[folios] Folios global preferences
restricted=false True if you want access to ALL of your folios restricted to registered users.
showDropDownMenus=true True if your website pages use TNG drop down menus.
showCoreIcons=true True if your website pages uses the small, TNG iconic menu.
border=0 Sets border width for all folio images.
bordercolor=#aaa Only in effect if border is set greater than 0.
[tjpzoom] Magnifier global options
showMagnifier=true Appears on folio image pages.
tjpzoom_config=square Set magnifier corners square or round.
tjpwidth=280 Starting width of magnifier.
tjpheight=220 Starting height of magnifier.
[qTip] Tooltips global options
tipborder=1px solid #aaa style of border for tooltips. Set to 0px for no border.
tipbackground-#eee Background color of tooltip.
tipfontsize=12px Tooltip font size in pixels.
tipfontstyle=italic Either italic or normal.
tiptextcolor=black Tooltip text color. Can be expressed as teal or #008080.

Create A TNG Media Collection

Folios works fine with single pages as well as for multipage documents and you will probably want to create a new collection dedicated to this style. On the TNG Admin page, click on 'Media' and then click the Add Collection button. Cm005.jpg

Cm001.jpg

You can name your new collection anything you want; it does not have to be 'Folios.'

  • Collection ID: Should should be a short, descriptive word and not capitalized.
  • Display Title: Should be Capitalized. TNG looks for a Display Title definition in your current language files. If it finds one, it will ignore the Title you enter here. You can define the Display Title in cust_text.php files for each language you use. You must use the collectionID as the index into the $text array, for example, $text['clippings']="Stories", where 'clippings' is the name you've given to your collection. Do not use a variable name such as $text[clippings] in the Display Title field.
  • Folder Name: the folder name should be same as the collection ID. It is best not to capitalize a folder name because Unix names are case-sensitive and it could introduce a bug.
  • If you have not already created the media folder, click the Make Folder button.
  • Icon file: you can choose an existing TNG icon such as tng_doc.gif, or you can use any other Icon you choose. Be sure to specify its full path relative to the website's root directory.
  • Thumbnail File: I think in theory the Thumbnail is used in listings. If you do not want TNG to create a thumbnail from the original document (in this case it does not make much sense), provide your own standard thumbnail. At the moment it doesn't seem to do much of anything.
  • Same setup as: use Histories or Documents.

Organize the Collection

Refer to the example chart below and create subfolders inside the collection to organize your folios. I like to create folders on my desktop computer, then upload them to the website using FileZilla. In this example, folios are organized by family and named according a family member's given name. Many other organizing schemes are possible. Each folio folder will contain page files and an index.php file that will be called when the folio is selected from the various TNG menu listings. When you create a folder you will add all the page files and a copy of init.php that has been renamed to index.php.

Cm006.jpg

Note that while each folio folder has its own index.php file, the parent collection and organizing subdirectories do not not. On some servers, this could mean that a visitor browsing to a directory on your website that does not contain an index.html or index.php file may see the directory contents. To stop this happening, follow instructions given in Prevent Directory Listing. Keeping with our example, you could create an index.php in each of your organizing directories (clippings, Smith, Jones and Brown) which contain just the following code to redirect a visitor to a listing of all the 'clippings':

<?php
header('Location: /browsemedia.php?mediatypeID=clippings');
?>

Add Content

Copy all the page files for your folio to its subdirectory underneath the appropriate media collection. Page files must be named in alpha order because that is the order in which they will be displayed. Numbers in the file 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 and they will sort the way you expect them to. If you wish to have a cover page, name it so it will display first, then edit index.php to have it use the first page as a cover. You will also need to give it a label to display on its tab, something like 'Cover' or 'Summary.'

Note that

  • folio page file types can be mixed (for instance, jpg and html).
  • the pages will be displayed in Unix collating sequence so Upper Case will be displayed before Lower Case and numbers will be treated as alpha characters.
  • the collation sequence will be different on a Windows WampServer testing environment.

Add The Index.php

Add a copy of init.php from your download package and rename it index.php. The file will work fine with no changes, but if you want to do some customizing, open it in a text editor such as Notepad or Editpad. The file is self-documenting, but you can delete all the comments to make it smaller.

Other areas where you can (but don't have to) customize:

User Options Explanation
$exclude[] = ".jpg";

$exclude[] = ".png";
$exclude[] = ".gif";
$exclude[] = ".htm";
$exclude[] = ".html";
$exclude[] = ".php";

Exclude certain file types from being included as a document page in this folio. The index.php is excluded automatically. No files (except the index.php) are excluded by default.
$useCover=TRUE;

$buttonLabel="cover";

Use a cover page for the folio and provide a button label for it.

If $buttonLabel can be found in the cust_text.php file in your chosen language as an index into the $text array (for example, $text['cover']="Contents"), the value provided there ("Contents") will be used. If not, the label itself will be used ("cover). This allows you to "internationalize" it in as many languages as you support.

$pdfLink ="filename.pdf"; Adds root-relative PDF download links to top and bottom of folio pages
Global Overrides
$restrict=true; Restrict folio access to registered users -- redirect the rest to TNG login page.
$border=0;

$bordercolor="#aaa";

Select a border for image pages in this folio.
$showMagnifier=true; If you've turned off the magnifier globally in folio.ini.php, you can turn it on here, but just for this folio.
$tjpzoom_config="round"; Sets the magnifier corners "round" or "square";
$tjpwidth;

$tjpheight;

Sets the start up width and height of the magnifier.
$tipborder="1px solid #aaa"; Sets tooltip border style
$tipbackground="#eee"; Sets tooltip background color
$tipfontsize="12px"; Sets tooltip font size in pixels
$tipfontstyle="italic"; "italic" or "normal"
$tiptextcolor="black"; Color of tool tip text

Note that all value statements in index.php must end with a semicolon (;). String values must be enclosed in quotes.

In version 3 of folio.php, you no longer have to find the MediaID number for your multipage document, since Folio is now able to find it in the TNG Database. It also gets the icon, title, links and collection type you specified when you created the document. The Description from the record is placed beneath the Title as notes. If you want to change these, you will need to do it in the media record.

Special Note for TNG Template 8

TNG Template 8 treats any file named index.php as a 'home' page and styles it uniquely. Unfortunately this style is not compatible with folios, so the initialization files must be named something else: we suggest init.php. However this will leave your folders vulnerable to directory browsing. One way to prevent that is to add a file named 'index.htm' to each folder that redirects a browser to your init.php:

<html>
<head>
<meta http-equiv="Refresh" content="0; url=init.php" />
</head>
<body>
<p>Please follow <a href="init.php">this link</a>.</p>
</body>
</html>

The code in the <body> is intended for browsers that do not honor the redirect. You should style it to suit.

Next, exclude .htm file types in init.php. Your .html file types will still be included in the folio if you need them. See Prevent Directory Listing for a more detailed discussion of the issue.

Include PDF Download Link

If the folio is also available as a PDF download, you can add links to the top and bottom of each page. To do so, define $pdfLink = "filepath" in the folio's index.php file, substituting "filepath" for the path to the file from the TNG root (root-relative.) For example:

$pdfLink = "clippings/pdf/myfile.pdf";

If you want to protect your PDF files so they cannot be accessed by public users or downloaded with a simple URL, you can place them on your server above your website root (usually public_html or www) where they are not accessible by the public. Then use pdffetch.php (included in v3.04) to download them. Here is how to do it.

  • Create a folder above your website root to hold your PDF files
  • Upload your PDF files to the new folder
  • Edit your customconfig.php file to add the path to your new PDF folder: $pdfpath = "filepath", substituting "filepath" with the actual 'server' path to your folder. For example:
/home4/bisbee/pdf/
  • Place pdffetch.php it in your TNG root directory.
  • Edit the folio's index.php file to add: $pdfLink = "pdffetch.php?pdf=filename.pdf";

If users are not logged in, pdffetch.php will take them to the login page. Registered users who click on the link will be given a choice to Save or Open the PDF file, but will not see a download path and will not be able to access it directly.

Create a TNG Cover Page (Optional)

A cover page can be used:

  • to present a summary of the folio;
  • to provide space for transcribing difficult to read documents;
  • to contain links to related non-folio pages or downloadable files (e.g. pdf, zip); and
  • for a table of contents with links to individual document pages.

If you choose to use a cover page you should create an HTML file named to sort first among the other page files and containing only text formatting tags—do not use <html>, <head> or <body> tags.

Note that it is good practice to enclose your formatted text in DIV tags and give them a class name so you will have the option to style them if you wish.

<div class="folio">
<p>Paragraph 1 from the article goes here</p>
<p>Paragraph 2 from the article goes here</p>
</div>

Add a Folio to TNG

This is the payoff, the final step, where we make an actual TNG Media record for the folio we've assembled under our new collection. Do this from the TNG Admin page by clicking on "Media".

Cm007.jpg

Since you have not entered the folio yet, the search list will return nothing.
Next, click on the Add New tab.

Cm008.jpg

Choose a thumbnail to represent the folio-type. If you place a thumbnail in the collection directory, you can use it for all folios in the collection.

Cm009.jpg

Continue filling out the form with the Title and Description. The Title will be used when your folio is displayed. The Description will appear as notes underneath the Title. When you have completed this portion, click "Save and continue...".

On the next screen you can associate this folio with a Person, Family, Source, Repository or Place. If associated with a person, you may further refine the association to an event in the person's life such as Death or Burial.

Cm010.jpg

Once a link has been added to the list of links associated with this media, you can edit it by clicking on the leftmost icon and associate it with an event in the person's life. In the above example, I have linked the folio with Robert Smith's death and it will show up on his page as a link under 'Death'.

When you are finished entering all the data in the record, you MUST click on Save to add it to the database. Your new multipage document is finished except for any additional styling you may wish to add.

Add Style Definitions (Optional)

Any html text, for instance for a cover page, should be enclosed in a DIV tag that has a unique class name like folio to allow you to style it whenever you choose.. 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 one example of folio styling you can paste into mytngstyle.css if you wish to experiment with it.

.folio { /* text page styling */
   padding: 3em;
   background-color: #fffff0;
   border-width: 1px;
   border-style: solid;
   border-color: #aaa;
}
.folio p { /* paragraph styling */
   font-size: 14px;
}

.folio li { /* list item styling */
   font-size: 14px;
}

If you have created other forms of folios (see Create A TNG Media Collection), and you want them styled differently than folios, replace the folio class in the DIV that encloses your text with some other class name that you can separately style in mytngstyle.css in a similar manner to folio.

Notes

Obviously, there is no magic in the names of collections, folders, classes, or icons. Change them as you will.

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

Examples

See also the Folios - Examples page.

Credits To

Disclaimer

There is no warranty. Use the script at your own risk. It has been tested in all the TNG template styles without any particular problems.

Sites Using

The following sites contain folios which are viewable without login.