PerlDoc

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

---

Parent package: Foswiki::Plugins
Child packages:

More ...Less ...

createTopicData( $webs, $excludewebs, $topics, $excludetopics ) → \%hash

Creates a hash of web => topics, using this structure:

%topicData = ( Web1 => { Topic1 => 1, Topic2 => 1, … } Web2 => { Topic1 => 1, Topic2 => 1, … } )

The value '1' is temporary to define which topics are valid, and will be replaced by a data structure later on.

Use one paramater or all. When no inWebs is passed, the current web is assumed. When no inTopics is passed, the current topic is assumed.

Function parameters:

• =$inWebs (string) - webs to include: either a web name, a comma-separated list of web names, or '*' for all webs the current user may see
• $inExcludeWebs (string) - webs to exclude: either a web name, a comma-separated list of web names
• $inTopics (string) - topics to include: either a topic name, a comma-separated list of topic names, or '*' for all topics
• $inExcludeTopics (string) - topics to exclude: either a topic name, a comma-separated list of topic names

Returns a reference to a hash of webs→topics.

insertObjectData( $topicData, $createObjectDataFunc, $properties )

Populates the topic data hash with custom data objects like this:

%topicData = ( Web1 => { Topic1 => your data, } )

The data object creation is done in your plugin in the function passed by $inCreateObjectDataFunc.

For example, AttachmentListPlugin creates this structure:

%topicData = ( Web1 => { Topic1 => { picture.jpg => FileData object 1, me.PNG => FileData object 2, … }, }, )

… using this data creation function:

