create new tag
, view all tags

What Are Transclusions? How to Use Them in TWiki Applications

2012-05-27 - 18:26:21 by PeterThoeny in Development
Transclusion diagram
Transclusion is the inclusion of a document or part of a document into another document by reference.

For example, press releases have an about section. Rather than copying the about section over and over again, a transclusion embodies a modular design by allowing the about text to be stored only once and included in the press releases. Ted Nelson (who also coined the words "hypertext" and "hypermedia") introduced the term "transclusion" in his 1982 book, Literary Machines.

Parameterization allows certain portions or subsections of a transcluded text to be modified dynamically based on parameters passed into the included text. For example, when including the about text of a press release, a version number parameter can specify what version of the about text to transclude.

Transclusions can be useful when authoring content in TWiki. Let's use the press release as a how-to example. First we create a page called PressReleaseAboutText with the following content, shown here in raw text format:

---+ Press Release About Text
The text between the horizontal rules gets included by all PressReleases.
*About TWiki.org:*
TWiki.org was founded in 1998 as an open source enterprise wiki. The community is committed to 
building an easy to use enterprise wiki and enterprise collaboration platform that scales to a million 
pages and 10K+ users. Users without programming skills can create web applications. TWiki has 
been downloaded over 500,000 times and is used daily by millions of people in over 100 countries.

The %STARTINCLUDE% and %STOPINCLUDE% are markers that tell what to include. The whole pages is included in a transclusion if they are missing.

Now that we have defined the about text, we can use transclusion to embed it in any press release as follows:

---+ Press Release: Bread Slicer 2.0 Available
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut 
labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco 
laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
voluptate velit esse cillum dolore eu fugiat nulla pariatur.

%INCLUDE{ "PressReleaseAboutText" }%

That's it in the simplest form: The %INCLUDE{...}% includes the about text. Now, whenever you update the about text, all press releases get updated as well. However, if you want to avoid including always the latest version you can include a specific version, such as
%INCLUDE{ "PressReleaseAboutText" rev="3" }%.

At times you want to change part of the included text dynamically. For example, the contact person might change based on the press release. This can be done with a parameterized include. That is, you can add additional named parameter(s) to the include to pass along the dynamic content:

%INCLUDE{ "PressReleaseAboutText" contact="Jimmy Neutron, jimmy@example.com" }%

In the about text you can use the named parameter as a variable:

*About TWiki.org:*
For more information: %contact%

The parameter can be made optional if you specify a default for the variable, such as: %contact{ default="Marketing, info@example.com" }.

Take advantage of transclusions when building TWiki applications, e.g. when using the TWiki platform as a Structured Wiki. You can define your own GUI widget library using a topic with named sections, which then serves as a component library to build your TWiki applications. Here are the steps:

  1. Create a topic that serves as a widget library.
  2. Create widgets in that topic, such as alert boxes, submit forms, user queries, etc. Widgets are defined using named sections and may process parameters.
  3. Now you can use a widget in any topic by including the widget library topic and specifying the section name of the widget.

As an exercise, lets define an alert box in a topic called WidgetLibrary:

<div style="border-color:#FF9933; border-style:solid; border-width:thin; width:85%; margin: 0 auto; box-shadow: 3px 3px 6px #ccc;">
<table cellpadding="5" width="100%" cellspacing="0" cellpadding="12" border="0">
<tr bgcolor="#FFBB55">
<td valign="top" width="16"><img src="%ICONURL{warning}%" width="16" height="16" align="absmiddle" alt="" border="0"></td>
<td><b> %title{ default="TWiki Alert" }% </b></td>
</tr><tr bgcolor="#FFCC66">
<td> %message{ default="This is the message" }% </td>

This widget handles two variables, named %title% and %message%, respectively. To use the alert box in any topic, write:

%INCLUDE{ "WidgetLibrary" section="AlertBox" title="Transclusion" message="The sky is the limit!" }%=

Which produces this alert box:

  The sky is the limit!

More sophisticated widgets can be built. Here is an example of a member list widget I did for a client. Each little box is a section that can be included, such as:

Member list example
%INCLUDE{ "UserReports" section="UserBox130px"

Including another section shows a user list:

%INCLUDE{ "UserReports" section="UserBoxesList130px"
 users="Dale Plummer, DavidNixon, ..."

The users="..." parameter is typically done dynamically with a search. Technically, the "UserBoxesList130px" section in turn includes the "UserBox130px" in a loop, e.g. includes can be nested as needed.

What widgets do you have in mind? Use your imagination, the sky is the limit!

-- PeterThoeny - founder of TWiki.org




Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r2 - 2012-05-29 - PeterThoeny

Twitter Delicious Facebook Digg Google Bookmarks E-mail LinkedIn Reddit StumbleUpon    
  • Help
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.