head 1.7; access; symbols; locks; strict; comment @# @; 1.7 date 2009.11.25.03.14.41; author GarryJolleyRogers; state Exp; branches; next 1.6; 1.6 date 2009.11.20.02.35.36; author LeeBelbin; state Exp; branches; next 1.5; 1.5 date 2007.02.26.12.54.05; author RicardoPereira; state Exp; branches; next 1.4; 1.4 date 2006.10.03.09.24.14; author RicardoPereira; state Exp; branches; next 1.3; 1.3 date 2006.02.15.09.19.07; author PeterThoeny; state Exp; branches; next 1.2; 1.2 date 2006.02.14.02.00.47; author PeterThoeny; state Exp; branches; next 1.1; 1.1 date 2006.02.13.23.52.21; author PeterThoeny; state Exp; branches; next ; desc @none @ 1.7 log @none @ text @%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 @ 1.6 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="LeeBelbin" date="1258684536" format="1.1" reprev="1.6" version="1.6"}% d67 1 a67 1 * Set PUBLISHWEBNAME = BDI.SDD.Primer @ 1.5 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="RicardoPereira" date="1172494445" format="1.1" reprev="1.5" version="1.5"}% d67 1 a67 1 * Set PUBLISHWEBNAME = SDD.Primer @ 1.4 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="RicardoPereira" date="1159867454" format="1.1" version="1.4"}% d70 1 a70 1 * Set PUBLISHSKIN = print @ 1.3 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="PeterThoeny" date="1139995147" format="1.0" version="1.3"}% d13 3 a15 3 * 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) d20 15 a34 15 * 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" }%" }% d38 17 a54 17 * =%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 d60 2 a61 2 * One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic: * Set SHORTDESCRIPTION = Maintain a static website collaboratively in a TWiki web d63 2 a64 2 * Debug plugin: (See output in =data/debug.txt=) * Set DEBUG = 0 d66 2 a67 2 * Web to publish: * Set PUBLISHWEBNAME = Publish d69 2 a70 2 * Skin to use to publish: * Set PUBLISHSKIN = print d72 2 a73 2 * Exclude topics from publishing: * Set EXCLUDETOPIC = WebPublish, WebChanges, WebHome, WebIndex, WebLeftBar, WebNotify, WebPreferences, WebRss, WebSearchAdvanced, WebSearch, WebStatistics, WebTopicList d75 2 a76 2 * Home label, used in =%PUBLISHBREADCRUMB%=: * Set HOMELABEL = Home d82 36 a117 36 * 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 d121 1 a121 1 * 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 @ 1.2 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="PeterThoeny" date="1139882447" format="1.0" version="1.2"}% d10 1 a10 1 One web (defined in the PUBLISHWEB 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. d17 1 d19 2 a20 1 * A static HTML page is generated for exery topic saved in the Publish web (unless listed in the EXCLUDETOPIC setting) d24 12 a35 1 * Page layout is based on the skin defined the PUBLISHSKIN setting d51 4 d67 1 a67 1 * Set PUBLISHWEB = Publish d73 1 a73 1 * Set EXCLUDETOPIC = WebChanges, WebHome, WebIndex, WebLeftBar, WebNotify, WebPreferences, WebRss, WebSearchAdvanced, WebSearch, WebStatistics, WebTopicList d87 2 d95 2 a96 2 * =$publishPath= defines the output directory of the static HTML files; defaults to the parent directory of the =twiki/pub= directory; should point to the htdocs root directory * =$attachPath= defaults =_publish=; is relative to =$publishPath= d100 1 a100 1 * Create a new =Publish= web (name indicated by the =PUBLISHWEB= Plugin setting) d107 1 d113 1 a113 1 * Create a new publish skin based on your branding. This [[%TWIKIWEB%.TWikiSkins][TWiki skin]] can be derived from any =twiki/templates/view.*.tmpl= skin file a121 1 * This Plugin version does not yet have a "refresh all" feature to regenerate topics after a skin change d128 1 a128 1 | Plugin Version: | 13 Feb 2006 (V1.000) | d130 1 d143 1 a143 1 -- TWiki:Main.PeterThoeny - 13 Feb 2006 @ 1.1 log @none @ text @d1 1 a1 1 %META:TOPICINFO{author="PeterThoeny" date="1139874741" format="1.0" version="1.1"}% d72 1 d80 2 a81 2 * New =Publish= web: * Create a new =Publish= web @