sub _createFileData { my ( $inTopicHash, $inWeb, $inTopic ) = @_;

# define value for topic key only if topic # has META:FILEATTACHMENT data my $attachments = _getAttachmentsInTopic( $inWeb, $inTopic );

if ( scalar @$attachments ) { $inTopicHash→{$inTopic} = ();

foreach my $attachment (@$attachments) { my $fd = Foswiki::Plugins::AttachmentListPlugin::FileData→new( $inWeb, $inTopic, $attachment ); my $fileName = $fd→{name}; $inTopicHash→{$inTopic}{$fileName} = \$fd; } } else {

# no META:FILEATTACHMENT, so remove from hash delete $inTopicHash→{$inTopic}; } }

… and calls insertObjectData using:

Foswiki::Plugins::TopicDataHelperPlugin::insertObjectData( $topicData, \&_createFileData );

Function parameters:

• \%inTopicData (hash reference) - topic data
• \$inCreateObjectDataFunc (function reference) - function that will create a data object
• \%inProperties (hash reference, optional) - properties to be passed to the function $inCreateObjectDataFunc

Returns nothing.

filterTopicDataByViewPermission( $topicData, $wikiUserName )

Filters topic data objects by checking if the user $inWikiUserName has view access permissions.

Removes topic data if the user does not have permission to view the topic.

Example: my $user = Foswiki::Func::getWikiName(); my $wikiUserName = Foswiki::Func::userToWikiName( $user, 1 ); Foswiki::Plugins::TopicDataHelperPlugin::filterTopicDataByViewPermission( \%topicData, $wikiUserName );

Function parameters:

• \%inTopicData (hash reference) - topic data
• $inWikiUserName (string) - name of user to check

Returns nothing.

filterTopicDataByDateRange( $topicData, $fromDate, $toDate, $dateKey )

Filters topic data objects by date range, from $inFromDate to $inToDate.

Removes topic data if: - the value of the object attribute $inDateKey is earlier than $inFromDate - the value of the object attribute $inDateKey is later than $inToDate

Use either $inFromDate or inToDate, or both.

FormFieldListPlugin uses this function to show topics between fromdate and todate (for example: fromdate="2005/01/01" todate="2007/01/01").

From FormFieldListPlugin: if ( defined $inParams→{'fromdate'} || defined $inParams→{'todate'} ) { Foswiki::Plugins::TopicDataHelperPlugin::filterTopicDataByDateRange( \%topicData, $inParams→{'fromdate'}, $inParams→{'todate'} ); }

Function parameters:

• \%inTopicData (hash reference) - topic data
• $inFromDate (int) - epoch seconds
• $inToDate (int) - epoch seconds
• $inDateKey (string, optional) - date key; if not defined: 'date'

Returns nothing.

filterTopicDataByProperty( $topicData, $propertyKey, $isCaseSensitive, $includeValues, $excludeValues )

Filters topic data objects by matching an object property with a list of possible values.

Removes topic data if: - the object attribute $inPropertyKey is not in $inIncludeValues - the object attribute $inPropertyKey is in $inExcludeValues

Use either $inIncludeValues or $inExcludeValues, or both.

For example, AttachmentListPlugin uses this function to filter attachments by extension. extension="gif, jpg" will find all attachments with extension 'gif' OR 'jpg'. OR 'GIF' or 'JPG', therefore $inIsCaseSensitive is set to 0.

From AttachmentListPlugin:

my $extensions = $inParams→{'extension'} || undef; my $excludeExtensions = $inParams→{'excludeextension'} || undef; if ( defined $extensions || defined $excludeExtensions ) { Foswiki::Plugins::TopicDataHelperPlugin::filterTopicDataByProperty( \%topicData, 'extension', 0, $extensions, $excludeExtensions ); }

Function parameters:

• \%inTopicData (hash reference) - topic data
• $inPropertyKey (string) - key of object property
• $inIsCaseSensitive (boolean int) - if 0, makes all hash values of inIncludeValues and inExcludeValues lowercase; for example, finding matches on file extension should not be case sensitive
• $inIncludeValues (string) - comma-separated list of values that the object should have
• $inExcludeValues (string) - comma-separated list of values that the object should not have

Returns nothing.

filterTopicDataByRegexMatch( $topicData, $propertyKey, $includeRegex, $excludeRegex )

Filters topic data objects by matching an object property with a regular expression.

Removes topic data if: - the object attribute $inPropertyKey does not match $inIncludeRegex - the object attribute $inPropertyKey matches $inExcludeRegex

Use either $inIncludeRegex or $inExcludeRegex, or both.

Function parameters:

• \%inTopicData (hash reference) - topic data
• $inPropertyKey (string) - key of object property that is matched with the regular expressions inIncludeRegex and inExcludeValues
• $inIncludeRegex (string) - regular expression
• $inExcludeRegex (string) - regular expression

Returns nothing.

getListOfObjectData( $topicData ) → \@objects

Creates an array of objects from topic data objects.

For instance:

For a data structure:

%topicData = ( Web1 => { Topic1 => { 'name_of_field_1' => FormFieldData object, 'name_of_field_2' => FormFieldData object, …, }, }, }

The call: my $fields = Foswiki::Plugins::TopicDataHelperPlugin::getListOfObjectData($topicData);

… returns a list of FormFieldData objects.

Function parameters:

• \%inTopicData (hash reference) - topic data

Returns a reference to an unsorted array of data objects.

stringifyTopicData( $topicData ) → \@objects

Creates an array of strings from topic data objects, where each string is generated by the object's method stringify (to be implemented by your object's data class). To be used for data serialization.

For example, FormFieldData's stringify method looks like this:

sub stringify { my $this = shift;

return "1.0\t$this→{web}\t$this→{topic}\t$this→{name}\t$this→{value}\t$this→{date}"; }

Call this method with: my $list = Foswiki::Plugins::TopicDataHelperPlugin::stringifyTopicData($inTopicData); my $text = join "\n", @$list;

Function parameters:

• \%inTopicData (hash reference) - topic data

Returns a reference to an unsorted array of data objects.

sortObjectData( $objectData, $sortOrder, $sortKey, $compareMode, $nameKey ) → \@objects

Sort objects by property (sort key). Calls _sortObjectsByProperty.

Function parameters:

• \@inObjectData (array reference) - list of data objects (NOT the topic data!)
• $inSortOrder (int) - value of %sortDirections: either $Foswiki::Plugins::TopicDataHelperPlugin::sortDirections{'ASCENDING'}, $Foswiki::Plugins::TopicDataHelperPlugin::sortDirections{'DESCENDING'} or $Foswiki::Plugins::TopicDataHelperPlugin::sortDirections{'NONE'}
• $inSortKey (string) - primary sort key; this will be a property of your data object
• $inCompareMode (string) - sort mode of primary key, either 'numeric' or 'alphabetical'
• $inNameKey (string) - to be used as secondary sort key; must be alphabetical; this will be a property of your data object

Returns a reference to an sorted array of data objects.

_sortObjectData( $objectData, $sortOrder, $sortKey, $compareMode, $secondaryKey ) → \@objects

Private function. Sort objects by property (sort key).

Function parameters:

• \@inObjectData (array reference) - list of data objects (NOT the topic data!)
• $inSortOrder (int) - value of %sortDirections: either $Foswiki::Plugins::TopicDataHelperPlugin::sortDirections{'ASCENDING'}, $Foswiki::Plugins::TopicDataHelperPlugin::sortDirections{'DESCENDING'} or $Foswiki::Plugins::TopicDataHelperPlugin::sortDirections{'NONE'}
• $inSortKey (string) - primary sort key; this will be a property of your data object
• $inCompareMode (string) - sort mode of primary key, either 'numeric' or 'alphabetical'
• $inSecondaryKey (string) - to be used as secondary sort key; must be alphabetical; this will be a property of your data object

Returns a reference to an sorted array of data objects.

makeHashFromString( $text, $isCaseSensitive ) → \%hash

Creates a reference to a key-value hash of a string of words, where each word is turned into a key with a non-zero (growing) number (to keep the original order of the items).

For example: my $excludeTopicsList = 'WebHome, WebPreferences'; my $excludeTopics = makeHashFromString( $excludeTopicsList, 1 );

… will create:

$hashref = { 'WebHome' => 1, 'WebPreferences' => 2, };

Function parameters:

• $inText (string) - comma-delimited string of values
• $inIsCaseSensitive (boolean int) - if 0, makes all hash values lowercase; for example, finding matches on file extension should not be case sensitive

Returns a reference to a key-value hash.

Shorthand debugging call.