Nuværende version fra 6. maj 2024, 03:24

Redirect to:

Showfolio Mod

The latest Mod Manager version of the folio method is called Showfolio Mod. It works with all versions of TNG from TNGv9 onward and is completely compatible with existing folios.

With TNGv10.1.0, Folio is offered as a mod for TNGv10.0. Options can be set with the Mod Manager editor after it is installed. See Showfolio Mod for a better implementation.

The Folio addon works with TNGv9 thru TNGv10.0. It is plug and play and has its own setup and options page.

Introduction

A folio simulates a multipage document handled as if it were a single TNG media object. Opening a folio displays a cover page (optional) and page navigation links to the rest of the pages (images or html/php), all using your website's TNG styling. Folios does not modify any native TNG files or structure the 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.

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 control file that is registered in TNG as a media file. When a 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 of the folder page-by-page.

Note 1: Folio images are displayed in their native size/resolution. For best viewing image widths should not exceed 800-900 pixels. Height can be whatever is needed. Faster load times can be achieved by using 72-100px resolution.

Note 2: TNG templates 8 and 12 have a quirk in which they consider any file named index.php to be the home page and styles them accordingly. This results in dark text on dark backgrounds (unreadable). If your website uses one of these templates, a related mod, tmpl_index_fix, should be installed to allow folio control files to be styled as secondary pages.

Note 3: Folio icons serve as links back to the main media listing to which the folio belongs. TNG media icons are "dead" -- do nothing. If you want to make the TNG icons behave in the same way, download and install the media_icons_mod.

Revisions

Version	Date Released	What's New
version 10.1.0.10	10 Jan 2015	Initial release This will be the only release of Folio as a mod. Please see Showfolio Mod for the next generation of the folio mod for TNGv9.0 thru TNGv10.1 and later.
version 9.0.0.9	25 Dec 2012	adds enhanced page initialization completely rewritten for better code semantics and efficiency large images resize when page width is reduced page tabs rearrange gracefully when page width is reduced replaced skinnytips with tooltips for all but the magnifier
version 9.0.0.8	26 Sep 2012	fixes label in control_file for border color minor processing fix adds tool-tip heading variable 'Magnifier' to English language folio_text.php files
version 9.0.0.7	6 Jun 2012	Fixes missing icon when folio-document is created within a native TNG collection. Changes tool tip for folio-document icon acting as link back to collection. New: Folios V9 Media Icons Mod is available to turn TNG document icons into links back to their respective collection listings so that Folios_v9.0.0.7+ and TNG documents will have the same behavior. To read more click on link above.
version 9.0.0.6	31 May 2012	Properly handles media record if the mediakey is missing. Fixes problem with folio control files failing to find the folio program. Upgrades compatibility with PHP4.
version 9.0.0.5	17 May 2012	Fixes failure to find media keys under some circumstances. Adds new routine to locate folios within the file hierarchy.
version 9.0.0.4	8 May 2012	Sets width for form and centers in on the screen Fixes failure to access a folio remotely via an url Adds option to create an init.php control file for users of Template 8
version 9.0.0.3	6 May 2012	Made compatible with older versions of PHP (v4) that caused it to blow up when creating Folio Control Files.
version 9.0.0.2	5 May 2012	Support for TNG template 8 to use init.php vice index.php as its folio control file. Eliminated errors and warnings when logging out while in the setup or control file pages.
version 9.0.0.1	2 May 2012	Initial release

Get The Correct Download File

Download the appropriate file for your TNG installation.

Folio version 9009 is an add-on and works with TNGv9 and TNGv10.0.3. You must unzip the contents (a folder) and place it into your TNG extensions folder. Use your browser to navigate to extensions/folio and the setup screen will appear.

Folio Mod v10.1.0.10 is required for TNG version 10.1.0 and later. It is a Mod Manager mod. Unzip the download package and place the file and folder in the TNG mods directory. Use Mod Manager to install it and set preferences.

Automated Installation (Mod v10.1.0.10)

Starting with TNGv10.1.0 and folio_v10.1.0.10, folio is a Mod Manager mod. If you have a previous version installed as an add-on, you can delete the folio folder from the TNG extensions directory. None of your existing folio folders, media or media records will be disturbed.

Add the unzipped contents of the download package (1 cfg file and a folder) to your TNG mods directory, then go to your TNG Admin page and select the Mod Manager. Find the Folio mod, open its line, and click on the Install button. After it is installed, open the line again, and click on the Edit Options button to set your preferences.

Manual Installation (Add-on Only)

To install the add-on version of Folio, unzip the download package and place the folder in your TNG extensions folder. Use your browser to navigate to extensions/folio and you will see the setup page. Select and save your options. The necessary files to display your folios will be copied to the TNG root.

Add The Folio Control File (Addon Only)

