(r2) TopicCreatePlugin < TWiki

TWiki Web>TopicCreatePlugin (revision 2) (raw view)
---+!! Topic Create Plugin 
<!--
   Contributions to this plugin are appreciated. Please update the plugin page
   at http://twiki.org/cgi-bin/view/TopicCreatePlugins/Plugin or provide feedback
   at http://twiki.org/cgi-bin/view/TopicCreatePlugins/PluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
This Plugin allows you to automatically create new topics or attach files at topic save time. This is typically used by TWiki applications to create a set of topics based on different templates.

---++ <nop>TOPICCREATE!! - Automatically Create a Set of TWiki Topics

   * The =%<nop>TOPICCREATE{}%= <nop>TWikiVariable is useful for creating topics based on templates.
   * Example scenario: You have a notebook application where users can create new notebooks based on a notebook template topic. Each time a user creates a new notebook you would like to create a set of children topics, each based on a different template.
   * Syntax: =%<nop>TOPICCREATE{ &lt;attributes&gt; }%=
   * Attributes recognized:
     | *Attribute* | *Meaning* | *Valid input* | *Default* |
     | =template=""= | Name of TWiki topic to be used as template | Any valid TWiki topic | (required) |
     | =topic=""= | Name of new TWiki topic to create | Any valid <nop>WikiWord | (required) |
     | =parent=""= | Name of parent topic | Any valid <nop>WikiWord | (parent of template topic) |
     | =disable=""= | Name of the template topic containing this use of TOPICCREATE | Any valid topic name (<nop>WikiWord) | _recommended_ |
     | =parameters=""= | List of parameters to pass to a child topic to initialize any urlparams.| Following syntax:%BR% =&lt;parameter-name&gt;=&lt;parameter-value&gt;= followed by any number of parameter name, value pairs separated by =&= or =;= | No Parameters |
   * The action to create the TWiki topic will not occur until one hits the =Save Changes= button in preview.
   * The =%<nop>TOPICCREATE{}%= variable will be removed upon saving of the topic.
   * Any attachments that are in the =template= will also be copied over to the new topic.
   * =%<nop>TOPICCREATE%= is recursive
   * Write =%<nop>TOPICCREATE{ template="<nop>MyTemplate" topic="<nop>%<nop>TOPIC%MyNewTopicName" parameters="MyParameterName=MyParameterValue&Hello=Goodbye" }%= to create a twiki topic based on another topic =<nop>MyTemplate= with the name =<nop>%<nop>TOPIC%MyNewTopicName=. Any =%<nop>URLPARAM{}%=  with the name =MyParameterName= and =Hello= present in =MyTemplate= will be replaced with =MyParameterValue= and =Goodbye=.
   * To prevent the action from happening in your template topic you should either include the =disable= argument, or escape it: =%<nop>TOPICCRE%<nop>NOP%ATE{...}%=. The =%<nop>NOP%= gets removed when a topic gets instantiated based on a template.

---++ <nop>TOPICATTACH!! - Automatically Copy Attachments to a Topic 

   * Example scenario: You have a template topic and would like to attach a file whose's content or name is determined by URL parameters at topic creation time.  This is usually done for a topic that was just created via TOPICCREATE as described above.
   * Syntax: =%<nop>TOPICATTACH{ &lt;attributes&gt; }%=
   * Attributes recognized:
     | *Attribute* | *Meaning* | *Valid input* | *Default* |
     | =fromtopic=""= | Topic (or Web.Topic) that contains the attachment  | Any valid TWiki topic | (required) |
     | =fromfile=""= | The attachment to copy from | Any attached file from =fromtopic= | (required) |
     | =disable=""= | Name of the template topic containing this use of TOPICATTACH | Any valid topic name (<nop>WikiWord) | (required) |
     | =comment=""= | Comment to appear for the attachment within this topic, replacing the comment that was in the =fromtopic= | a one line string | {omit parameter if no change desired} |
   * Write =%<nop>TOPICATTACH{ fromtopic="<nop>SourceTopic" fromfile="Sample.jpg" name="Snoopy.jpg" disable="..."}%= to attach =Sample.jpg= from topic =<nop>SourceTopic= as =Snoopy.jpg=.
   * The parameter value comment is used to change the comment (description) that shows for the topic in the table of attachments.
   * The "hidden" attribute of the topic is removed: the attachment can be hidden in the =fromtopic= if desired.
   * The =fromtopic= can specify a different web if desired.  For example =TWiki<nop>.Some<nop>Template= would be valid as a =fromtopic=.
   * To prevent the action from happening in your template topic you *must* provide the =disable= parameter with the topic name containing the =%<nop>TOPICATTACH%=.

