Difference: TWikiFuncDotPm (15 vs. 16)

Revision 162013-10-14 - TWikiContributor

Line: 25 to 25
 $TWiki::Plugins::VERSION. The 'Since' field in the function documentation refers to $TWiki::Plugins::VERSION.
Changed:
<
<
Notes on use of $TWiki::Plugins::VERSION (from 1.2 forwards):
>
>
Notes on use of $TWiki::Plugins::VERSION 6.00 and later:
 
Changed:
<
<
  • If the major version (e.g. 1.) is the same then any plugin coded to use any earlier revision of the 1. API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to require plugins to be recoded.
  • If the minor version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, deprecation of functions in the interface trigger a minor version increment. Note that deprecated functions are not removed, they are merely frozen, and plugin authors are recommended to stop using them.
  • Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
>
>
  • The version number is now aligned with the TWiki release version.
  • A TWiki-6.7.8 release will have a $TWiki::Plugins::VERSION = 6.78.
  • In an unlikely case where the patch number is 10 or larger, the patch number is added to the previous patch number. For example, TWiki-6.7.9 will have version 6.79, TWiki-6.7.10 will have 6.7910, and TWiki-6.7.11 will have 6.7911. This ensures that the version number can sort properly.
 
  • TWiki::Plugins::VERSION also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of TWiki::Plugins::VERSION it relates to.
Line: 112 to 104
 

Changed:
<
<

getExternalResource( $url, @headers ) -> $response

>
>

getExternalResource( $url, \@headers, \%params ) -> $response

  Get whatever is at the other end of a URL (using an HTTP GET request). Will only work for encrypted protocols such as https if the LWP CPAN module is
Line: 121 to 113
 Note that the $url may have an optional user and password, as specified by the relevant RFC. Any proxy set in configure is honored.
Changed:
<
<
Optional headers may be supplied of form 'name1', 'value1', 'name2', 'value2'. Do not add a User-Agent header, it will be added.
>
>
Optional parameters may be supplied:
  • \@headers (an array ref): Additional HTTP headers of form 'name1', 'value1', 'name2', 'value2'. User-Agent header is set to "TWiki::Net/### libwww-perl/#.##" by default, where ### is the revision number of TWiki::Net and #.## is the version of LWP.
  • \%params (a hash ref): Additional options.

Below is the list of available %params. See CPAN:LWP::UserAgent for more details.

Name Usage
agent => $useragent ("User-Agent:" header)
cookie_jar => $cookies
credentials => [$netloc, $realm, $uname, $pass]
handlers => {$phase => \&cb, ...} Note: %matchspec is not available.
local_address => $address
max_redirect => $n
max_size => $bytes
method * => $method E.g. 'HEAD'
parse_head => $boolean
requests_redirectable => \@requests
ssl_opts => {$key => $value, ...}
timeout * => $secs
The parameters with * do not require LWP.

Example:

my $response = getExternalResource($url,
    ['Cache-Control' => 'max-age=0'], {timeout => 10});
  The $response is an object that is known to implement the following subset of
Changed:
<
<
the methods of LWP::Response. It may in fact be an LWP::Response object,
>
>
the methods of HTTP::Response. It may in fact be an HTTP::Response object,
 but it may also not be if LWP is not available, so callers may only assume the following subset of methods is available:
code()
Line: 163 to 184
  Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
Note: The optional parameters \@headers and \%params were added in TWiki::Plugins::VERSION 6.00

postExternalResource( $url, $text, \@headers, \%params ) -> $response

This method is essentially the same as getExternalResource() except that it uses an HTTP POST method and that the additional $text parameter is required.

The $text is sent to the server as the body content of the HTTP request.

See getExternalResource() for more details.

Since: TWiki::Plugins::VERSION 6.00

 

getCgiQuery( ) -> $query

Line: 307 to 344
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

  • Example for Plugin setting:
Changed:
<
<
>
>
    • MyPlugin topic has: * Set COLOR = red
 
    • Use "MYPLUGIN_COLOR" for $key
    • my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
Line: 345 to 382
 Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

  • Example for Plugin setting:
Changed:
<
<
    • MyPlugin topic has: * Set SHOWHELP = off
>
>
    • MyPlugin topic has: * Set SHOWHELP = off
 
    • Use "MYPLUGIN_SHOWHELP" for $key
    • my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
Line: 529 to 566
 

isGuest( ) -> $boolean

Changed:
<
<
Test if logged in user is a guest (TWikiGuest)
>
>
Test if logged in user is a guest (TWikiGuest)
  Since: TWiki::Plugins::VERSION 1.000 (7 Dec 2002)

Changed:
<
<

isAnAdmin( $id ) -> $boolean

>
>

isAnAdmin( $user, $topic, $web ) -> $boolean

  Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.
