Showfolio Mod
|
Downloads of Showfolio Mod are restricted to TNG Wiki logged in users. This is a different account from that of the TNG Forum. If you do not have a user account on the TNG Wiki use the Request Account link to request a user account. |
|
|
If you have trouble downloading with Google Chrome, Vivaldi, Brave or other Chromium based browser, try using a right-click and select Open in new Window, then F5, or use another browser such as Firefox |
|
|
This Mod works with all versions of TNGv12 through current versions of TNGv15. Earlier versions require you do some manual configuration of the mod options (see article below.) |
|
| Showfolio mod | ||||||
|---|---|---|---|---|---|---|
| Summary | Integrates with TNG to show folios | |||||
| Validation | n/a | |||||
| Mod Updated | 5 Dec 2024 see Revision History | |||||
| Download link | version 15.0.1.42.zip
version 14.0.5.43.zip
version 13.0.0.37.zip
| |||||
| Download stats | view statistics | |||||
| Author(s) | Rick Bisbee | |||||
| Homepage | A Bisbee Family History | |||||
| Mod Support | Support for Showfolio_Mod | |||||
| Contact Developer | As above | |||||
| Latest Mod | 15.0.1.2 | |||||
| Min TNG V | 12.0 | |||||
| Max TNG V | 15+ | |||||
| Files modified | globallib.php, genlib.php, admin_media.php, customconfig.php | |||||
| Related Mods | ||||||
| Notes | ||||||
What is a Folio?
- A folio is a folder of images and page files in which the folder itself is registered in TNG as a document. Media within the folder are organized and displayed book-style and do not need to be individually registered in the TNG database, a real benefit if there are hundreds of them.
- A folio can be created in any of TNG's media collections and will list as part of that collection.
- A folio simulates a multipage document (like a book) 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, all using your website's TNG styling. Pages may be added or removed by adding or removing page files from the folio folder.
- Page tabs can be labeled and mapped to synchronize with actual pages being displayed. Navigation allows you to jump to any tab you wish, so if the document has an index and you've mapped the pages, you can jump to any page in the index.
- A folio can contain and display single page documents. A US census image from Ancestry is a common example. With a single page there are no page tabs, of course, but you can closely examine the document using the zoom-pan capability.
- Possible uses for a folio might include Old Books and Manuscripts, 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.
- Folio pages may be HTM, HTML or PHP files that produce a page of output, or they may be image files, or a mixture of both. You can create an html document containing images as a page if you choose. Each file will become a 'page' of the Folio and it will display according to the alpha order of the file names.
- So to create a folio from a book, for example, you might scan pages from the book as JPG images into a folder inside one of the TNG media 'collections', and name the pages something like p0001.jpg, p0002.jpg, p0003.jpg, etc. Using the provided tools, you can register the folder in TNG and that's it -- you have a Folio, a 'document' that can be paged and viewed by visitors, and easily maintained by admins.
- One drawback is that folios cannot be included in GEDCOM downloads and will probably not be compatible with your desktop genealogy program, unless your desktop program is TNG. If you are using TNG as your desktop genealogy program, you can easily capture the whole site (including folios) to DVD for archiving.
Very important note! Immediately after installing this mod you must press the button - Install Folios Table - in the mod listing. Failure to do this will cause errors when trying to run the mod.
Expanding the Concept
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 may contain a folio.php control file (old style) 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.
In the newer style (TNG 14 and 15), the folio.php file configurations are copied to an edit form which is saved to a new tng_folios table. After that, Folios uses the table to manage individual folio configurations. The folio.php control file remains in the folder but is no longer used.
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.
Large documents
This mod's author and others use Showfolio to publish some very large books on several live websites. One of these books has over 2000 pages, but because of Showfolio's nature, all individual pages display quickly. A side benefit as compared with PDF books, is they cannot be downloaded in their entirety. If someone wants to download or screen-shoot 2000 pages one page at a time, we can't really stop them, but this is the next best thing. Folios can be individually set to display to the public or for logged in members only.
Each folio can have an option to download a PDF file containing the contents of the folio. For example, a newsletter-folio whose pages consist of individual JPG files, can contain a link to download a PDF version of the newsletter if you choose to provide one.
The Showfolios Mod includes a utility that allows for storage of PDF documents in the private area of the site above the document root that is not accessible to a browser, but will download them upon request from an authorized visitor.
With large publications, the tab map is very handy for synchronizing tab labels with page file titles or numbers. As explained below, a tab map provides a concise way to create page tabs with individual labels or ranges of page numbers, either plain or prefixed, as might be the case with an Index section where each page might start with an "i" (i3, i4, i5, etc.) The map for that would be something like: "Cover, [1-109], Index, i[1-16]".
New Features
Starting with versions 14.0.5.40 and 15.0.1.41, Showfolio is more tightly integrated into TNG. It includes built-in administrative functions to create and update folios. It Removes the requirement to have a folio.php control file in each folio folder and instead uses a new TNG table to keep the custom configurations. That said, it is backward compatible with all your current folios. You can convert them to using the new table with a click of the mouse, or you can keep them as they are (using folio.php for their configuration); either way they will display as they always have. Keep in mind though, any changes you make to an existing folio using a folio.php control file will cause it to be converted to using the new tng_folios table. The folio.php control file and its contents remain, but will not be used.
These new versions provide a Folios listing in the TNG Admin area that looks and works just like the TNG Media listing, allowing you to select, edit, preview or delete folios. When a folio is deleted it is removed from the database, but no files or folders are ever deleted. The folio can be quickly recreated using the Folios admin tools.
The Folio Explorer lets you quickly select a folder to register as a folio. Any folders already registered as folios will be grayed out and not selectable.
Zoom Pan
On each folio page that displays an image, there is a "full-screen" icon (see below). When clicked, the folio image appears in full screen mode, which can then be zoomed and panned to view very small detail. In some cases, an even larger image can be achieved by combining it with the Browser's F11 (full screen) key. This works especially well with high resolution images like census returns. Icon colors are selectable to better fit your site's color scheme.
Tip
If you cannot stop the zoom when using the mouse wheel, and you are using a wireless Logi mouse and keyboard with a USB dongle, you will need to reconfigure the mouse.
Download Logi Options+ for your keyboard-mouse model from the internet: https://www.logitech.com/en-us/software/logi-options-plus.html
Open the app and:
- Click on the mouse image
- Click on "Point and scroll"
- Click on the image where it says "Scroll wheel"
- Turn "Smooth scrolling" off with the on-off button.
Compatibility
Please check your current version of TNG and the table below to determine which version will be suitable for your website.
| Version | v12 all | v13 all | v14 all | v15 all |
|---|---|---|---|---|
| 13.0.0.37 | PHP 5.6/7.4/8.0 | PHP 7.4/8.2 | ||
| 14.0.5.40 | PHP 7.4/8.2 | |||
| 15.0.1.41 | PHP 7.4/8.2 |
*green: compatible red: not compatible white: not tested
Custom Titles For Page Tabs
Suppose you have a book with numbered pages and you want the Showfolio tabs to match the page numbers. For example, suppose you have pages with Roman numerals? No problem. What if the number of pages is really, really large, maybe in the thousands. No problem.
You can also determine the number of page tabs to show for each folio. If your Folio is just a collection of unconnected documents, you can number them sequentially, starting with a cover page if you choose. Or you can label the tabs individually to describe the underlying page content, for example, "Birth", "Death", etc.
To customize the tabs you must provide a tab map either in the folio.php control file or using the Admin Folios functions. A page map contains one entry for each page, or group of pages in the Folio. A tab map gives you a syntax to express a range of sequentially numbered pages, starting at the point where it is found in the map and continuing until reaching the final page in the range, for example, using "[14-321]" you won't have to type all the page numbers from 14 to 321 in your tab map.
You are not required to use a tab map. If none is found, the Showfolio defaults will be used.
In the tab map string you can label each page individually using a number or text, you can use a range of numbers inside square brackets -- [4-56], or you can use a prefixed page number range -- i[1-12], where each page number will be prefixed by the single letter.
Latest versions (v14.0.5.40 and v15.0.1.41) allow you to enter a tab map into an edit window as a plain string without quotes. Thus,
Title, iii, iv, v, vi, img 1, [1-12], img 2, [13-422], i[1-23], Back
For older version using folio.php, here is an example of a tab map for a book which contains a title page, front matter (Roman numerals), several hundred numbered pages (ranges) and images. The map is an array defined in standard PHP syntax.
// Map labels for this Folio tabs $tabmap = array( 'Title', 'iii','iv','v','vi','img 1', '[1-12]', 'img 2','[13-422]', 'i[1-23], 'Back' );
For those unfamiliar with PHP arrays, a simpler alternative mapping allows you to use a plain string. As you can see in the example below, you may split the string over several lines for readability, but it must be enclosed in double quotes ("") and terminated with a semicolon (;) after the final quote.
$tabmap = " Title, iii, iv, v, vi, img 1, [1-12], img 2, [13-422], i[1-23], Back";
Please Note: If you add or remove a page from the folio, you must adjust the tab map accordingly or tab labels will become unsynchronized. Also Note: You must enter the tab map with a code editor. To repeat, it is not necessary to use a tab map if you only need the default tabs numbered according to the order of pages shown. Also, a page map is not necessary if you use a 'Cover' page in your folio configuration - Showfolio will automatically adjust the page numbers so they start numbering from the second page.
Number of Tabs Displayed
You can set the number of tabs to display on each side of the current page tab. The default is 2, but to expand the number of visible tabs you can set $sidetabs, for example: $sidetabs = 4. That places the preceding four page tabs before the current tab, and the following four tabs after the current tab. The tab line will also include the previous and next buttons plus the anchor tabs (first and last page) which are fixed. Your choice will depend on the tab size -- that is, the number of characters contained in the tab labels chosen for a particular Folio.
// Number of inner tabs to show on either side of a selected tab (default=2) $sidetabs = 5;
Turning PDF Into a Folio Book
1. Download and use a utility to break up a PDF file into JPG page images. There is a built-in utility in Windows 10, but I recommend IceCream PDF because it handles any number of PDF pages, you can control the quality of the output JPG files, and the files tend to be smaller to speed up display time.
2. Name the JPG page files to alpha sort correctly -- for example, page0001.jpg, page0002.jpg, etc. Note that to alpha sort, the numbers must be padded to a fixed length.
3. Add a $tabmap array to folio.php and optionally add a $sidetabs setting (see above).
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. The mod developer has been running the Showfolio Mod on his production site and on several test sites going back to TNGv9.1.0 with no particular problems.
If you experience any problems, 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. For example: $pdfpath = "/home/smythe/pdf/"; where the information in quotes is your actual server path.
Revisions
| Version | Date Released | Showfolio — What's New |
|---|---|---|
| version 15.0.1.42 |
| |
| version 14.0.5.43 |
| |
| version 15.0.1.41a |
| |
| version 14.0.5.40a |
| |
| version 15.0.1.41 |
| |
| version 14.0.5.40 |
| |
| version 15.0.0.38 |
| |
| version 13.0.0.36 |
| |
| version 13.0.0.36 |
| |
| version 13.0.0.35 |
| |
| version 13.0.0.34 |
| |
| version 13.0.0.33 |
| |
| version 13.0.0.32 |
| |
| version 13.0.0.31 |
| |
| version 13.0.0.30 |
| |
| version 13.0.0.29 |
| |
| version 13.0.0.28 |
| |
| version 13.0.0.27 |
| |
| version 13.0.0.26 |
| |
| version 13.0.0.25 |
| |
| version 13.0.0.24 |
| |
| version 13.0.0.23 |
| |
| version 13.0.0.22 |
| |
| version 13.0.0.21 version 12.0.0.21 |
| |
| version 13.0.0.20 version 12.0.0.20 |
| |
| version 13.0.0.19 version 12.0.0.19 |
| |
| version 13.0.0.18 |
| |
| version 12.0.0.17 |
| |
| version 12.0.0.16 |
| |
| version 12.0.0.15 |
| |
| version 12.0.0.14 |
| |
| version 12.0.0.13 |
| |
| version 12.0.0.12 |
| |
| version 10.1.1.11 |
| |
| version 10.1.1.10 |
| |
| version 10.1.1.9 |
| |
| version 10.1.1.8 |
| |
| version 10.1.1.7 |
| |
| version 10.1.1.6 |
| |
| version 10.1.1.5 |
| |
| version 10.1.1.4 |
| |
| version 10.1.1.3 |
| |
| version 9-10.1.1.2 |
| |
| version 9-10.1.1.1 |
|
Installing Showfolio
Please uninstall any earlier version of the Showfolio Mod and Admin Showfolio Mod. The latter is no longer used as the admin functions are now included in the Showfolio Mod.
Showfolio Mod installs like any other mod, except immediately after installation you must click on the button in the mod listing to create the folios table.
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.
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 uninstall the mod from your Mod Manager. Removing the mod does not remove the folders or database records for any folios you have created, but the material in the folio folders will not be accessible as media via TNG.
You can reinstall or update the Showfolio Mod and your folios will be accessible again.
If you wish to uninstall all folio records from your database, you can use the Showfolio Admin Mod. -Note: this mod is no longer required with Showfolio Mod versions starting with v14.0.5.40 and v15.0.1.41.
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
-Note: this is no longer required with Showfolio versions v14.0.5.40 and v15.0.1.41 and higher.
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
header("Location:../../showfolio.php?mediaID=1678");
/*************************************************************************
FOLIO: military/cw24/folio.php (Sat, 08 Aug 2015)
Cheney B. Bisbee Civil War Pension File
*************************************************************************/
// Treat first page as cover sheet
$usecover=true;
// ignore any files in the folder with extensions .html or .htm
$exclude[] = ".htm";
$exclude[] = ".html";
// add link to download pdf from the site's private area
$pdffetch ="cbisibee.pdf";
?>
Set Local Options
-Note: Starting with Showfolio Mod versions 14.0.5.40 and 15.0.1.41 and higher, these configurations will be set using the Folios editor in the TNG Admin.
Options in the folio.php 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 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. IMPORTANT! This HTML link must be relative to the folio control folder -- folio.php. Since PDF is not an allowed Folio page file, you can place it right in the Folio if you wish. Best practice would be to place it in a subfolder of the folio, so the link might look something like 'inc/mydoc.php'. The same subfolder would also be a good place for any image files that are displayed in html pages. Because they are in a subfolder, they will not display separately as folio pages. |
| $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 private PDF file directory must be defined in customconfig.php. For example, $pdfpath="/home6/subserv2/pdf/"; Notice the trailing forward slash. |
| $sidetabs = 2; | Sets the number of page tabs that will appear on either side of the currently selected page. The longer your tab labels the fewer you will want showing at the top of your page. |
| 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. |
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
Starting with Showfolio Mod versions v14.0.4.40 and v15.0.1.41, you can use the built-in folios editor to create, modify or delete folios. Remember, deleting a folio does not delete any files or folders, and they may be quickly recreated again if desired.
Once you've registered a folder as a TNG folio, you can click on the button at the bottom of the editor to take you to the TNG media page for editing things like the icon to be show with the folio, and link it to users or other events. You will Save & Exit Media editor when finished to return to the Folios editor to review and save the folio. From the Folios listing you can search and select folios by title, edit them, preview them or delete them.
For users of older version of the Showfolio Mod, after creating a folio (folder) inside any media collection (folder) such as Documents or Histories, go to your TNG Admin >> Media page, select the collection, find the folder and then select its folio.php as the media file. Fill out the rest of the required Media information fields and link it to a person or family. After saving it to the database, it will list with whatever collection it belongs to, and will display as a multi-page folio.
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.
Please consult your TNG documentation for instructions on creating a TNG media collection.
Organizing this way appeals to the tidy mind, but makes it very tedious to enter new media into the TNG system. Personal Photos, census returns, marriage records, death certificates, are all entered into separate collections with their own maintained structures.
Folios can greatly simplify this aspect of adding new media. For instance, you can create a collection and call it, say, "Exhibits".
Under Exhibits you can create folios associated with persons, using their personID as folio names, then register the folios as TNG media and associate them with the appropriate person.
Thereafter, place all new media in the person's folio, available for immediate inspection by site visitors. You can maintain a tab map for custom labels such as '1950 Census' if you like, or you can just allow folios to number them sequentially according to the order of their page file names.
There is a way you can link a media document that exists in one folio, into another folio's pages. For example, a headstone with both husband and wife's name can be physically placed in both folios, or can be placed in one folio and just linked as a page in the other. Actually it's quicker to duplicate them -- efficiency vs convenience.
If you need to register a document contained in the folio and associate it with an event such as 'Birth', go ahead and do it using the "Exhibits" collection and folio name/doc.jpg as the medium. For example, 'exhibits/p004352/bc4352.jpg. Note that I've prefixed and padded the PID so that it will alpha-sort properly. I use prefix 'bc' for birth certificates and the file is forever linked with personID 4352. This is a strictly personal choice. There are many other ways to do things.
Folio Screenshot
Example of a working folio.
Note that this particular folio has tab mapped labels. In a large folio, it is convenient to use the Enter Tab window to jump to a far tab you want. If you enter a number, Showfolio first looks to see if there is a mapped label beginning with that number. If none found, it searches for an exact match with an indexed page number.
A cover page can be inserted at the beginning of the folio to provide a description/transcription of the folio contents, and/or show links to other interesting information on the site or externally on sites such as Find A Grave.
In admin mode (shown) there is a link (icon) to edit the media in TNG.
A PDf download link can be set in the folio.php control file to provide visitors with a PDF version of the folio, or any other associated PDF you want. Even if the site is open to all, you can specify that the download for this folio is available only to logged in members.
Although these options are easily edited directly into the folio.php control file, the companion admin_showfolio Mod helps set them up for you and is much quicker.
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.
- A Bisbee Family History mod developer and TNG Forum user Kazooter's site
- Grandfather's World War One Service Record WP/TNG v14.0.0 Mod v13.0.0.23 -- Fantastic Mod
- Family tree of Marcin & Emilia Senderski
- William Ernest Moffat Roger Moffat's site incorporated with WordPress
- Chamberlain & Eidenbenz Genealogy Used this mod from day 1. Just gets better and better!
- Kleinmann Genealogy Love this mod!
- R G Strong Family Genealogy Great!
- Nordic Ancestry Great addition to TNG !
- The Shardalow name and variations of. Took a while to get the hang of it, but now love it!
- The Clist Connections This mod is essential IMHO and I couldn't imagine TNG life without it!
- Ostfrieslands Ortssippenbücher Die Seite lebt von dieser MODifikation
The following private sites have installed Showfolio Mod and contain folios which are only viewable with a login.
- Malkins' in Nu Tirani - New Zealand WP/TNG v15.0 Mod v15.0.0.38 -- Excellent Mod
- Chris Korte's New Zealand Genealogy Project TNG v14.0.5 Mod v13.0.0.33