<!--
TOPICPATCH is not yet working properly in this release.

3. Replace a form fields within a Topic 

   * Example scenario: You would like to modify the value of a form field based on a URL input parameter.  This is usually done for a topic that was just created via TOPICCREATE as described above.
   * Syntax: =%<nop>TOPICPATCH{ &lt;attributes&gt; }%=
   * Attributes recognized
     | *Attribute* | *Meaning* | *Valid input* | *Default* |
     | =topic=""= | Topic to be modified  | Any valid TWiki topic | (required) |
     | =action=""= | Either "replace" or "append" to specify the action to do to a form field value in =topic= | (required) |
     | =formfield=""= | Form Field Name to be modified | value | (required) |
-->

---++ Known issues & limitations

   * The =TOPICATTACH= must be in the 'top level' topic being saved by a =TOPICCREATE=.  It can not be in a recursive/subordinate topic invoked by the TOPICCREATE.
   * Precautions have been taken to make this Plugin safe. It does not have ANY WARRANTY, does not even have the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. It is up to the administrator to decide if this Plugin is safe for a public TWiki site.

---++ 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 server where TWiki is running. 

   * Run configure to install the plugin, then enable the plugin in configure.
   * Alternatively, download the ZIP file from the Plugin web (see below) and install the plugin manually:
   * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
     | ==lib/TWiki/Plugins/%TOPIC%/Func.pm== | Plugin core functionality |
   * Test if the installation was successful:
      * Create a test topic called =TestTopicCreate<nop>= with this content: %BR%
        =%<nop>TOPICCREATE{ template="%SYSTEMWEB%.WikiWord" topic="<nop>%<nop>TOPIC%Child" }%=
      * After saving =TestTopicCreate= you should get a new topic =TestTopicCreateChild= with the content of %SYSTEMWEB%.WikiWord.

---++ Plugin Info

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Automatically create a set of topics and attachments at topic save time

|  Plugin Author: | TWiki:Main.StanleyKnutson, TWiki:Main.PeterThoeny, TWiki:Main.PaulineCheung, TWiki:Main.AndrewRJones |
|  Copyright: | &copy; 2005-2014 Peter Thoeny; <br /> &copy; 2009 Andrew Jones; <br /> &copy; 2008-2014 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]] for 2014-11-07 version |
|  Plugin Version: | 2014-11-07 |
|  Change&nbsp;History: | <!-- versions below in reverse order -->&nbsp; |
|  2014-11-07: | TWikibug:Item7586: Expand variables on topic creation; create new topics across webs; new parent parameter; code cleanup |
|  2011-07-13: | TWikibug:Item6725: Change global package variables from "use vars" to "our" |
|  25 Oct 2009: | TWikibug:Item6357 - removed dependency on Unix utilities =cp= and =mkdir=, should now work on any OS that TWiki does; removed depreciated API calls -- TWiki:Main.AndrewRJones |
|  11686 | TWikibug:Item2956 - freeze !TWikiRelease04x00 and copy it to new branch MAIN |
|  10613 | TWikibug:Item2473 - files in pub and data directories shouldn't be marked executable in svn (Ordnung muss sein) |
|  7960 | TWikibug:Item1238 - plugins cleanup: added BuildContrib support/infrastructure |
|  7585 | TWikibug:Item1016 - initial import of TopicCreatePlugin (thanks TWiki:Main.StanleyKnutson and others) |
|  21 Nov 2005: | Initial TOPICCATTACH |
|  30 Apr 2005: | Initial version |
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.2 |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.008 |
|  [[TWiki:Plugins/Benchmark][Plugin Benchmark]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  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:__ %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
Topic revision: r2 - 21 Oct 2019 - TWikiAdminUser
Account
- Log In
- Register User
~~Edit~~
~~Attach~~
Copyright © 1999-2025 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.TopicCreatePlugin.