TWiki> TWiki_ Web>PublishWebPlugin

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.

On this page:

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 page 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 (WikiWord names are possible too)
  • All links should be defined as double square bracket links, e.g. [[Topic]] or [[Topic][label]] (do not use WikiWord 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 TextFormattingRules 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:Sorted descending
    data/TWiki/PublishWebPlugin.txt,v Plugin topic repository
    data/Publish/WebPublish.txt,v Plugin topic repository
    data/TWiki/PublishWebPlugin.txt Plugin topic
    data/Publish/WebPublish.txt Plugin topic
    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 WebLeftBar:
        • *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.WebPreferences 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: GoodStyle 100%, FormattedSearch 100%, PublishWebPlugin 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: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

-- TWiki:Main.PeterThoeny - 15 Feb 2006

 
  • Suche in Topic-Namen

  • Suche in Topic-Inhalten
This site is powered by the TWiki collaboration platform Powered by Perl