Changed:
<
<
  • $id can be either a login name or a WikiName
>
>
  • $user can be either a login name or a WikiName
  • a user mapping handler's isAdmin() may take $topic and $web arguments. That's why this function takes them too. For a user mapping handler whose isAdmin() doesn't care $topic and $web (e.g. TWikiUserMapping), $topic and $web are irrelevant, needless to say.
  Since: TWiki::Plugins::VERSION 1.2
Added:
>
>
Note: The parameters $topic and $web were added in TWiki::Plugins::VERSION 6.00
 

isGroupMember( $group, $id ) -> $boolean

Line: 661 to 705
 earlier TWiki releases.

Tip if you want, you can use this method to check your own access control types. For example, if you:

Changed:
<
<
>
>
  • Set ALLOWTOPICSPIN = IncyWincy
 in ThatWeb.ThisTopic, then a call to checkAccessPermission('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef) will return true.

Since: TWiki::Plugins::VERSION 1.000 (27 Feb 2001)

Line: 798 to 842
  }
Added:
>
>
Since: TWiki::Plugins::VERSION 1.2
 

getTopicList( $web ) -> @topics

Line: 1086 to 1132
 
  • $topic - topic to atach to
  • $attachment - name of the attachment
  • $opts - Ref to hash of options
Added:
>
>
  • $ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK.
 $opts may include:
dontlog don't log this change in twiki log
comment comment for save
Line: 1173 to 1220
 
  • $name - template file name
  • $skin - comma-separated list of skins to use (default: current skin)
  • $web - the web to look in for topics that contain templates (default: current web)
Changed:
<
<
Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
>
>
Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
  Since: TWiki::Plugins::VERSION 1.1
Line: 1188 to 1235
 

expandTemplate( $def ) -> $string

Changed:
<
<
Do a , only expanding the template (not expanding any variables other than %TMPL)
>
>
Do a %TMPL:P{$def}%, only expanding the template (not expanding any variables other than %TMPL)
 
  • $def - template name
Return: the text of the expanded template

Since: TWiki::Plugins::VERSION 1.1

Changed:
<
<
A template is defined using a %TMPL:DEF% statement in a template
>
>
A template is defined using a %TMPL:DEF% statement in a template
 file. See the documentation on TWiki templates for more information.
Line: 1209 to 1256
 

Changed:
<
<

redirectCgiQuery( $query, $url, $passthru )

>
>

redirectCgiQuery( $query, $url, $passthru, $viaCache )

  Redirect to URL
  • $query - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
  • $url - URL to redirect to
  • $passthru - enable passthrough.
Added:
>
>
  • $viaCache - forcibly cache a redirect CGI query. It cuts off all the params in a GET url and replace with a "?$cache=..." param. "$viaCache" is meaningful only if "$passthru" is true.
  Return: none
Line: 1248 to 1296
 

addToHEAD( $id, $header, $requires )

Adds $header to the HTML header (the tag).

Changed:
<
<
This is useful for Plugins that want to include some javascript custom css.
>
>
This is useful for Plugins that want to include some javascript and custom css.
 
  • $id - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
  • $header - the HTML to be added to the section. The HTML must be valid in a HEAD tag - no checks are performed.
Changed:
<
<
  • requires optional, comma-separated list of id's of other head blocks this one depends on.
>
>
  • requires optional, comma-separated list of id's of other head blocks this one depends on. Those blocks will be loaded first.
  All TWiki variables present in $header will be expanded before being inserted into the section.
Line: 1357 to 1405
 

Changed:
<
<

expandVariablesOnTopicCreation ( $text ) -> $text

>
>

expandVariablesOnTopicCreation ( $text, $web, $topic ) -> $text

  Expand the limited set of variables that are always expanded during topic creation
  • $text - the text to process
Added:
>
>
  • $web - name of web, optional
  • $topic - name of topic, optional
 Return: text with variables expanded

Since: TWiki::Plugins::VERSION 1.1

Line: 1478 to 1528
 (ie, with the name of the function instead of the alias) will not work.
Added:
>
>

registerExternalHTTPHandler( \&fn )

Should only be called from initPlugin.

Adds a function to modify all the HTTP requests to any external resources.

  • \&fn - Reference to the function.

The handler function must be of the form:

sub handler(\%session, $url) -> (\@headers, \%params)
where:
  • \%session - a reference to the TWiki session object (may be ignored)
  • $url - a URL being requested

The returned \@headers and \%params are added to the request in the same manner as getExternalResource, except that \%params will not override any entries that have been set earlier. All the params explicitly given by the caller of getExternalResource or postExternalResource will have the highest precedence.

Example:

sub initPlugin {
    TWiki::Func::registerExternalHTTPHandler( \&handleExternalHTTPRequest );
}

