%META:TOPICINFO{author="GarryJolleyRogers" date="1259118881" format="1.1" version="1.7"}% ---+!! 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. %TOC% ---++ 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 (%TWIKIWEB%.WikiWord names are possible too) * All links should be defined as double square bracket links, e.g. =[[Topic]]= or =[[Topic][label]]= (do not use %TWIKIWEB%.WikiWord links) #PublishProcess ---+++ Publish process
* A static HTML page is generated for exery 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 * Topics can be re-published without an edit/save cycle.%BR% Topic: [[%SCRIPTURL%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%#PublishProcess][Clear]]%BR% %PUBLISHWEB{ "%URLPARAM{ "action" }%" topic="%URLPARAM{ "tname" }%" }% ---+++ 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 %TWIKIWEB%.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 = BDI.SDD_.Primer * Skin to use to publish: * Set PUBLISHSKIN = static * Exclude topics from publishing: * Set EXCLUDETOPIC = WebPublish, WebChanges, WebHome, WebIndex, WebLeftBar, WebNotify, WebPreferences, WebAtom, WebRss, WebSearchAdvanced, WebSearch, WebStatistics, WebTopicList * 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 ==%TOPIC%.zip== in your twiki installation directory. Content: | *File:* | *Description:* | | ==data/TWiki/%TOPIC%.txt== | Plugin topic | | ==data/TWiki/%TOPIC%.txt,v== | Plugin topic repository | | ==data/Publish/WebPublish.txt== | Plugin topic | | ==data/Publish/WebPublish.txt,v== | Plugin topic repository | | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module | * Configure and test the installated Plugin: * TWiki 4.0 and up: Run the [[%SCRIPTURL%/configure%SCRIPTSUFFIX%][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/%TOPIC%.pm=: For security, the output directories are defined in the =%TOPIC%.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?\%BR%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 [[%TWIKIWEB%.TWikiSkins][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 ([[http://www.gnu.org/copyleft/gpl.html][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 | | [[TWiki:Plugins/Benchmark][Benchmarks]]: | %TWIKIWEB%.GoodStyle 100%, %TWIKIWEB%.FormattedSearch 100%, %TOPIC% 99% | | Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% | | Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev | | Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal | __Related Topics:__ %TWIKIWEB%.TWikiPlugins, %TWIKIWEB%.DeveloperDocumentationCategory, %TWIKIWEB%.AdminDocumentationCategory, %TWIKIWEB%.TWikiPreferences -- TWiki:Main.PeterThoeny - 15 Feb 2006