Difference between revisions of "Showfolio Mod"

From TNG_Wiki
Jump to: navigation, search
(Sites Using)
Line 266: Line 266:
 
The following sites have installed Showfolio Mod and contain folios which are viewable without login.
 
The following sites have installed Showfolio Mod and contain folios which are viewable without login.
 
* [http://www.bisbeefamily.com A Bisbee Family History] mod developer and TNG Forum user Kazooter's site
 
* [http://www.bisbeefamily.com A Bisbee Family History] mod developer and TNG Forum user Kazooter's site
 +
* [http://mfo.me.uk Mitchell Families Online] Used this mod from day 1. Just gets better and better!
  
 
[[Category:Media]]
 
[[Category:Media]]

Revision as of 08:43, 13 August 2015

Ambox notice.png This Mod works with all versions of TNGv9 and current versions of TNGv10. If you experience conflicts with other mods, please notify the developer.
TNG 10.0
TNG 9.0


Showfolio mod
Summary Integrates with TNG to show folios
Validation n/a
Mod Updated {{{mod_last_update}}}
Download link
Download stats view statistics
Author(s) Rick Bisbee
Homepage n/a
Mod Support n/a
Contact Developer Support for Showfolio Mod
Latest Mod 10.1.1.7
Min TNG V 8.1.1
Max TNG V 10.1.1
Files modified
Related Mods
Notes


Introduction

Showfolio Mod is a major new revision of the previous Folios mod and addons and is backward compatible with existing folio structures. It installs showfolio.php in the TNG root folder and it works the same for folios as TNG's showmedia.php works for other media.

The main difference between Showfolio and previous versions is in the control file. Showfolio Mod now prefers the control file to be named folio.php to make its purpose crystal clear in the TNG database, and to avoid file name clashes with certain TNG templates; however, it will still accept existing index.php or init.php as control file names. The control file no longer requires path information to the TNG root, or any other information for that matter. Unless there is a need to change global settings for an individual folio, the control file may be empty or may contain descriptive comments to remind the administrator which folio it controls.

A utility named showfolio_update.php is included and can be run from the TNG root directory to help you upgrade control files should you choose to do so.

Compatibility

Mod Tested With TNG Versions
Ver 812 813 900 910 922 1000 1001 1002 1003 1010 1011 1012
10.1.1.7

*green: compatible   red: not compatible   white: not tested

What is a Folio?

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

Expanding the Concept

Folio

A folio is a method, not a document type. A single folder contains all of its 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 a folio.php (index.php or init.php in older versions) control file that is registered in TNG as a media file. When requested for viewing, showfolio.php opens it, sets some options specific to that individual folio, then displays the contents of the folder page-by-page.

Note 1: Folio images are displayed in their uploaded sizes/resolutions. 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: 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.

Compatibility with Existing Folios

If you are already invested in folios, we recommend you first install and run this on a test site. You should be able to run your existing folios as they are, with no changes to them. If you wish, you can convert your existing folios to the Showfolio Mod standard (see #Converting Folios to Showfolio). The mod developer has been running the showfolio mod on his production site (TNGv10.1.1) and on several test sites going back to TNGv9.1.0 with no particular problems.

Disclaimer: As a practical matter Showfolio Mod has not been run on every single version of TNG since TNGv9.0. We analyzed those we were not able to test directly and find no reason to believe Showfolio Mod is not %100 compatible with all of them. If you experience any problems in this regard, please let us know.

Protecting PDF Files

We provide a PDF fetch capability to grab and download PDF files stored in a private area of your website located above the public_html. This prevents URL downloading of files restricted to members only. It is triggered from the control file with a new parameter: $pdffetch = "filename.pdf"; You must place the server path to your private pdf folder in your customconfig.php file to use it.

Revisions

Version Date Released Showfolio — What's New
version 10.1.1.7
12 Aug 2015
  • excluded file types not working -- fixed
version 10.1.1.6
12 Aug 2015
  • fixes bug in cfg file that may have prevented init.php files being recognized
version 10.1.1.5
4 Aug 2015
  • Resolves image paths in html, php or in mixed html-php page files
  • handles errors with missing or bad query string
  • fixes bug that caused cover page labels to be lower cased
version 10.1.1.4
29 Ju1 2015
  • Compatible with all versions of TNG from 8.1.2 to present
version 10.1.1.3
1 Ju1 2015
  • adds German language support
  • standardizes versioning
version 9-10.1.1.2
1 Ju1 2015
  • Fixes missing PDF link if folio only consists of one page
version 9-10.1.1.1
30 Jun 2015
  • Initial release for TNGv9 and TNGv10

Installing Showfolio

If you are using an earlier version of the Folios add-on, go to its setup page and uninstall it. Then go to the TNG root folder and remove pdffetch.php if it exists.

If you have been using the previous Folio Mod, go to Mod Manager in the TNG Admin area and uninstall it.

Showfolio is a TNG Mod Manager mod. Download the correct version from this page according to the version of TNG you are using. Unzip the package and place the file and folder in your TNG 'mods directory, then use Mod Manager to install it. Set your preferences with the mod editor as shown in the following graphic.

Sf003.jpg

Finally, add the private pdf server path to your customconfig.php, for example:

$pdfpath="/home6/smith/pdf/";

Your folios should continue to display as before. If not, contact the mod developer for help.

Uninstalling Showfolio Mod

You can completely uninstall the mod from your Mod Manager. Removing the mod does not change database records for any folios you have created, but the material in the folio folders will not be accessible as media via TNG.

Uninstalling Showfolio Mod in earlier versions of TNG (v9) may show a missing file error, even though the mod has been completely uninstalled. The error is caused by a defect in earlier versions of Mod Manager and is no cause for concern.

Converting Folios to Showfolio

While Showfolio will continue to work with the old Folio control files, you are encouraged to modify them to the new standard.

A utility to assist you in upgrading your control files is provided and can be found in the TNG root after the mod is installed. You can access it using your TNG domain's url as follows:
www.mydomain.com/showfolio_upgrade.php 
(replace ''mydomain.com'' with your own)

Sf001.jpg


The Showfolio upgrade utility searches your database for a list of folio control files and displays them one at a time as above. The upper window displays the contents of the current control file. The second window recommends the new content. It is editable and you may modify and save it as as you choose. Normally it can be saved without further editing. After Updating or Skipping the current folio, the next one on the list is displayed until they've all been viewed/converted.

In the example above, the border specs are the same as the global defaults (unless you've changed them with the mod editor) and can be deleted. The $mediaID is from an older version of folios and is completely unnecessary. In short, this control file can be empty, or just contain comments.

If you click the Upgrade button, the control file will be converted and the next control file will be displayed for edit. When the file is converted a backup is created in case you want to revert back to the old setup using showfolio_restore.php.

If you click on the Skip button, the control file will be skipped and not shown again during the current session. This might be handy if a file is wrongly thought to be a control file.

Quit exits the upgrade utility.

Create a New Folio

Page Files

A folio consists of one or more page files. Page files can be of the following types: .jpg, .gif, .png, .htm, .html, or .php.

Page files can be individual images or formatted content that may contain images. There is a restriction on web content files -- they must not contain header, header content or body tags. This is because the folio "wrapper" provides all that; otherwise an error will be generated.

All page files are contained within a single folder that also contains a control file named folio.php, the content of which is explained below. For now, just understand that folio.php will be registered in TNG as a media file.

Add Control File

With Showfolio, the only purpose of a control file -- named folio.php in the folios -- is to provide options that are unique to this folio. If there are no unique options for this folio, if you don't need to override any global options, the control file can be empty, or it can contain comments (each line preceded with a double slash)) for your own information.

Following is an example control file and a list of local options/overrides you might want to consider for a given folio:

<?php
/***********************************************
FOLIO CONTROL FILE (folio.php):
************************************************/
# 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 download pdf from the site's private area
$pdffetch ="cbisibee.pdf";

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

?>

Set Local Options

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. A control file must be present, but it can be empty if no customizations are required.

Here are some options you can (but don't have to) use in the control file 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 control file is excluded automatically. No allowed files (except the control file) are excluded by default.
$useCover=1;

$buttonLabel="cover";

Treat the first page as a cover page for the folio and provide a button label for it. You might want a cover page, for example, if you want to summarize the contents of the folio.

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"; Places PDF download links at top and bottom of folio pages and downloads the file from the folio folder.
$pdffetch = "filename.pdf"; Adds PDF download links to top and bottom of folio pages. Fetches PDF files from a private area of the website so they cannot be downloaded using a browser url. Server path to files must be defined in customconfig.php. For example, $pdfpath="/home6/subserv2/pdf/";
Global Overrides
$restrict=true; Restrict folio access to registered users -- redirect the rest to TNG login page.
$bordersize=1;

$bordercolor="#aaa";

Select a border for image pages in this folio.
$showMagnifier=1; If you've turned off the magnifier globally with the mod preference editor, you can turn it on here, but just for this folio.

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

Registering a Folio As TNG Media

You could create a folio of images (and control file) and place the folder in your TNG Documents or Histories collection. Then go to your TNG Admin page and select Media/Documents or Media/Histories to register it by drilling down into the collection and folio and selecting its folio.php as the media file.

Chances are good you will want to create your own media collections at some point, for example, military, newsletters, obituaries, or clippings and base them either on TNG Documents or Histories to better manage your different types of folios.

Following is a diagrammatic example of how you might organize a collection of folders.

Sf002.jpg

Please consult your TNG documentation for instructions on creating a TNG media collection.

Folio Screenshot

Example of a working folio.

Sf004.jpg

Note that this particular folio has a Cover plus seven pages and a PDF download button. In admin mode (shown) there is a link (icon) to edit the media in TNG. The cover page is simple html that includes an inserted graphic, but can be a more elaborate PHP script or an image.

Obligatory Disclaimer

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

Sites Using

The following sites have installed Showfolio Mod and contain folios which are viewable without login.