sub handleExternalHTTPRequest {
    my ($session, $url) = @_;
    my @headers;
    my %params;

    # Add any necessary @headers and %params
    push @headers, 'X-Example-Header' => 'Value';
    $params{timeout} = 5;

    # Return refs to both
    return (\@headers, \%params);
}

Since: TWiki::Plugins::VERSION 6.00

 

decodeFormatTokens($str) -> $unencodedString

Line: 1501 to 1596
 
$n or $n() New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar
$nop or $nop() Is a "no operation".
$quot Double quote (")
Added:
>
>
$aquot Apostrophe quote (')
 
$percnt Percent sign (%)
$dollar Dollar sign ($)
Added:
>
>
$lt Less than sign (<)
$gt Greater than sign (>)
 
Changed:
<
<
Note thath $quot, $percnt and $dollar all work *even if they are followed by
>
>
Note that $quot, $aquot, $percnt and $dollar all work *even if they are followed by
 alphanumeric characters*. You have been warned!

Since: TWiki::Plugins::VERSION 1.2

Line: 1587 to 1685
 Since: TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
Added:
>
>

Read-only and Mirror Webs

The following functions are for ReadOnlyAndMirrorWebs.

getSiteName() -> $siteName

Returns the current site name if it's defined. Otherwise returns the null string.

getContentMode( $web ) -> $contentMode

Returns the content mode of the specified $web. Please read ReadOnlyAndMirrorWebs about content mode.

Since: TWiki::Plugins::VERSION 6.00

webWritable( $web ) -> $boolean

Checks if the web is wriable on this site - if it's master or local. Returns true if it's writable. Returns false otherwise.

Since: TWiki::Plugins::VERSION 6.00

Using multiple disks

The following functions are for UsingMultipleDisks.

getDiskList() -> @diskIDs

Returns IDs of disks used by TWiki. An disk ID is "" (a null string) or a decimal number without leading 0.

Since: TWiki::Plugins::VERSION 6.00

getDiskInfo($web, [$diskID]) -> ($dataDir, $pubDir, $diskID)

Returns the relevant paths and the disk ID of the specified web on the specified site.

Since: TWiki::Plugins::VERSION 6.00

trashWebName(web => $web | disk => $diskID) -> $trashWebName

Returns the name of the trash web to which topics of the $web web are moved. Or returns the name of the trash web of the specified disk.

Each disk (file system) TWiki uses needs to have a trash web since a topic deletion may entail an attachment directory move, which is possible only within the same disk/file system.

Since: TWiki::Plugins::VERSION 6.00

 

General Utilities

Line: 1656 to 1812
 
( '', 'Web.Subweb.Topic' ) ( 'Web/Subweb', 'Topic' )
( 'Web1', 'Web2.Topic' ) ( 'Web2', 'Topic' )
Changed:
<
<
Note that hierarchical web names (SubWeb) are only available if hierarchical webs are enabled in configure.
>
>
Note that hierarchical web names (Web.SubWeb) are only available if hierarchical webs are enabled in configure.
  The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
Input Return
Line: 1724 to 1880
 
  • $extra - arbitrary extra information to add to the event.
  • $web - web name, optional. Base web is taken if empty. Ignored if web is specified in $topic.
  • $topic - topic name, optional. Can be Topic or Web.Topic. Base topic is taken if empty.
Changed:
<
<
  • $user - WikiName of user, optional. Name of logged-in user is taken if not specified.
>
>
  • $user - WikiName, login name or cUID of user, optional. Name of logged-in user is taken if not specified.
 Return: none

Since: TWiki::Plugins::VERSION 1.4

Line: 1742 to 1898
 
  if( defined &TWiki::Func::writeLog ) {
    # use writeLog
Changed:
<
<
TWiki::Func::writeLog( $web, $topic, 'myevent', $extra );
>
>
TWiki::Func::writeLog( 'myevent', $extra, $web, $topic );
  } else { # deprecated code if plugin is used in older TWiki releases $TWiki::Plugins::VERSION > 1.1
Line: 1757 to 1913
  Format the time in seconds into the desired time string
  • $time - Time in epoc seconds
Changed:
<
<
  • $format - Format type, optional. Default e.g. '31 Dec 2002 - 19:30'. Can be '$iso' (e.g. '2002-12-31T19:30Z'), '$rcs' (e.g. '2001/12/31 23:59:59', '$http' for HTTP header format (e.g. 'Thu, 23 Jul 1998 07:21:56 GMT'), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz' for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
>
>
  • $format - Format type, optional. Default e.g. '2013-12-31 - 19:30'. Can be '$iso' (e.g. '2013-12-31T19:30Z'), '$rcs' (e.g. '2013/12/31 23:59:59', '$http' for HTTP header format (e.g. 'The, 2013-07-23 07:21:56 GMT'), or any string with tokens '$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz' for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
 
  • $timezone - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
Return: $text Formatted time string
Changed:
<
<
Note: if you used the removed formatGmTime, add a third parameter 'gmtime'
>
>
Note: If you used the removed formatGmTime, add a third parameter 'gmtime'
  Since: TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
Line: 1811 to 1968
 

extractNameValuePair( $attr, $name ) -> $value

Changed:
<
<
Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
>
>
Extract a named or unnamed value from a variable parameter string.
 
  • $attr - Attribute string
  • $name - Name, optional
Return: $value Extracted value
Line: 1827 to 1983
  my $val1  = TWiki::Func::extractNameValuePair( $text, "name1" );
my $val2  = TWiki::Func::extractNameValuePair( $text, "name2" );
Added:
>
>
Note: Function TWiki::Func::extractParameters is more efficient for extracting several parameters

entityEncode( $text, $extra ) -> $text

Entity encode text.

  • $text - Text to encode, may be empty
  • $extra - Additional characters to include in the set of encoded characters, optional
Return: $text Entity encoded text

Since: TWiki::Plugins::VERSION 6.00

Escape special characters to HTML numeric entities. This is not a generic encoding, it is tuned specifically for use in TWiki.

HTML4.0 spec: "Certain characters in HTML are reserved for use as markup and must be escaped to appear literally. The "<" character may be represented with an entity, &lt;. Similarly, ">" is escaped as &gt;, and "&" is escaped as &amp;. If an attribute value contains a double quotation mark and is delimited by double quotation marks, then the quote should be escaped as &quot;.

Other entities exist for special characters that cannot easily be entered with some keyboards..."

This method encodes HTML special and any non-printable ASCII characters (except for \n and \r) using numeric entities.

FURTHER this method also encodes characters that are special in TWiki meta-language.

$extras is an optional param that may be used to include additional characters in the set of encoded characters. It should be a string containing the additional chars.

entityDecode( $text ) -> $text

Decode all numeric entities (e.g. &#123;). Does not decode named entities such as &amp; (use HTML::Entities for that)

  • $text - Text to decode, may be empty
Return: $text Entity decoded text

Since: TWiki::Plugins::VERSION 6.00

urlEncode( $text ) -> $text

URL encode text, mainly used to encode URL parameters.

  • $text - Text to encode, may be empty
Return: $text URL encoded text

Since: TWiki::Plugins::VERSION 6.00

Encoding is done by converting characters that are illegal in URLs to their %NN equivalents. This method is used for encoding strings that must be embedded verbatim in URLs; it cannot be applied to URLs themselves, as it escapes reserved characters such as = and ?.

RFC 1738, Dec. '94:

    ...Only alphanumerics [0-9a-zA-Z], the special
    characters $-_.+!*'(), and reserved characters used for their
    reserved purposes may be used unencoded within a URL.

Reserved characters are $&+,/:;=?@ - these are also encoded by this method.

This URL-encoding handles all character encodings including ISO-8859-*, KOI8-R, EUC-* and UTF-8.

This may not handle EBCDIC properly, as it generates an EBCDIC URL-encoded URL, but mainframe web servers seem to translate this outbound before it hits browser - see CGI::Util::escape for another approach.

urlDecode( $text ) -> $text

URL decode text, mainly used to decode URL parameters.

  • $text - Text to decode, may be empty
Return: $text URL decoded text

Since: TWiki::Plugins::VERSION 6.00

 

Deprecated functions

Line: 2191 to 2440
 
  • beforeAttachmentSaveHandler(\%attrHash, $topic, $web, $meta) = added =$meta
  • writeLog( $action, $extra, $web, $topic, $user )
Added:
>
>

TWiki-6.0 (Jerusalem Release)

$TWiki::Plugins::VERSION 6.00

EmptyPlugin.pm

No changes

Func.pm

  • isAnAdmin( $user, $topic, $web ) -> $boolean -- added $topic and $web
  • expandVariablesOnTopicCreation( $text, $web, $topic ) -> $text -- added $web and $topic
  • postExternalResource( $url, $text, \@headers, \%params ) -> $response
  • registerExternalHTTPHandler( \&fn )
  • getContentMode( $web ) -> $contentMode
  • webWritable( $web ) -> $boolean
  • getDiskList() -> @diskIDs
  • getDiskInfo($web, $siteName) -> ($dataDir, $pubDir, $diskID)
  • trashWebName(web => $web | disk => $diskID) -> $trashWebName
  • entityEncode( $text, $extra ) -> $text
  • entityDecode( $text ) -> $text
  • urlEncode( $text ) -> $text
  • urlDecode( $text ) -> $text
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.TWikiFuncDotPm.