Attach Content Plugin

Saves dynamic topic text to an attachment

Overview

This plugin puts any text between a %STARTATTACH{"filename"}% and %ENDATTACH% into an attachment with the given filename.

Pass filename, topic, web or comment as parameters.

The current version only refreshes the attachment when the topic is saved. Obviously this means that the attachment can get out of synch if, for example, it explicitly or implicitly refers to other topics.

This plugin is written specifically to be able to put css into topic(s) and still be able to have efficient stylesheets: i.e., without the overhead of Foswiki processing. The feature can be used for many other things where you want Foswiki to generate a plain text file a smart way.
For example: write a SEARCH in a topic and save the search results to an XML file. The XML data can be used for efficient look-up.

Syntax Rules

Write:

%STARTATTACH{"filename"}%
content-to-be-saved
%ENDATTACH%

You can pass a number of parameters:

Parameters

Parameter	Description	Default	Example
topic	Topic to save the attachment to.	- (the current topic is used)	topic="WebHome"
web	Web where the save topic is located.	- (the current Web is used)	web="Main"
comment	Attachment comment text.	the default {AttachmentComment} text in configure	comment="User data as of %DATE%"
hide	Use hide="on" to hide the attachment in normal topic view.	off	hide="on"
keeppars	Keep paragraph <p /> tags, <nop> tags, and square bracket type links	the default {KeepPars} text in configure	keeppars="on"
hidecontent	Hide content from view.	- (the "content-to-be-saved" is visible)	hidecontent="on"

Examples

Adding a Save button to the topic.

These examples add a "Save" button to force a save of the topic and update the attachment. Note that with versions of Foswiki since 1.0.4, it is not possible to initiate a save from a simple HTML link - which causes a "GET". Save can only be initiated from a POST operation done using a HTML form. The following sample form is used to create the button:

<form action="%SCRIPTURL{save}%/%WEB%/%TOPIC%" method="post">
    <input type="hidden" name="action" value="action_save=1" />
    <input type="submit" class="foswikiButton" value="Save the topic" />
</form>

Creating a color scheme

See: PatternSkinColorSettings. This topic uses AttachContentPlugin to write a CSS file for colors. Color values are set dynamically in the topic. On topic save the CSS file is attached to the topic and can be referred to using variable USERCOLORSURL.

User data XML

This will generate an attachment to this topic. Content will be a xml file of users registered to this installation.

<?xml version="1.0" encoding="ISO-8859-1"?>
<users>
%SEARCH{ "[F]irstName.*value=.*()" web="%MAINWEB%" type="regex" nonoise="on" excludetopic="UserForm,ProjectContributor,WikiGuest,UnknownUser" format="<user><firstname><![CDATA[$formfield(FirstName)]]></firstname><lastname><![CDATA[$formfield(LastName)]]></lastname><url><![CDATA[%SCRIPTURL{view}%/%WEB%/$topic]]></url></user>" }%
</users>

Note that the STARTATTACH and ENDATTACH macros are not shown, so the actual content of the above "live" Attach Content block (spaced out for easier readability) is:

%STARTATTACH{"userdata.xml" comment="User data as of %DATE%"}%
<?xml version="1.0" encoding="ISO-8859-1"?>
<users>
%SEARCH{ "[F]irstName.*value=.*()" web="%MAINWEB%" type="regex" nonoise="on" 
   excludetopic="UserForm,ProjectContributor,WikiGuest,UnknownUser" 
   format="<user><firstname><![CDATA[$formfield(FirstName)]]></firstname>
               <lastname><![CDATA[$formfield(LastName)]]></lastname>
               <url><![CDATA[%SCRIPTURL{view}%/%WEB%/$topic]]></url>
           </user>"
 }%
</users>
%ENDATTACH%

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. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)

cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> 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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.

Settings

After installation, configure this plugin by changing settings in configure.

Dependencies

Name	Version	Description
File::Temp	>0	Required
Digest::MD5	>=2.36	Required

Change History

19 Dec 2024	improve performance by only calling expandCommonVariables when there is a chance to do so
14 Jan 2024	Foswikitask:Item15244 - code improvements such as use of strict and warnings in perl
03 Feb 2021	Foswikitask:Item15015 - fixed escape the removal of bracket links
13 Jun 2016	Foswikitask:Item14095 - fixed saving attachments with unicode chars in it
03 May 2016	Foswikitask:Item14062 - only attach content when it actually changed; Foswikitask:Item11782 - make sure the file is proper utf8 on unicode Foswiki
25 Sep 2015	Foswikitask:Item13747 - fixed unescaped left braces; use CPAN:File::Temp for temporary files; check access rights before saving auto-created attachment to prevent an unnecessary error condition; check access rights before saving auto-created attachment to prevent an unnecessary error condition; remove SVN tags to make plugin releasable again; use floats for version tags; normalize web,topic params to STARTATTACH; remove use of deprecated saveTopicText api
21 Aug 2010	Created stub handlers _startAttach and _endAttach.
25 May 2010	Foswikitask:Item8579 - Fix example to resolve save errors
31 Aug 2009	Arthur Clemens: Added param hidecontent. Moved plugin settings to configure.
23 Nov 2008	Foswiki compatible.
16 Apr 2007	Kenneth Lavrsen: Add added keeppars parameter. Settings change to being plugin settings only. Removal of plugin tags fixed so text between is still visible.
15 Apr 2007	Arthur Clemens: added parameters web, topic, comment and hide. Plugin tags are removed from view. Added configurable default comment.
19 Oct 2006	Kenneth Lavrsen: Fixed major security issue. Original version allowed /../ in the filename so files could be stored everywhere; Plugin now cleans up the its work area and no longer leaves temporary files; Temporary filenames made pseudo random to avoid race condition; Plugin now also removed nops and TML square bracket links; Attachment is no longer saved when uploading other files and changing attributes.
09 Feb 2006	Initial version