CGI::Wiki::Formatter::UseMod - UseModWiki-style formatting for CGI::Wiki
A formatter backend for CGI::Wiki that supports UseMod-style formatting.
use CGI::Wiki::Formatter::UseMod; # Instantiate - see below for parameter details. my $formatter = CGI::Wiki::Formatter::UseMod->new( %config ); # Format some text. my $cooked = $formatter->format($raw); # Find out which other nodes that text would link to. my @links_to = $formatter->find_internal_links($raw);
my $formatter = CGI::Wiki::Formatter::UseMod->new( extended_links => 0, # $FreeLinks implicit_links => 1, # $WikiLinks force_ucfirst_nodes => 1, # $FreeUpper use_headings => 1, # $UseHeadings allowed_tags => [qw(b i)], # defaults to none macros => {}, node_prefix => 'wiki.pl?', node_suffix => '', edit_prefix => 'wiki.pl?action=edit&id=', edit_suffix => '', munge_urls => 0, );
Parameters will default to the values shown above (apart from allowed_tags, which defaults to allowing no tags).
allowed_tags
If you set munge_urls to true, then your URLs will be more user-friendly, for example
munge_urls
http://example.com/wiki.cgi?Mailing_List_Managers
rather than
http://example.com/wiki.cgi?Mailing%20List%20Managers
The former behaviour is the actual UseMod behaviour, but requires a little fiddling about in your code (see node_name_to_node_param), so the default is to not munge URLs.
node_name_to_node_param
Be aware that macros are processed after filtering out disallowed HTML tags. They are also not called in any particular order.
The keys of macros should be either regexes or strings. The values can be strings, or, if the corresponding key is a regex, can be coderefs. The coderef will be called with the first nine substrings captured by the regex as arguments. I would like to call it with all captured substrings but apparently this is complicated.
Macro examples:
macros => { '@SEARCHBOX' => qq(<form action="wiki.pl" method="get"> <input type="hidden" name="action" value="search"> <input type="text" size="20" name="terms"> <input type="submit"></form>), qr/\@INDEX\s+\[Category\s+([^\]]+)]/ => sub { return "{an index of things in category $_[0]}" } }
my $html = $formatter->format($submitted_content, $wiki);
Escapes any tags which weren't specified as allowed on creation, then interpolates any macros, then translates the raw Wiki language supplied into HTML.
A CGI::Wiki object can be supplied as an optional second parameter. This object will be used to determine whether a linked-to node exists or not, and alter the presentation of the link accordingly. This is only really in here for use when this method is being called from within CGI::Wiki.
my @links_to = $formatter->find_internal_links( $content );
Returns a list of all nodes that the supplied content links to.
use URI::Escape; $param = $formatter->node_name_to_node_param( "Recent Changes" ); my $url = "wiki.pl?" . uri_escape($param);
In usemod, the node name is encoded prior to being used as part of the URL. This method does this encoding (essentially, whitespace is munged into underscores). In addition, if force_ucfirst_nodes is in action then the node names will be forced ucfirst if they weren't already.
force_ucfirst_nodes
Note that unless munge_urls was set to true when new was called, this method will do nothing.
new
my $node = $q->param('node') || ""; $node = $formatter->node_param_to_node_name( $node );
In usemod, the node name is encoded prior to being used as part of the URL, so we must decode it before we can get back the original node name.
Kake Pugh (kake@earth.li).
Copyright (C) 2003 Kake Pugh. All Rights Reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The OpenGuides London team (http://openguides.org/london/) sent some very helpful bug reports. A lot of the work of this module is done within chromatic's module, Text::WikiFormat.
This doesn't yet support all of UseMod's formatting features and options, by any means. This really truly is a 0.0* release. Please send bug reports, omissions, patches, and stuff, to me at kake@earth.li.
kake@earth.li
UseModWiki "encodes" node names before making them part of a URL, so for example a node about Wombat Defenestration will have a URL like
http://example.com/wiki.cgi?Wombat_Defenestration
So if we want to emulate a UseModWiki exactly, we need to munge back and forth between node names as titles, and node names as CGI params.
my $formatter = CGI::Wiki::Formatter::UseMod->new( munge_urls => 1 ); my $node_param = $q->param('id') || $q->param('keywords') || ""; my $node_name = $formatter->node_param_to_node_name( $node_param ); use URI::Escape; my $url = "http://example.com/wiki.cgi?" . uri_escape( $formatter->node_name_to_node_param( "Wombat Defenestration" ) );
CGI::Wiki
Text::WikiFormat
UseModWiki (http://www.usemod.com/cgi-bin/wiki.pl)
1 POD Error
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
To install CGI::Wiki::Formatter::UseMod, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::Wiki::Formatter::UseMod
CPAN shell
perl -MCPAN -e shell install CGI::Wiki::Formatter::UseMod
For more information on module installation, please visit the detailed CPAN module installation guide.