Showfolio Mod
|
Downloads of Showfolio Mod are restricted to logged in users. If you do not have a user account on the TNG Wiki use the Request Account link to request a user account |
|
|
This Mod works with all versions of TNGv10.0.3 through current versions of TNGv12. 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 | see Revision History |
| Download link | |
| 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 | 12.0.0.17 |
| Min TNG V | 11.0.3 |
| Max TNG V | 12+ |
| Files modified | globallib.php, genlib.php, admin_media.php, customconfig.php |
| 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 some very early 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.
Compatibility
| Version | v1003-1013 | v11 all | v12 all |
|---|---|---|---|
| 12.0.0.17 | PHP 5.6/7.2 |
*green: compatible red: not compatible white: not tested
Showfolio may work in TNG installations prior to version 10.0.3, but mod options will have to be set by manually by editing them at the top of showfolio.php. Web hosting services are rapidly upgrading their versions of PHP and MySQL, but as long as your TNG website is working, Showfolio should continue to work. If you have a special need to keep Showfolio functional in earlier versions of TNG, please let me know.
See Multisite Testbed for information on how this mod is tested and managed.
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.
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
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. 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 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
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 completely uninstall the mod from your Mod Manager. Removing the mod does not change database records for any folios you have created, and 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)
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 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
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.
Folio Screenshot
Example of a working folio.
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.
- A Bisbee Family History mod developer and TNG Forum user Kazooter's site
- 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!
