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

Install AttachContentPlugin to be able to save this topic. On saving, an attachment will be created to this topic.

%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%

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

14 Jan 2024 (2.43)	Foswikitask:Item15244 - code improvements such as use of strict and warnings in perl
03 Feb 2021 (2.42)	Foswikitask:Item15015 - fixed escape the removal of bracket links
13 Jun 2016 (2.41)	Foswikitask:Item14095 - fixed saving attachments with unicode chars in it
03 May 2016 (2.40)	Foswikitask:Item14062 - only attach content when it actually changed; Foswikitask:Item11782 - make sure the file is proper utf8 on unicode Foswiki
25 Sep 2015 (2.34)	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 (2.33)	Created stub handlers _startAttach and _endAttach.
25 May 2010 (2.32)	Foswikitask:Item8579 - Fix example to resolve save errors
31 Aug 2009 (2.3)	Arthur Clemens: Added param hidecontent. Moved plugin settings to configure.
23 Nov 2008 (2.21)	Foswiki compatible.
16 Apr 2007 (2.20)	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 (2.10)	Arthur Clemens: added parameters web, topic, comment and hide. Plugin tags are removed from view. Added configurable default comment.
19 Oct 2006 (2.0)	Foswiki:Main.KennethLavrsen 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 (1.0)	Initial version