+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ --OLD-- thumbspage closed issues and developer notes trimmed from the source code and not added to the later UserGuide. These are probably of interest to developers mainly, and were retained as historical context and example. +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ =========================================================================== CLOSED ISSUES =========================================================================== This section lists recently closed and current issues, some of which are open to user feedback (via lutz@learning-python.com). This list may not be complete; search for "caveat" in this and other code files here for additional items, and see section "VERSION HISTORY" above for more on version changes noted here. --CLOSED-- 1) Python 3.X assumes local platform's Unicode encoding default for header/footer inserts and the output page: change as needed. ==> Addressed and resolved in 1.3, per version notes above. 2) This script would probably run on Python 2.X too if the viewer_thumbs module didn't import "tkinter" (a book legacy). ==> But no longer as is, as of 1.3's Unicode enhancements: punt on trying to maintain 1.2 compatibility. 3) Styling of the table is open ended. For example, a style "border-spacing: 4px;" may help avoid names running into each other, though the default (2px?) seems adequate. ==> Addressed in version 1.4 with extra CSS styling. 4) The reused viewer_thumbs module skips non-image files by simply catching errors; this could use Python's mimetypes module instead. ==> See PyPhoto's newer version of this module, which uses mimetypes as described; alas, it's a fork. Here's the newer code's online link: http://learning-python.com/ pygadgets-products/unzipped/_PyPhoto/PIL/viewer_thumbs.py ==> Addressed in version 1.5: incorporated the PyPhoto mods here, though PyPhoto's viewer_thumbs may still vary arbitrarily. 5) Relying on browser-specific display of full images isn't ideal, because such displays vary in scaling, background color, etc. ==> Addressed by version 1.5's image-viewer pages (see above). 6) Desktop Chrome (only) botches
s and borders at some zoom levels: the former may be lighter at some page locations than others, and the latter may drop one or more sides altogether. This was first seen when odd Unicode characters were on-page, but can happen anywhere - at user-zoom levels at or below 90%, all bets are off on
- and -border rendering. It also happens on both index pages and 1.5 viewer pages; the latter's CSS borders may drop one or more sides at <= 90% zoom. This has been observed on desktop Chrome only, and in versions 66 and 68 on Mac OS and Windows. The only fix seems to be to not use
or borders - an extreme workaround. Styling
s (e.g., style="height: 0.5px; background-color: black;") doesn't fix the issue at all zoom levels. This is clearly a (temporary?) browser bug, but unfortunate in this site's most widely used browser. ==> Addressed
s in 1.5 by replacing them with table borders. Chrome borders around s still vanish at zoom <= 90%, but they are nice enough to keep, even if only 3 sided. ==> Addressed s in 1.6 by using "thin" instead of "1px" for all CSS image border widths. This fixes borders on both index and viewer pages. Per above, index-page
s became table borders in 1.5, for which "1px" works correctly. 7) Viewer-page image scaling in CSS is lousy - there's no way to adjust to changes in window aspect ratio well. For more details, see [defunct] "USAGE NOTE" above, and code notes below. JavaScript may help, but using Python to generate HTML that embeds both CSS and JavaScript seems a bit much for a simple Python image viewer... ==> Addressed by 1.6's JavaScript-based dynamic image scaling. This makes both this script and its output a bit of a tangled mess, but such is life in web development today. 8) Assuming UTF-8 for all insert files' Unicode encoding is simple (and also works for ASCII, as it's a UTF-8 subset), but requires either a minor script change or file conversions for differing platform defaults; is this a significant usage factor? ==> Addressed in 1.6: insert encoding was made a separately and easily configurable setting in user_configs.py. =========================================================================== DEVELOPER NOTES =========================================================================== This section provides additional details and musings mostly of interest to programmers, not users (but Android users: see #C). Items are prefixed by the version relevant or current when added. 1) (all) SCOPE: Apart from header/footer inserts, this script makes fairly simplistic image and subfolder links only; edit either the output HTML page or the code here that creates it as desired. [Update: this program has grown less simple but more useful, with version 1.4 styling, 1.5 image-viewer pages, and 1.6 image scaling.] 2) (1.1) SUBFOLDERS: Makes a bullet list for any subfolders in the images folder (else they cannot be navigated to), but skips all other non-image content; put any doctype, readme, font, CSS code, etc., in header or footer. Run on each image tree subfolder manually; automating this and other content seems too clever and complex. 3) (1.2) STYLING: Stretching the thumbs table to fill the whole window is off by default, as it can appear too spread out for short names in large windows. Enable this via the user_configs.py setting if desired. [Update: as of 1.5, stretching is always on, for new table borders.] 4) (1.2) STYLING: A table overflow scrollbar was skipped, as it appears only at table bottom, which can be very far away on large pages. Instead, use the browser's automatic general window scroll. [Update: changed in 1.4 - now uses CSS autoscroll for thumbs table, which is more mobile-friendly, and shows the scrollbar iff needed.] 5) (1.3) UNICODE: The script now fully supports images with non-ASCII names, but getting them onto your web server may take special steps. On one Linux server, an "unzip" of the WinZip zip package failed on the Unicode test images, but GoDaddy's browser-based file upload worked (and in later use, Mac OS and cPanel uploads both handle Unicode well). See examples/unicode/_README.txt for more on uploading result files. See also learning-python.com/ziptools for a Python zip alternative. 6) (1.3) UNICODE: the insertEncoding setting now defaults to UTF-8, as this is a general scheme which also works for ASCII files. To use your platform's default encoding instead, set this variable to None; this is not required if header/footer inserts are saved as UTF-8. 7) (1.3) UNICODE: If (but only if) file or folder names are non-ASCII, custom HEADER.html files must include a content-type tag with a charset matching the outputEncoding (which is UTF-8 by default). Default headers include this tag automatically (see code ahead). 8) (all) CSS: Note that index-page styling must be all inline, to avoid asking custom HEADER.html files to code or link to this CSS code. 9) (all) RELATED: See also pixindex, a related tool that adds images to a zip file and FTPs them to a sever: learning-python.com/pixindex. A) (all) DESIGN: As noted in OVERVIEW, this script's results are static. Although adapting it to produce results dynamically on a server would support changes in server-folder content, this would require a web server, rendering results unusable offline (e.g., in program docs). Generating results dynamically on a server would also require redesign of thumbnail generation to avoid long delays. B) (1.6) LOADING INDICATOR: viewer page images are hidden by JavaScript until loaded, to avoid an annoying 'flash' in some contexts. If JavaScript is enabled, a "Loading..." paragraph is also posted temporarily (else the screen is blank on loads). Index pages load thumbnails quickly, and require no indicator. C) [this was moved to usage notes] (1.6) ANDROID "RAW" AND USER SETTINGS: the native image display on some Android Chromes may initially render some images oddly and too large in portrait orientation, but if and only if the seemingly unrelated "Force enable zoom" is selected in Accessibility Settings. The "Raw" links of viewer pages trigger this, but it is not caused by this program - it also happens when visiting images' URLs directly, completely outside the script's pages. It's also limited - it occurs for some images only, and never when the Setting is cleared. This is sadly typical of browsers' fragility. Indeed, at times it seems a website could be laid low by a good sneeze... Users may be best served by clearing this setting in this use case. For more clues, try a search on "android chrome force enable zoom displays images too large", or this possibly related bug report: see https://bugs.chromium.org/p/chromium/issues/detail?id=464295.