/
TopicCreatePlugin.txt
92 lines (72 loc) · 6.75 KB
/
TopicCreatePlugin.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
%META:TOPICINFO{author="ProjectContributor" date="1132609510" format="1.1" version="$Rev: 3036 $"}%
---+!! Topic Create Plugin
This Plugin allows you to automatically create topics or attach files at topic save time. This is typically used by Foswiki applications to create a set of template based topics.
%TOC%
---++ <nop>TOPICCREATE - Automatically Create a Set of Foswiki Topics
* The =%<nop>TOPICCREATE{}%= Macro 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: =%<nop>TOPICCREATE{ <attributes> }%=
* Attributes recognized
| *Attribute* | *Meaning* | *Valid input* | *Default* |
| =template=""= | Name of Foswiki topic to be used as template | Any valid Foswiki topic | (required) |
| =topic=""= | Name of new Foswiki topic to create | Any valid <nop>WikiWord | (required) |
| =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% =<parameter-name>=<parameter-value>= followed by any number of parameter name, value pairs separated by =&= | No Parameters |
* The action to create the Foswiki 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 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 foswiki 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{ <attributes> }%=
* Attributes recognized
| *Attribute* | *Meaning* | *Valid input* | *Default* |
| =fromtopic=""= | Topic (or Web.Topic) that contains the attachment | Any valid Foswiki 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 =Foswiki<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%=.
Limitations/TODO:
* 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.
---++ Plugin Settings
Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop><plugin>_<setting>%==, i.e. ==%<nop>TOPICCREATEPLUGIN_SHORTDESCRIPTION%==
* One line description, is shown in the %SYSTEMWEB%.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
* This Plugin is Unix specific and depends on the Unix utilities =cp= and =mkdir=.
* For safety reasons, the path to the utilities is hardcoded in the Plugin module. The path might need to be changed depending on your environment.
* 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 Foswiki site.
---++ Installation Instructions
%$INSTALL_INSTRUCTIONS%
---++ Plugin Files
| *File:* | *Description:* |
%$MANIFEST%
---++ Plugin Info
| Plugin Author(s): | Foswiki:Main.AndrewJones |
| Previous Author(s): | TWiki:Main.StanleyKnutson, TWiki:Main.PeterThoeny, TWiki:Main.PaulineCheung |
| Copyright: | © 2009, Andrew Jones, © 2005 - 2006, Peter Thoeny |
| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
| Plugin Release: | %$RELEASE% |
| Plugin Version: | %$VERSION% |
| Change History: | <!-- versions below in reverse order --> |
| 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 |
| Dependencies: | %$DEPENDENCIES% |
| Other Dependencies: | Unix utilities =cp= and =mkdir= |
| License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
| Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |
| Support: | http://foswiki.org/Support/%TOPIC% |
__Related Topics:__ %SYSTEMWEB%.DefaultPreferences, %USERSWEB%.SitePreferences, [[%SYSTEMWEB%.Plugins][Plugins]]