Publish Web Plugin

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 every topic saved in the %PUBLISHWEBNAME% 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
• Visit %PUBLISHWEBNAME%.WebPublish to re-publish topics without an edit/save cycle

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%. Do not change settings here, but add settings in the publish web's WebPreferences, such as * Set PUBLISHSKIN = mypublish

• 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 = Website

• Skin to use to publish:
  • Set PUBLISHSKIN = website
  • Note: It is also possible to specify a publish skin on a per page basis. Define a TWiki Form with a form field called PublishSkin. It can be of any type, but a select dropdown box is probably most convenient.

• Exclude topics from publishing:
  • Set EXCLUDETOPIC = WebAtom, WebChanges, WebCreateNewTopic, WebHome, WebIndex, WebLeftBar, WebNotify, WebPublish, WebPreferences, WebRss, WebSearchAdvanced, WebSearch, WebStatistics, WebTopicList, WebTopMenu, WebTopicCreator, WebTopicEditTemplate

• 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/Website/WebPublish.txt	Publish page topic
  lib/TWiki/Plugins/PublishWebPlugin.pm	Plugin Perl module
  templates/view.website.tmpl	Demo publish skin

• Configure and test the installated Plugin:
  • Run the configure script to enable the Plugin
  • Configuration on shell level:
    • Add/customize these twiki/lib/LocalSite.cfg settings:
      • $TWiki::cfg{Plugins}{PublishWebPlugin}{TemplatePath}: Template path where skin files are located.
        • If empty or omitted: the twiki/templates directory is assumed; normal TWikiTemplates search path applies, e.g. for a PUBLISHSKIN = website setting, a twiki/templates/view.website.tmpl template file is assumed
        • If specified: Must be an absolute path; skin is assumed to be an html page at that location, e.g. for a PUBLISHSKIN = website setting, a $TWiki::cfg{Plugins}{PublishWebPlugin}{TemplatePath}/website.html file is referenced
      • $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishPath}: Path where the plugin places the generated html files.
        • Specify an absolute or relative path to the Apache HTML document root
        • If relative, path is relative to twiki/pub, such as '../../html'
      • $TWiki::cfg{Plugins}{PublishWebPlugin}{AttachPath}: Path where the plugin places images and other topic attachments.
        • Must be relative to $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishPath}, default is '_publish'
      • $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishUrlPath}: URL path that corresponds to {PublishPath} directory. Leave empty if it is the HTML document root.
      • Example: $TWiki::cfg{Plugins}{PublishWebPlugin}{TemplatePath} = ''; $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishPath} = '/path/to/apache/html'; $TWiki::cfg{Plugins}{PublishWebPlugin}{AttachPath} = '_publish'; $TWiki::cfg{Plugins}{PublishWebPlugin}{PublishUrlPath} = '';
    • Create the directory indicated in the {PublishPath} setting if needed
    • Create the directory indicated in the {AttachPath} setting (relative to {PublishPath})
    • Change the permission of directories indicated by {PublishPath} and {AttachPath} to be writable by the cgi user (such as user nobody on RedHat Linux)
  • Create a new TWiki web for website publishing:
    • Create a new Website web (name indicated by the PUBLISHWEBNAME Plugin setting)
    • In Website.WebPreferences of that web, set the NOAUTOLINK setting to on
    • For convenience, add these links to Website.WebTopMenu (or Website.WebLeftBar if you use the PatternSkin):

         * [[%BASEWEB%.WebHome][Publishing %ICON{menu-down}%]]
            * [[%BASEWEB%.Index][Home page topic]]
            * <a href="%PUBLISHWEB{"publishurlpath"}%/index.html">index.html</a>
            * <a href="%PUBLISHWEB{"publishurlpath"}%/%PUBLISHWEB{topicurl}%">%PUBLISHWEB{topicurl}%</a>
            * [[%SCRIPTURL{view}%/%BASEWEB%/WebPublish?action=publish;ptopic=%BASETOPIC%][Re-publish this topic]]
            * [[%SYSTEMWEB%.PublishWebPlugin][PublishWebPlugin]]
            

    • Create a Sandbox_page topic in that web
    • This should generate a sandbox_page.html page on topic save
    • Create Index topic and other topics
• Publish skin:
  • Create a new publish skin that matches the look of your website. The TWiki skin can be derived from any twiki/templates/view.*.tmpl skin file, or can be created from scratch. This plugin contains a bare bone demo skin called website located at twiki/templates/view/website.tmpl
  • 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 WebPreferences settings, such as %PUBLISH_SITE%, %PUBLISH_LOGO%, etc.
  • Activate the new skin with a WebPreferences settings, such as * Set PUBLISHWEBPLUGIN_PUBLISHSKIN = mypublish
  • You can have multiple publish skins; see note in the PUBLISHSKIN plugin setting above.

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

Related Topics: %PUBLISHWEBNAME%.WebPublish, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences