Difference: TWikiFuncDotPm (15 vs. 16)

• 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.

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

• \@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.

Example:

my $response = getExternalResource($url,
    ['Cache-Control' => 'max-age=0'], {timeout => 10});

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

• • MyPlugin topic has: * Set COLOR = red

• • MyPlugin topic has: * Set SHOWHELP = off

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

• $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.

• Set ALLOWTOPICSPIN = IncyWincy

• $ignorePermissions - Set to "1" if checkAccessPermission() is already performed and OK.

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

• $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.

• requires optional, comma-separated list of id's of other head blocks this one depends on. Those blocks will be loaded first.

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

• $web - name of web, optional
• $topic - name of topic, optional

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)

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

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

• $user - WikiName, login name or cUID of user, optional. Name of logged-in user is taken if not specified.

• $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

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

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

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

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

Since: TWiki::Plugins::VERSION 6.00

TWiki-6.0 (Jerusalem Release)

EmptyPlugin.pm

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