Use the "Create Folio Control File" program from the Folio Setup page to customize and add a control file to each folio. The control file is named index.php to prevent directory browsing. For users of TNG Template 8 which styles any index.php as a home page (ruining the display), the Control File program will optionally create an init.php which just includes the index.php control file. Either one can be used as the media file when creating a TNG media record, but users of Template 8 must use init.php as the media file name. If you are already using init.php as your control file, you do not need to change anything.

If you prefer to create control files manually, you can copy one from an existing folio and modify it with an editor to suit.

A control file can also be created from scratch with an editor and manually dropped into the folder. Here is an example of a complete folio control file with nearly every local option set.

<?php
/*************************************************************************
FOLIO CONTROL FILE: military/cw24/index.php (Tue, 24 Apr 2012)
*************************************************************************/
# Cheney B. Bisbee Civil War Pension File
$restricted=1;
$showmagnifier=0;
$bordersize=1;
$bordercolor="blue";
$exclude[]=".png";
$exclude[]=".gif";
$useCover=1;
$pdfLink="cheney_bisbee_cwpension.pdf";

// locate folio.php
$relpath = ""; $maxlevels=6;
for( $i=0; $i<$maxlevels; $i++ ) {
    if( file_exists( $relpath . "folio.php" ) )
        include( $relpath . "folio.php" );
    else
        $relpath .= "../";
}
?>

It begins with a comment enclosed between (/*) and (*/) that serves to remind us where the file belongs and when it was created. Lines beginning with a hash mark (#) or double slashes (//) are also comments. Comments are ignored by the server and their only purpose is to provide reminders to the coder.

Option variables are defined for this specific folio. Options do not have to be used -- those which are not defined take on the global values set when Folios V9 was installed, or else not used at all.

Remember, the actual control file is named index.php. If used, an init.php file just includes the index.php control file as a workaround for TNG Template 8.

Using Folio

Folio
Folio
Summary	Multipage images and documents facility
Validation
Mod Updated	{{{mod_last_update}}}
	TNG 10.1.0
	TNG 9.0
Download stats	view statistics
Author(s)	Rick Bisbee
Homepage	Folios (This page)
Mod Support	Rick Bisbee
Contact Developer	Support for Folios
Latest Mod	10.1.0.10
Min TNG V	10.1.0
Max TNG V	10.1
Files modified
Related Mods	Showfolio Mod tmpl_index_fix_v10.1.0.0.zip media_icons_mod_v10.1.0.1.zip
Notes	Handles jpg, gif, png, htm, html, and php.

You can use an existing TNG media type as the basis for a folio, or you can create a new collection (type).

Create A TNG Media Collection

Folios works fine with single pages as well as for multipage documents and you may 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.

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 as well as creating the index.php file.

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

Create a control file named index.php in the folder where you are installing a new folio. You can find an example file in your mods/folio.v10 folder if you want to start from that, or you can copy the file contents below and modify it to suit.


<?php
/***********************************************
FOLIO CONTROL FILE:
************************************************/
# Cheney B. Bisbee Civil War Pension File

// ignore any files in the folder with extensions .html or .htm
$exclude[] = ".htm";
$exclude[] = ".html";

// consider the first file in the folder a coversheet
$useCover=1;

// add link to allow user to download the a pdf verson
$pdfLink ="cbisibee.pdf";

// do not show the magnifier on image pages
$showMagnifier=false;

// Do not modify below this line
// this section finds the folio.php driver
$relpath = ""; $maxlevels=6;
for( $i=0; $i<$maxlevels; $i++ ) {
        if( file_exists( $relpath . "folio.php" ) )
                include( $relpath . "folio.php" );
        else
                $relpath .= "../";
}
?>

Options in the control file only pertain to the current folio. No options are required -- they will all default to the global values set with mod manager or the setup page for the add-on version. The only thing absolutely required is the block of code that finds folio.php.

Here are some options you can (but don't have to) use to customize the current folio:

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.

Special Note for Users of TNG Templates 8 and 12

TNG Templates 8 and 12 treat any file named index.php as a 'home' page and style them accordingly. This results in dark text on a dark background that is virtually unreadable.

There are two ways to fix the problem. The first is to use a companion mod -- tmpl_index_fix -- to correct the behavior of these templates.

Or you can change the name of the Folio's index.php control file to something like 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 folio 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";

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".

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

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.

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.

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 would like to see one of my own implementations of folios, click on Curtis C. Bisbee Civil War Pension File.

Examples

Credits To

Janos Pal Toth at http://valid.tjp.hu/tjpzoom for the magnifier lens
The folks at http://craigsworks.com for the custom tool tips script.
Roger Clist at The Clist Connectionsfor his always helpful design suggestions.

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.

A Bisbee Family History mod developer and TNG Forum user Kazooter's site
The Clist Connections has folios of typewritten pages (jpg scans) and folios created from source documents (html pages)

Forskel mellem versioner af "Folios"