Topic Create Plugin

This Plugin allows you to automatically create topics or attach files at topic save time. This is typically used by TWiki applications to create a set of template based topics.

TOPICCREATE - Automatically Create a Set of TWiki Topics

  • The %TOPICCREATE{}% 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 child topics, each based on a separate template.
  • Syntax: %TOPICCREATE{ <attributes> }%
  • 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 WikiWord (required)
    disable="" Name of the template topic containing this use of TOPICCREATE Any valid topic name (WikiWord) recommended
    parameters="" List of parameters to pass to a child topic to initialize any urlparams. Following syntax:
    <parameter-name>=<parameter-value> followed by any number of parameter name, value pairs separated by &
    No Parameters
  • The action to create the TWiki topic will not occur until one hits the Save Changes button in preview
  • The %TOPICCREATE{}% variable will be removed upon saving of the topic
  • Any attachments that are in the template will also be copied to the new topic
  • %TOPICCREATE% is recursive
  • Write %TOPICCREATE{ template="MyTemplate" topic="%TOPIC%MyNewTopicName" parameters="MyParameterName=MyParameterValue&Hello=Goodbye" }% to create a twiki topic based on another topic MyTemplate with the name %TOPIC%MyNewTopicName. Any %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: %TOPICCRE%NOP%ATE{...}%. The %NOP% gets removed when a topic gets instantiated based on a template.

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: %TOPICATTACH{ <attributes> }%
  • 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 (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 %TOPICATTACH{ fromtopic="SourceTopic" fromfile="Sample.jpg" name="Snoopy.jpg" disable="..."}% to attach Sample.jpg from topic 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.SomeTemplate 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 %TOPICATTACH%.

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, e.g., %TOPICCREATEPLUGIN_SHORTDESCRIPTION%.

NOTE: Do not change the settings here, overload them in the Main.TWikiPreferences. Prefix a setting with TOPICCREATEPLUGIN_, e.g. to overload DEBUG define a TOPICCREATEPLUGIN_DEBUG setting in the Main.TWikiPreferences.

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

  • Debug plugin: (See output in data/debug.txt)
    • Set DEBUG = 0

Known issues & limitations

  • There should be a name argument to rename the topic as it is copied
  • 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 in your twiki installation directory. Content:
    File: Description:
    data/TWiki/TopicCreatePlugin.txt Plugin topic
    data/TWiki/TopicCreatePlugin.txt,v Plugin topic repository
    lib/TWiki/Plugins/ Plugin Perl module
    lib/TWiki/Plugins/TopicCreatePlugin/ Perl utilities
  • Test if the installation was successful (Option A) - pollutes your sandbox, but easiest to try
    • Unzip the 'sandbox test' attachment in your twiki installation directory
    • Go to the topic Sandbox.CreateClientNotebook
    • Enter a name like "MyTest" and press 'create topics'
    • Press "save" on the page that appears
    • This will perform these operations:
      • Create three topics MyTest MyTestEnvironment and MyTestTripLog
      • Copy an attachment from the CreateClientNotebook topic to the created trip log
  • Test if the installation was successful (Option B)
    • Create a test topic called TestTopicCreate with this content:
      %TOPICCREATE{ template="TWiki.WikiWord" topic="%TOPIC%Child" }%
    • After saving TestTopicCreate you should get a new topic TestTopicCreateChild with the content of WikiWord.

Plugin Info

Plugin Author: TWiki:Main.StanleyKnutson, TWiki:Main.PeterThoeny, TWiki:Main.PaulineCheung, TWiki:Main.AndrewRJones
Copyright: © 2005-2011 Peter Thoeny;
© 2009 Andrew Jones;
© 2008-2011 TWiki:TWiki.TWikiContributor
License: GPL (GNU General Public License)
Plugin Version: 2011-07-13
Change History:  
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.024
CPAN Dependencies: none
Other Dependencies: none
Perl Version: 5.005
TWiki:Plugins/Benchmark: GoodStyle nn%, FormattedSearch nn%, TopicCreatePlugin nn%
Plugin Home:

Related Topics: TWikiPreferences, TWikiPlugins

Edit | Attach | Watch | Print version | History: r3 < r2 < r1 | Backlinks | Raw View | More topic actions...
Topic revision: r1 - 2014-03-07 - TWikiAdminUser
  • Edit
  • Attach
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2020 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 at TWiki:TWiki.TopicCreatePlugin.