Publish Web Plugin

Utility to publish a TWiki web to static HTML pages. Useful to maintain a static website collaboratively in an access restricted TWiki.

Description and Syntax Rules

One web (defined in the PUBLISHWEBNAME setting) serves as the master for the static HTML pages. The Plugin generates an HTML pages every time a user saves a topic in the Publish web. The static HTML files are based on a TWiki skin of choice. All referred attachments (images etc) are copied to a publish directory.

Topics and Links

  • The home topic is assumed to be Index
  • Topic names: For clarity, use capitalized words and underscores (Wiki Word names are possible too)
  • All links should be defined as double square bracket links, e.g. [[Topic]] or [[Topic][label]] (do not use Wiki Word links)

Publish process

  • A static HTML page is generated for exery topic saved in the Publish web (unless listed in the EXCLUDETOPIC setting)
  • Topic names get converted to a lowercase filename, e.g. Index to index.html, AboutUs to aboutus.html, and Customer_Support to customer_support.html
  • Only text between %STARTPUBLISH% and %STOPPUBLISH% is used (the whole text if missing)
  • WikiWord links are ignored, also across webs
  • Page layout is based on the skin defined in the PUBLISHSKIN setting
  • Topics can be re-published without an edit/save cycle.
    Topic: Clear
    %PUBLISHWEB{ "" topic="" }%

Variables

  • %STARTPUBLISH% - place in topic text where to start publishing
    • Optional, start from top if missing
  • %STOPPUBLISH% - place in topic text where to stop publishing
    • Optional, publish to end of topic if missing
  • %PUBLISHWEB{"nicetopic"}% - nice topic name
    • Shows a "nice" topic name of the current topic: Underscores in topic names are rendered as space; the Index topic is rendered with the HOMELABEL Plugin setting
    • Example: Topic Customer_Support turns into Customer Support
  • %PUBLISHWEB{"breadcrumb"}% - nice breadcrumb
    • The breadcrumb is based on the parent child relationship of topics, starting at the Index topic
    • The breadcrumb does not include the current topic, append %PUBLISHWEB{"nicetopic"}% to get the complete breadcrumb
    • The skin may contain a %PUBLISHWEB{"breadcrumb"}% variable to show the breadcrumb
    • Underscores in topic names are rendered as space
    • Example: You are here: Home > Customer Support >
  • %PUBLISHWEB{"publish" topic="Name"}% - re-publish topic(s) without edit/save cycle
    • Useful to refresh all HTML pages if the skin has been modified
    • A topic="all" publishes all topics in the Publish web except for the excluded ones
    • A topic="Any_Topic" publishes a specific topics

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, i.e. %PUBLISHWEBPLUGIN_SHORTDESCRIPTION%

  • One line description, is shown in the Text Formatting Rules topic:
    • Set SHORTDESCRIPTION = Maintain a static website collaboratively in a TWiki web

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

  • Web to publish:
    • Set PUBLISHWEBNAME = Publish

  • Skin to use to publish:
    • Set PUBLISHSKIN = print

  • Home label, used in %PUBLISHBREADCRUMB%:
    • Set HOMELABEL = Home

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

  • Download the ZIP file from the Plugin web (see below)
  • Unzip PublishWebPlugin.zip in your twiki installation directory. Content:
    File: Description:
    data/TWiki/PublishWebPlugin.txt Plugin topic
    data/TWiki/PublishWebPlugin.txt,v Plugin topic repository
    data/Publish/WebPublish.txt Plugin topic
    data/Publish/WebPublish.txt,v Plugin topic repository
    lib/TWiki/Plugins/PublishWebPlugin.pm Plugin Perl module
  • Configure and test the installated Plugin:
    • TWiki 4.0 and up: Run the configure script to enable the Plugin
    • Change the Plugin settings as needed (for now leave PUBLISHSKIN = print setting)
    • Configuration on shell level:
      • Settings in lib/TWiki/Plugins/PublishWebPlugin.pm: For security, the output directories are defined in the PublishWebPlugin.pm library. Change the hardcoded settings if needed:
        • $publishPath defines the output directory of the static HTML files, relative to the twiki/pub directory; defaults to the parent directory of the twiki/pub directory; should point to the htdocs root directory
        • $attachPath defaults _publish; is relative to $publishPath
      • Create the directory indicated in the $attachPath setting
      • Change the permission of directories indicated by $publishPath and $attachPath to be writable by the cgi user (typically user nobody)
    • Create new TWiki web for website publishing:
      • Create a new Publish web (name indicated by the PUBLISHWEBNAME Plugin setting)
      • In WebPreferences of that web, set the NOAUTOLINK setting to on
      • For convenience, add these links to the Web Left Bar:
        • *Publishing*
        • [[Index][Home page topic]]
        • [[http://%HTTP_HOST%/index.html][/index.html]]
        • [[http://%HTTP_HOST%%PUBLISHWEB{topicurl}%][%PUBLISHWEB{topicurl}%]]
        • [[%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/WebPublish?\
          action=publish;ptopic=%BASETOPIC%][Re-publish this topic]]
        • [[%TWIKIWEB%.PublishWebPlugin][PublishWebPlugin]]
      • Create an Test topic in that web
      • This should generate an test.html page on topic save
      • Create Index topic and other topics
  • Publish skin:
    • Create a new publish skin based on your branding. The TWiki skin can be derived from any twiki/templates/view.*.tmpl skin file
    • Omit any links to TWiki, such as edit and attach links
    • The skin can use Plugin specific settings %PUBLISHWEB{"breadcrumb"}% and %PUBLISHWEB{"nicetopic"}%
    • The skin can introduce skin specific Publish.Web Preferences? settings, such as %PUBLISH_SITE%, %PUBLISH_LOGO%, etc.
    • Activate the new skin in the Plugin's PUBLISHSKIN setting

Limitations

  • All attachments are copied into the same directory, e.g. make sure you use unique filenames across all topics in your publish web and in your skin

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2006, Peter@Thoeny.org
License: GPL (GNU General Public License)
Plugin Version: 15 Feb 2006 (V1.022)
Change History:  
15 Feb 2006: Added %PUBLISHWEB{"publish" topic="Name"}%
13 Feb 2006: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.024
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Benchmarks: Good Style 100%, Formatted Search 100%, Publish Web Plugin 99%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/PublishWebPlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/PublishWebPluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/PublishWebPluginAppraisal

Related Topics: TWiki Plugins, Developer Documentation Category, Admin Documentation Category, TWiki Preferences

-- TWiki:Main.PeterThoeny - 15 Feb 2006
Topic revision: r1 - 15 Feb 2006 - 09:19:07 - Peter Thoeny
 
2picthead.jpg}
Back to Redbourn
Copyright We make no guarantee of the correctness of the content of this site. All material on this collaboration platform is the property of Martin Cleaver and the contributing authors.