Tags:
create new tag
view all tags

Copy Topic Tree Plugin

Copy a whole topic tree, including all of its descendants

Introduction

Using this plugin, developers can create TWiki applications that copy a whole topic tree as part of an application workflow. A topic tree is composed of a base topic and all its descendants. Descendants are topics where the parent trail leads back to the base topic.

Destination topics (base topic and descendants) that already exist are not overwritten.

It is possible to set form fields of the destination base topic.

There are three configure options on how to handle topic revisions:

  • {CopyRevisions} = 0 - ignore the topic revisions of the source topic, e.g. start destination topic with revision 1 based on latest revision of source topic.
  • {CopyRevisions} = 1 - copy all revisions, e.g. clone topic.
  • {CopyRevisions} = 2 - copy all revisions and create a new revision on top of it, with author set to person who does the copy topic tree action.

Syntax Rules

This plugin handles the %COPYTOPICTREE{"..."}% variable. The default "..." parameter or action="..." parameter determines the action. Currently only action="copytopictree" is supported.

action="copytopictree" - copy topic tree from source to destination

%COPYTOPICTREE{ action="copytopictree" ... }% supports these parameters:

Parameter Explanation Default
from="..." Topic name or Web.TopicName of source base topic (none, required)
to="..." Topic name or Web.TopicName of destination base topic. The topic can be auto-incremented using AUTOINCn, such as "UID-AUTOINC0001" to get new base topic SID-1235, assuming the existing latest topic is SID-1234. (none, required)
includes="..." RegularExpression of topic names of descendants to include in the copy action. Use this to speed up the search for topics. For example, if all descendant topics start with SID-, specify "^SID-". An empty value will include all descendants. ""
excludes="..." RegularExpression of topic names of descendants to exclude from the copy action. Use this to speed up the search for descendants. ""
substitute="/.../.../" RegularExpression substitution rule on how to change the name of descendant topics. Leave this empty if you copy a tree from one web to another and you want to keep the same names. Format: "/pattern/replacement/". The pattern is a regular expression that identifies text to replace, the replacement indicates what to replace it with. Use pairs of parenthesis in the pattern to remember snippets of text. Those snippets of text can be retrieved in the replacement part with $1, $2, $3, $4, respectively. Examples:
"/$/Backup/" Append Backup to all children topic names, e.g. FooBar becomes FooBarBackup.
"/^SID-(.*)/BID-$1/" All names starting with SID-* are changed to start with BID-*.
""
baseparent="..." Set the parent of the destination base topic. The parent can be auto-incremented using AUTOINCn, such as "PID-AUTOINC001" to get new parent topic PID-124, assuming existing latest topic is PID-123. The parent is not changed if the parameter is empty or not specified. ""
baseformfields="..., ..., ..." Set form fields of the destination base topic. Specify a comma list of form field names, or name=value pairs. The value is taken from the named URL parameter in case only the name is specified. For example, to set the form field Title to "Chief Scientist", and the form field Date to "2019-12-08", use one of these two options:
• parameter baseformfields="Title=Chief Scientist, Date=2019-12-08", or:
• parameter baseformfields="Title, Date" and set URL parameters Title=Chief+Scientist;Date=2019-12-08
Note: Watch out for commas in values. Use the URL parameter option if there is a chance that values contain commas.
""
nomessage="1" Set to 1 to suppress all output. Use this in template topics, such as:
%STARTSECTION{ type="expandvariables" }%%COPYTOPICTREE{ action="%URLPARAM{copyttaction}%" ... nomessage="1" }%%ENDSECTION{ type="expandvariables" }%
"0"

To-Do and Limitations

  • Proper error message handling/display on low level errors.
  • RCS backend is assumed for {CopyRevisions} = 1 and 2 mode on TWiki installations older than TWiki-6.0.
  • Implement feature to optionally set/erase form fields of decendants on copy.
  • Implement feature to view list of descendants before copy action.
  • Create form to interactively copy topic tree.

Plugin Installation & Configuration

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

  • For an automated installation, run the configure script and follow "Find More Extensions" in the in the Extensions section.

  • Or, follow these manual installation steps:
    • Download the ZIP file from the Plugins home (see below).
    • Unzip CopyTopicTreePlugin.zip in your twiki installation directory. Content:
      File: Description:
      data/TWiki/CopyTopicTreePlugin.txt Plugin topic
      lib/TWiki/Plugins/CopyTopicTreePlugin.pm Plugin Perl module
      lib/TWiki/Plugins/CopyTopicTreePlugin/Core.pm Plugin core module
      lib/TWiki/Plugins/CopyTopicTreePlugin/Config.spec Plugin configuration spec
      pub/TWiki/CopyTopicTreePlugin/copy-tree.png Copy tree diagram
    • Set the ownership of the extracted directories and files to the webserver user.
    • Install the dependencies (if any).

  • Plugin configuration and testing:
    • Run the configure script and enable the plugin in the Plugins section.
    • Configure additional plugin settings in the Extensions section. Settings:
      $TWiki::cfg{Plugins}{CopyTopicTreePlugin}{CopyRevisions} # How to copy revisions:
      * Specify 0 to ignore the topic revisions of the source topic, e.g. start destination topic with revision 1 based on latest revision of source topic.
      * Specify 1 to copy all revisions, e.g. to clone topic.
      * Specify 2 to copy all revisions and create a new revision on top of it, with author set to person who does the copy topic tree action.

      $TWiki::cfg{Plugins}{CopyTopicTreePlugin}{Debug} # Debug plugin. See output in data/debug.txt
    • Test if the installation was successful using the example above.

Plugin Info

  • One line description, is shown in the TextFormattingRules topic:
    • Set SHORTDESCRIPTION = Copy a whole topic tree, including all of its descendants
Plugin Author: TWiki:Main.PeterThoeny
Copyright: © 2014-2015 Alba Power Quality Solutions.
© 2014-2015 TWiki:Main.PeterThoeny
© 2014-2015 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Sponsor: Alba Power Quality Solutions
Plugin Version: 2015-05-09
Change History:  
2015-05-09: TWikibug:Item7665: Add copy tree diagram
2015-05-07: TWikibug:Item7665: AUTOINC001 support for baseparent="" and to="" parameters; new nomessage="1" parameter
2014-03-29: TWikibug:Item7468: Add baseparent="" parameter to specify parent of destination base topic; add baseformfields="" parameter to set form fields of the destination base topic
2014-03-28: TWikibug:Item7468: Copy attachments in {CopyRevisions} = 0 mode; fix parent if topic substitution is used
2014-03-27: TWikibug:Item7468: Initial version
TWiki Dependency: $TWiki::Plugins::VERSION 1.2
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
Plugin Benchmark: GoodStyle nn%, FormattedSearch nn%, CopyTopicTreePlugin nn%
Plugin Home: http://TWiki.org/cgi-bin/view/Plugins/CopyTopicTreePlugin
Feedback: http://TWiki.org/cgi-bin/view/Plugins/CopyTopicTreePluginDev
Appraisal: http://TWiki.org/cgi-bin/view/Plugins/CopyTopicTreePluginAppraisal

Related Topics: TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng copy-tree.png r1 manage 61.1 K 2015-06-10 - 05:01 TWikiAdminUser Saved by install script
Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | More topic actions
Topic revision: r2 - 2015-06-17 - TWikiAdminUser
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.CopyTopicTreePlugin.