%META:TOPICINFO{author="TWikiContributor" date="1435136042" format="1.1" version="$Rev$"}%
---+!! Copy Topic Tree Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/CopyTopicTreePlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/CopyTopicTreePluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky>
<div style="float:right; width: 350px; margin:0 0 20px 20px;">
<div style="background-color:#EBEEF0; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
<div style="padding: 10px 10px;">
<img src="%ATTACHURLPATH%/copy-tree.png" alt="copy-tree.png" width="350" height="186" />
</div>
</div>
</sticky>

%SHORTDESCRIPTION%

---++ 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 =%<nop>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

=%<nop>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 ="SID-AUTOINC0001"= to get new base topic =SID-1235=, assuming the existing latest topic is =SID-1234=. | (none, required) |
| =includes="..."= | %SYSTEMWEB%.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="..."= | %SYSTEMWEB%.RegularExpression of topic names of descendants to exclude from the copy action. Use this to speed up the search for descendants. | =""= |
| <div style="white-space: nowrap;"> =substitute="/.../.../"= </div> | %SYSTEMWEB%.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. Tokens =$fromBaseTopic= and =$toBaseTopic= in the pattern and replacement part resolve to the source base topic name and destination base topic name, respectively. Examples: %BB% ="/$/Backup/"= - append =Backup= to all children topic names, e.g. !FooBar becomes !FooBarBackup. %BB% ="/^SID-(.*)/BID-$1/"= - all names starting with =SID-*= are changed to start with =BID-*=. %BB% ="/^($fromBaseTopic)/$toBaseTopic/"= - all children's base name is changed, such as =SID-0001-0123= to =SID-0005-0123= assuming destination base topic is =SID-0005= | =""= |
| =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 "%SERVERTIME{$year-$mo-$day}%", use one of these two options: %BB% parameter =baseformfields="Title=Chief Scientist, Date=%SERVERTIME{$year-$mo-$day}%"=, or: %BB% parameter =baseformfields="Title, Date"= and set URL parameters =Title=Chief+Scientist;Date=%SERVERTIME{$year-$mo-$day}%= %BR% _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:%BR% =%<nop>STARTSECTION{ type="expandvariables" }%%<nop>COPYTOPICTREE{ action="%<nop>URLPARAM{copyttaction}%" ... nomessage="1" }%%<nop>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 &amp; 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.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.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 [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Configure additional plugin settings in the __Extensions__ section. Settings:
        %BR% =$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. |
        %BR% =$TWiki::cfg{Plugins}{CopyTopicTreePlugin}{Debug}= # Debug plugin. See output in data/debug.txt
      * Test if the installation was successful using the example above.

%ENDTWISTY%

---++ Plugin Info

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Copy a whole topic tree, including all of its descendants
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2014-2015 Alba Power Quality Solutions. %BR% &copy; 2014-2015 TWiki:Main.PeterThoeny %BR% &copy; 2014-2015 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Sponsor: | [[http://www.powerqualitynetwork.com/][Alba Power Quality Solutions]] |
|  Plugin Version: | 2015-05-24 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2015-05-24: | TWikibug:Item7665: Add $fromBaseTopic and $toBaseTopic tokens to substitute parameter |
|  2015-05-18: | TWikibug:Item7665: Doc fix |
|  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 |
|  [[TWiki:Plugins.Benchmark][Plugin Benchmark]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% 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:__ %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences

%META:FILEATTACHMENT{name="copy-tree.png" attachment="copy-tree.png" attr="h" comment="" date="1433911650" path="copy-tree.png" size="62558" user="TWikiContributor" version="1"}%
