ShearerSite Template System

Revision History

Changes in ShearerSite 1.5b16 (2003-06-14)

Improvements

DirectRSS has many changes, including full namespace support. There's also a new detailed tutorial and configuration instructions for using DirectRSS for both single-file RSS and blogBrowser formats.

The ShearerSite administration page now promotes index or default pages to their own area the top of the file list. It also renames the "Apply"/"Reapply" button to "Update Pages", and displays some help as to why you would want to click it.

Installation on other web servers is now easier. The web-resources folder is laid out the same way as a typical web server. The README file gives instructions.

Notes

DirectRSS generates better-looking XML output if the input XML documents already have the correct namespaces defined on the root element. Otherwise, it can write extra namespace definitions. The sample files are set up correctly.

RSS includes don't yet filter the input for obnoxious scripts, styles, or meta tags, so only include RSS feeds you trust.

Progress-bar display via Safari on LocalWebAppServer doesn't work well; the page only displays when the operation is finished. The same thing works fine in Mozilla, and also works fine when using Safari with another web server. (On IE for Mac, display updating is very infrequent, but this is the case when using it with any web server.) All other browser/platform combinations seem to work; it's just a two-way conflict where Safari disables progressive rendering when used with LocalWebAppServer.

Edit Page, when used on HTML pages, works through a textarea instead of a WYSIWYG editor, so its usefulness is limited.

In Advanced Options view, the "Show extra progress details" option for the Update Pages command is temporarily nonfunctional.

Bug fixes

