Embed Topic Plugin

Supports viewing/editing of embeded topics in one page. Unlimited nesting of topics.

Warning:: This plugin is oblivious to permission restrictions. Using it in principle gives read and write access to all topics in one web to any user.

What this is for

There are many ways this plugin could be used, but the most obvious is to modularize large topics. It is like the built-in include feature, but a bit more powerful because you can edit a topic at the same time you are editing the topic it is included in. The plugin has other features that minimize typing and clicking. It works very well if you use TWiki to take notes, as you can take notes in a continuous matter in one page while at the same time creating a structure.

Syntax (summary)

The tags are not case-sensitive. There are two ways of embedding a topic into another:

%EmbedTopic{MyTopic}%

%BeginTopic{MyTopic}%
.. content of MyTopic ..
%End{MyTopic}%

With available shorthands:

%T{MyTopic}

%B{MyTopic}
.. content of MyTopic ..
%E{MyTopic}

Syntax (with examples)

There are two ways to embed a topic, say, MyTopic.

There is first %EmbedTopic{MyTopic}% (or %T{MyTopic}, for short).

If you write %EmbedTopic{MyTopic}% in topic X, the next time you view X, MyTopic will be embedded in it. You will see something like:

MyTopic Content of MyTopic

The next time you edit X, you will see something like this in the textarea:

.. content of X ..

%BeginTopic{MyTopic}%
  .. content of MyTopic ..
%End{MyTopic}%

If you change the content between the two tags, this will change the content of MyTopic.

You can also insert the Begin/End tags directly in a topic (or use the shorthands %B{MyTopic} and %E{MyTopic}. If the embeded topic doesn't exist, it will be created with the content you write. If you enter %EmbedTopic{MyTopic}% and MyTopic does not exist, it will not be created upon saving. It will be created only if you open the embeding topic another time, in which case you will get:

.. content of embeding topic
%BeginTopic{MyTopic}%%End{MyTopic}%

If you save this, an empty MyTopic will be created.

There is also a handy shortcut. If, while using the second way, you write an embedded topic name like this:

%BeginTopic{AnotherTopic::MyTopic}%
.. content of MyTopic ..
%End{AnotherTopic::MyTopic}%

Then the same as above will happen, but in addition MyTopic will be embedded in AnotherTopic. If AnotherTopoc does not exist, it will be created with MyTopic embedded in it. If it already exists, MyTopic will be embedded at the end.

This is useful if you come across a new subtopic which you would like to write about as part of a larger topic, and also to have a link to it somewhere else. Say for instance you are writing something on water. You open a subtopic H2O in your water topic, and you want at the same time to have this H2O subtopic to appear in a topic in which you write down all yours notes in chemistry. Whatever. I use this mainly to insert definitions I create in a list of definitions at the same time I write them down in the topics in which I first use them.

Nested embeds

You can nest embeded topics. See the demo.

Demo

There is a demo included in the archive. I don't seem to have the permission to install it on twiki.org.

Plugin Settings

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

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Supports viewing/editing of embeded topics in one page

• Background of the headings:
  • Set BGCOLOR = #EEEEEE
• Color of the headings' text:
  • Set HDCOLOR = #000000

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.

• Download the ZIP file from the Plugin web (see below)
• Unzip EmbedTopicPlugin.zip in your twiki installation directory. Content:

• Test if the installation was successful:
  • Load topic EmbedTopicPluginDemo in the TWiki web and see if the topics WaterDef and H2ODef are embedded in it.

Plugin Info

Related Topics: TWikiPreferences, TWikiPlugins

-- TWiki:Main/DavidBourget - 23 Dec 2004