Module name TWiki::Func.pm FuncDotPm Location TWIKIROOT/lib/TWiki/Func.pm Summary Stable interface from Plugins to TWiki Primary Author PeterThoeny CVS history CVS:lib/TWiki/Func.pm CVS alpha CVSget:lib/TWiki/Func.pm Contributing authors (see CVS History) Is Class NO First Release twiki-20010901-release, TWikiRelease01Dec2001

File Hierarchy   TWIKIROOT   lib   TWiki   Func.pm

Purpose

To isolate the inner workings of TWiki from the render plugin modules that use it. This module is an official list of routines whose functionality and interface are stable; no other subs in TWiki should be used by the plugins.

Used by

This module is primarily used by the plugins. See 'Purpose', above.

Please see CodevDocumentationProject and CodevDocumentationProjectDev for comments on the format of these pages.

TWiki::Func Module Documentation

%PERLDOC{"TWiki::Func"}%

Contributors:
-- MartinCleaver - 23 Jun 2002
-- PeterThoeny - 01 Feb 2004

Discussions

Can we get AppendTextToTopic added to this API? This would facilitate mail in and more robust comment handling.

-- MartinCleaver - 23 Jun 2002

Added %PERLDOC{...}% to pull the doc from the TWiki/Func.pm Perl module. Removed PublicMethods and PrivateMethods section since they are no longer needed.

-- PeterThoeny - 01 Feb 2004

traceExec

It would be nice if there existed a traceExec function through which plugins should make calls to external programs. This would ease the porting effort and provide useful information for system administrators who wanted to ensure external dependencies were fulfilled.

getPluginPreferencesValue

I propose that a routine be added so to allow a plugin to retreive its own values without having to pass the name of its own plugin.

i.e. currently one has to write:

    $debug = TWiki::Func::getPreferencesFlag( "\U$pluginName\E_DEBUG" );

the "\U$pluginName\E_ bit is ugly and prone to user error.

-- MartinCleaver - 26 Mar 2004

I think both of your suggestions are good ideas, and I just committed an implementation of the second to CVS.

-- WalterMundt - 27 Mar 2004

Useful. To make it consistent, add also a getPluginPreferencesFlag()

-- PeterThoeny - 27 Mar 2004

Given that the correct way to write Web/Topic reference is Web.Topic, how best should I get the attachment dir for a given web.topic name? It seems silly to write:

$webTopic = "Web.Topic"; 
$webTopic =~ s!\.!/!;  # <- surely everyone is going to have to do this?
$dir = getPubDir().$webTopic;

-- MartinCleaver - 23 Aug 2004

setPreferencesValue

I propose to implement a function setPreferencesValue( $key, $value ) which sets a $value for the Preference Variable $key in the current topic. Although I could do it (and have done it) using low-level routines from prefs.pm, it would be a better style to have this routine in the Func module.

-- JChristophFuchs - 15 Oct 2004

Do you mean "set it for the duration of this session" or "set it permanently, by writing * Set to the topic"? If the former, it would be better to expose the Prefs API to plugins, as it has this method already. If the latter, then again, it should be done by the Prefs module. For example, should it be set in Meta fields, or in the body text?

-- CrawfordCurrie - 15 Oct 2004

In my case, I need to "set it for the duration of this session". I have done it using the Prefs module, but the TWiki documentation states that plugins should use only functions in the Func module

-- JChristophFuchs - 15 Oct 2004

initialize

It is not possible (as far as I can see) to legally invoke a script from a plugin, as this requires the initialization of various modules in TWiki, such as the Store, User, Access, and Prefs. At least, from looking at all scripts in bin/ the pattern appears to be to start off with getting a CGI object and then invoking TWiki::initialize. This function should be available for plugin writers, as many plugins might entail interacting with the user, not just rendering a page.

-- ThomasWeigert - 26 Mar 2005

Questions

Here is something I don't understand...

1. I thought the point of FuncDotPm is to isolate the plugin writers from potential changes in core.
2. I thought that meta data is not exposed in FuncDotPm to allow the TWiki core to freely change the way meta data is stored.
3. In Func::readTopicText meta data is returned together with the text, and it is assumed that Func::saveTopicText store the appropriate meta data with text.

-- ThomasWeigert - 27 Mar 2005