The Display Template Info feature was broken; it was showing HTML source code to the user rather than the real thing. (The bug was caused by an internal change to passing titles without HTML encoding. This code used the navigation writer to display the template hierarchy, and put HTML in the 'title' slot. Now there's a 'titleHTML' slot.)

Fix for an obscure template problem. If there was a meta tag that needed to be removed inside a FrontPage border that was being removed, the command would give an error and stop template application. (This is illegal HTML, since meta tags should come in the head element, but there are some strange pages out there.)

The sample stylesheet eliminates a lot of unwanted whitespace that showed up above the navigation arrows in Mozilla.


Changes in version 1.5b15 (2003-05-31)

This bug-fix release corrects a problem displaying files with missing page titles and generating navigation with Unicode page titles. The launcher for the built-in web server is compatible with more operating system versions (by using 127.0.0.1 in place of localhost). Other changes to the experimental PushSync FTP replication and DirectRSS blogBrowser modules enable them to work daily on a test site.

Change Log


RSS

DirectRSS: Read 'sample-file','recent-file','recent-max' parameters from .ini file. Change sample weblog ID to "home" instead of "sample", to match Radio Userland default.

Rss_plugin: Capitalization fixes to the permalink anchor name, the MetaWeblog API item permaLink itself, and date range specifiers. Got to love case sensitivity. (Only the date range specifier one caused an actual problem--it ignored the date range.)

rssweblog: RSS items now have a getCategories() method. FilteredRSSLister category match is now case-insensitive.

WeblogArchiver: Ditch SAX parser in favor of our own rssweblog module, so the module will now work with blogBrowser format and on systems without expat, such as the default Mac OS X 10.2 install.

PushSync

PushSyncCGI: Always operate in recursive mode.

Replicator: Set FolderIterator's file filtering RE to allow non-HTML files.

FTPEndpoint: Autogenerate folders if needed on dest. NullEndpoint: use to ignore changes to the files; use as a temporary destination for "assume dest is up to date" functionality (if the dest really is up to date, and PushSync just doesn't know about it).

Main

LocalWebAppServer: Open browser to 127.0.0.1 instead of localhost. Pre-NT Windows, and IE (only) for Mac OS X, don't like localhost.

FileIterator: Allow subclasses to override filename filtering regexp.

HTMLTemplateFilter: Work around bug in Python 2.2.0 StringIO and Unicode strings (replace with our own tiny class MyStringIO).

NavigationTemplateWriter: Send output in Unicode rather than trying to pre-encode it.

metainfo: Fix case where title is missing; don't try to HTMLDecode it. Also bring HTMLDecoding to TitleFilter.

Build script: added CGITools, PushSyncPackage, ChangeLog.txt.


Changes in version 1.5b14 (2003-05-27)

This beta release improves the appearance of several components, including the main web administration page, and contains many bug fixes and new features for DirectRSS, including full namespace support. It also marks the debut of PushSync (in an alpha version), which efficiently publishes web site changes using file copies, FTP, or other methods added through plugins. LocalWebAppServer now supports command line arguments that are passed to servlets, and PushSync and DirectRSS use this capability to specify configuration files. Sample files are included so you can be up and running in five minutes. There are more than 100 changes since 1.5b13.

Change Log

adminCGI

Support API change to metainfo such that page titles no longer come across HTML entity-encoded. Now titles with entities or Unicode characters will show up as intended in the file list, without showing the HTML code. performEditPage page now handles submitted Unicode (UTF-8) page titles properly. The title was the one field that wasn't passed through the decoder. More character encoding support: response methods can now set their own encoding. Uses imported HTMLEncode implementation instead of built-in one. Also added support for adminHTML combining Document Title and navTitle (Short Title). Fix Show Template Info page to resolve warning messages. Remove Publish button & shorten help message when publishing has not been set up for a folder. Fix possible UTF-8 decoding error after uploading an HTML file, while assigning its title. Now can be called directly as a CGI, without the admin.pycgi wrapper (or LocalWebAppServer), if desired. Added externalRedirect() method to HTTPOutput class and selfRelativeURLToFullURL() function, enabling us to ditch redirectBugWorkaround (which fixed an IIS hang when we passed a partial URL).

adminHTML

Redesigned file list. New custom Rename, Edit, and Delete buttons. (Delete now requires JavaScript.) Removed Content Modified column. Combined Document Title and Nav. Title--now named Short Title--columns. Blue reverse-out column headings. Removed reference to Medical Computing in Convert to PDF section in Advanced view. Hide Publish button & shorten help message when publishing has not been set up for a folder.

DirectRSS

Config options are now read from a text file. DirectRSSConfig.py removed in favor of .ini file, set by command-line param, environment var, or setting in DirectRSS.pycgi. Running under LocalWebAppServer, now installs itself at /RPC2, matching Radio Userland. New description for LocalWebAppServer list page. Exception classes for all errors. Use of new high-level rssitem methods in rssweblog. Bug fix to metaWeblog.getCategories() result format. Setup page, visible in a browser when loading the DirectRSS URL, shows how to configure the weblog posting program for this DirectRSS instance. XML-RPC error responses are now formatted for better display.

HTMLEncode

Make default output encoding ASCII rather than UTF-8. It's a subset of most other output encodings this script supports, so it's compatible. It may just require more numeric entities. iso-8859-1 is still the default input encoding, to reduce the incidence of 'ordinal out of range errors' for non-ASCII input and instead use the most probable interpretation. Moved updated implementation from adminCGI.py. Be more careful to stringify input and encode output character-by-character if necessary to avoid unistrs seeping out.

HTMLFilter

Added hex entity decoding. Expanded docstring for HTMLDecode.

HTMLTemplateFilter

Fix bug in filtering out template tags in head element, most often causing duplicate meta name="description" tags from the template to show up in content pages. Wrote MetaTagDirector class to arbitrate whether content or template gets to keep a tag. Also change user-visible references to content "sections" to "regions", in line with other template tools.

Include_plugin

Fix parameter count; wasn't updated for new documentInfo parameter.

LocalWebAppServer

Support command-line config parameters for servlets. Consolidate code into WebServerMap class. Better way of importing servlets that doesn't involve modifying sys.path. Better-looking CGI list page. Static files in web root now get a Content-Length header. Fix extra Connection: close header on 404 error; in fact, remove all Connection: close headers.

metainfo

Now can return HTML-decoded page titles, leading to greater compatibility of title display with different output devices and encodings.

PushSync

PushSync efficiently publishes changes to your web site to another server or another location on the same system. It makes its alpha debut with support for local file copies and FTP replication, configured through an .ini file.

rssweblog.py

Many changes for full namespace support. Now reads and generates radioWeblogPost:id elements. Bug fix to metaWeblog.getCategories() response format. Editing description no longer could leave an extra, out-of-sync content:encoded element from another weblogging system. Bug fix to editing repeating category elements. Preserve existing amount of whitespace around weblog posting in RSS file while editing, and add a blank line after new postings. post.getDate() returns pubDate (creation date) in preference to dc:date (mod date). New methods: post.setCreationDate(), setModificationDate(), setCategories(), setGUID(), setPostID(), and autoSetPostID(). Code now makes sure XML declaration gets written. SAX adapter now enables namespace support and tracks namespace prefix mapping. xmllib adapter grabs encoding name from file, and triggers SAX-like prefix mapping events by keeping track of xmllib's namespace map in conjunction with its own stack. New methods in xmlFilter provide namespace hooks, and xmlWriter now adds xmlns attributes when needed.

showtitle.py

New command-line tool, intended for use by search indexing engines while indexing PDF (or other non-HTML) files. Retrieves the title the user has set in ShearerSite. An extension to the ht://Dig search engine has been successfully tested and implemented with a patch to its conv_doc.pl script.


Bug fixes in version 1.5b8 (2003-02-19):

  1. In LocalWebAppServer, worked around a problem that made POST requests fail on Windows.

New features in version 1.5b7 (2003-02-17):

  1. LocalWebAppServer, a built-in web server that allows use the web interface even on personal machines without an existing web server. Preconfigured launchers are provided for Mac OS X, Windows, Linux, and other Unices, so you can edit the sample site out of the box. (LocalWebAppServer will autolaunch your browser with a page presenting a menu of all available web applications. Additional applications can be placed in the "servlets" folder. The web application server uses a multithreaded-compatible variant of the standard Python CGI API, so it's straightforward for developers to convert existing Python CGI scripts so that they can also run inside the application server.)

New features in version 1.3 (2002-03-11):

  1. Folder-based navigation. The navigation hierarchy can be inferred directly from the layout of files in folders themselves. This can be used instead of reading navigation information from FrontPage.
  2. New navigation writer. Though the old navigation writer is still available and works with FrontPage or folder-based navigation, the new writer allows much more control over what is displayed in the "navigation-children" area.
    New meta tags used by the navigation writer:
    • DC.Title specifies a document title that overrides the one given in the title tag as far as the navigation system is concerned. The regular <title>-tag title shows up as always in bookmarks and window titles. The suggested use for this is to have a long title for bookmarks, and a shorter DC.Title for navigation that may only make sense in context. For example, the page titled "Andrew Shearer's Software" has a DC.Title of "Software". The extra words in the first title allow it to stand alone, but they would be redundant in the navigation area.
    • template.navigation.hold specifies the number of folder levels deeper that this page will still appear at the top of the navigation "children" area. By default, it is 0 (the digit zero), and the child pages themselves will appear at top of the "children" area, while the parent page retreats to the breadcrumb trail. This meta tag affects only the navigation views of child pages and subfolders, not the page that contains it. Set it to a number greater than zero for areas where the user may hop around frequently between and across subfolder levels. Since the current page's navigation links are "held" or duplicated to pages below this one, the user won't have to use the breadcrumb-trail links to go back up the hierarchy before following a different one of the navigation links. The disadvantage is that the list may grow longer, since the links called for by both parent and child are included.
    • template.navigation.expand specifies the number of levels to expand the hierarchy. Use 0 to hide all children, and 1 to show immediate children. Use higher values if the immediate children are not linkable (see template.navigation.no-link). This option only has an effect when used in a folder's default or index file. Children are defined as the non-default, non-index files inside the folder, plus any direct subfolders containing default or index files.
    • template.navigation.no-link prevents this page from being linked from navigation views, though its title will still appear. Useful in content-free index pages in folders that only exist to categorize other files. Requiring a placeholder index page for a folder to appear in the navigation view has an advantage: if the user decides to chop off the end of a URL path, there will still be an index page there with all of the child links in place, even if it has no other content.
  3. New "Edit" button for folder settings allows configuration over the Web.
  4. Modification date saving (optional). Now running the template system over a set of files does not destroy the modification date information, even if the template has changed. This feature can be switched on by including a DC.Date meta tag in the template. The DC.Date and automatic template.Content-MD5 meta tags work together to preserve modification date information even despite spurious changes to the file's modification date by other programs such as FrontPage. The template.Content-MD5 meta tag saves a checksum of content areas of the document (ignoring areas from the template), and the DC.Date meta tag is only updated with the file's last modification date if the content has actually changed. If you need to correct a DC.Date manually, change it in the content page after first applying a template a DC.Date meta tag. The change will stick even through template applications and changes until you actually modify the content again. Note that changes to <head>-element tags such as <title> and <meta> do not count as content changes.
  5. XHTML compatibility. An XML directive at the top of the template file, such as <?xml version="1.0"?> causes generated meta tags to be XML-compatible. The program does not attempt to convert other HTML into XHTML, and it does not yet recognize XML empty-element syntax in template directives. So be sure to match XHTML templates with XHTML content, and HTML 2-4 templates with HTML 2-4 content.

New features in version 1.2 (2001-10-31):

  1. You can now apply the templates to any folder. Nested subfolders without template settings of their own will inherit their settings from parent folders (just as they would have if you had applied templates to a parent folder, but without the waiting).
  2. Implemented "shy newlines", to prevent blank lines from appearing in the <head> element when meta tags are removed from the content page.
  3. Support for client-side scripts in both the template and content. Use fromtemplate, onloadfromtemplate, onunloadfromtemplate, onloadfromcontent, onunloadfromcontent boolean attributes to distinguish template and content-based scripts.
  4. The folder's template settings are now displayed on the admin page for the folder.