ExpandTopicContentPlugin

Expands all macros and expandvariables type sections of a topic and return the raw markup

Usage

This plugin implements the macro EXPANDTOPIC which fetches the content of a given topic and returns the content a bit like an INCLUDE does.

But unlike a normal INCLUDE, the EXPANDTOPIC will first expand the macros in the expanded topics (defined by the expand parameter) either unconditionally or the same way macros are expanded when creating a new topic based on a templatetopic. The result can be entity encoded so the result can be place in a hidden form field, or it can be completely hidden.

The applications for this plugin are

• Enable overwriting existing topics by the expanded content of a template topic. E.g. to create flat static base line document that can be updated from a template topic that contains formatted searches, INCLUDEs, and other macros. This is done by making a creator topic that contains an HTML form that targets the base line topic and contains a hidden input field with .. <input type="hidden" name="text" value="%EXPANDTOPIC{"TemplateTopic" encode="entiry"}% />
• INCLUDE a topic without actually including the content in the rendered output but take advantage of the actions a plugin takes on the included topic. An example can be to include a schedule created by Foswiki:Extensions/TimeCalcPlugin and display selected stored time values in the parent topic. Note that the parent topic cannot use preferences defined in the expanded topic. They are only valid in content taken from the expanded topic.

This plugin also implements the Macro REVISIONATTIME which is useful to enable linking to previous revisions of a topic based on a date. You will often want this when you update the same topic using EXPANDTOPIC from a template topic on a regular basis and need to be able to see earlier versions for a given date.

EXPANDTOPIC{"topic" expand="..." encode="..."} -- include an entire topic with macros expanded

• Returns the topic text from a topic and expands macros as given by parameters. Result can be encoded or hidden.
• Syntax: %EXPANDTOPIC{"topic" expand="all|create|none" encode="none|hide|entity"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "topic"	The topic that is expanded. It can be prefixed by the web name in which case the web parameter is ignorred	Current topic
  web="webname"	The web of the topic to be expanded.	Current web
  expand	expand="all" - all macros are expanded in the scope of the expanded topic. expand="create" - all macros inside sections of type 'expandvariables' are expanded the same way, and according to the same rules as when a template topic is expanded when creating a new topic expand="none" - no macros are expanded (they will be later in the context of the parent topic unless encoded).	"all"
  encode	encode="none" - no encoding is done encode="entity" - the entire expanded topic is entity encoded so it can be contained inside a hidden html text field. encode="hide" - the EXPANDTOPIC returns nothing. This can be quite useful if the expanded topic contains Macros from plugins that either performs an action or defines macros that are accessible from the parent topic	"none"

• Note: Defined preferences in the expanded topic are not defined in the including parent topic. Preferences defined in the parent are however valid in the expanded topic.
• Example: %EXPANDTOPIC{"TemplateTestTemplate" encode="entity" expand="create"}%

REVISIONATTIME{"topic" web="..." time="..."} -- returns the revision of a topic that was valid on a given date

• The macro will return the Foswiki revision as a number, that was valid on the time given to the macro.
• The time can be relative to the current time (always in the past) by giving a negative number in seconds.
• If you asks for a revision on date in the format DD Mmm YYYY without a time one minute the time will be set to one minute to midnight end of the given day.
• If the date given is older than the first revision of the topic, revision 0 is returned.
• Syntax: %REVISIONATTIME{"topic" web="webname" time="time format - see below"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "topic"	The topic that is expanded. It can be prefixed by the web name in which case the web parameter is ignorred	Current topic
  web="webname"	The web of the topic to be expanded.	Current web
  time="time"	Time can be in the formats DD Mmm YYYY, or in epoch (seconds since 1 Jan 1970), or as a negative number in seconds relative to now. If no time is given the current time is assumed.	"0"

• Example - give the revision of 1 week ago : %REVISIONATTIME{"TemplateTestTemplate" time="-604800"}%
• Example of WikiUsers a week ago: %REVISIONATTIME{"Main.WikiUsers" time="-604800"}%
• Example of WikiUsers 01 Jan 2012: %REVISIONATTIME{"Main.WikiUsers" time="01 Jan 2012"}%
• Example of WikiUsers 01 Jan 1990: %REVISIONATTIME{"WikiUsers" web="Main" time="01 Jan 1990"}%
• Example of defaults: %REVISIONATTIME{}%

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Info

Change History:
22 Jan 2016 (1.2)	Fixed the documentation for EXPANDTOPIC (hide, not hidden)
30 Jul 2014 (1.1)	Added the REVISIONATTIME macro which is useful link to earlier revisions of a topic based on a date
09 Dec 2010 (1.0)	Initial release
Dependencies:	None
Home page:	http://foswiki.org/bin/view/Extensions/ExpandTopicContentPlugin