CGI-Wiki-Formatter-UseMod
view release on metacpan or search on metacpan
lib/CGI/Wiki/Formatter/UseMod.pm view on Meta::CPAN
edit_suffix => '',
munge_urls => 0,
);
Parameters will default to the values shown above (apart from
C<allowed_tags>, which defaults to allowing no tags).
=over 4
=item B<Internal links>
C<node_prefix>, C<node_suffix>, C<edit_prefix> and C<edit_suffix>
allow you to control the URLs generated for links to other wiki pages.
So for example with the defaults given above, a link to the Home node
will have the URL C<wiki.pl?Home> and a link to the edit form for the
Home node will have the URL C<wiki.pl?action=edit;id=Home>
(Note that of course the URLs that you wish to have generated will
depend on how your wiki application processes its CGI parameters - you
can't just put random stuff in there and hope it works!)
=item B<Internal links - advanced options>
If you wish to have greater control over the links, you may use the
C<munge_node_name> parameter. The value of this should be a
subroutine reference. This sub will be called on each internal link
after all other formatting and munging I<except> URL escaping has been
applied. It will be passed the node name as its first parameter and
should return a node name. Note that this will affect the URLs of
internal links, but not the link text.
Example:
# The formatter munges links so node names are ucfirst.
# Ensure 'state51' always appears in lower case in node names.
munge_node_name => sub {
my $node_name = shift;
$node_name =~ s/State51/state51/g;
return $node_name;
}
B<Note:> This is I<advanced> usage and you should only do it if you
I<really> know what you're doing. Consider in particular whether and
how your munged nodes are going to be treated by C<retrieve_node>.
=item B<URL munging>
If you set C<munge_urls> to true, then your URLs will be more
user-friendly, for example
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 C<node_name_to_node_param>),
so the default is to B<not> munge URLs.
=item B<Macros>
Be aware that macros are processed I<after> filtering out disallowed
HTML tags and I<before> transforming from wiki markup into HTML. 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.
You may wish to have access to the overall wiki object in the subs
defined in your macro. To do this:
=over
=item *
Pass the wiki object to the C<< ->formatter >> call as described below.
=item *
Pass a true value in the C<pass_wiki_to_macros> parameter when calling
C<< ->new >>.
=back
If you do this, then I<all> coderefs will be called with the wiki object
as the first parameter, followed by the first nine captured substrings
as described above. Note therefore that setting C<pass_wiki_to_macros>
may cause backwards compatibility issues.
=back
Macro examples:
# Simple example - substitute a little search box for '@SEARCHBOX'
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>),
}
# More complex example - substitute a list of all nodes in a
# category for '@INDEX_LINK [[Category Foo]]'
pass_wiki_to_macros => 1,
macros => {
qr/\@INDEX_LINK\s+\[\[Category\s+([^\]]+)]]/ =>
sub {
my ($wiki, $category) = @_;
my @nodes = $wiki->list_nodes_by_metadata(
metadata_type => "category",
metadata_value => $category,
ignore_case => 1,
);
my $return = "\n";
foreach my $node ( @nodes ) {
$return .= "* "
. $wiki->formatter->format_link(
wiki => $wiki,
link => $node,
)
. "\n";
}
return $return;
},
}
=cut
sub new {
my ($class, @args) = @_;
my $self = {};
bless $self, $class;
$self->_init(@args) or return undef;
return $self;
}
sub _init {
my ($self, %args) = @_;
# Store the parameters or their defaults.
my %defs = ( extended_links => 0,
implicit_links => 1,
force_ucfirst_nodes => 1,
use_headings => 1,
allowed_tags => [],
macros => {},
pass_wiki_to_macros => 0,
lib/CGI/Wiki/Formatter/UseMod.pm view on Meta::CPAN
pre => qr/^\s+/,
table => qr/^\|\|/,
},
definition => [ "<dl>\n", "</dl>\n", "<dd> ", "</dd>\n" ],
pre => [ "<pre>\n", "</pre>\n", "", "\n" ],
table => [ qq|<table class="user_table">\n|, "</table>\n",
sub {
my $line = shift;
$line =~ s/\|\|$/<\/td>/;
$line =~ s/\|\|/<\/td><td>/g;
return ("<tr>","<td>$line","</tr>");
},
],
# we don't label unordered lists as "not indented" so we can nest them.
indented => {
definition => 0,
ordered => 0,
pre => 0,
table => 0,
},
blockorder => [ qw( header line ordered unordered code definition pre table paragraph )],
nests => { map { $_ => 1} qw( ordered unordered ) },
link => sub {
my $link = shift;
return $self->format_link(
link => $link,
wiki => $wiki,
);
},
);
return wikiformat($safe, \%format_tags, \%format_opts );
}
sub _format_opts {
my $self = shift;
return (
extended => $self->{_extended_links},
prefix => $self->{_node_prefix},
implicit_links => $self->{_implicit_links}
);
}
=item B<format_link>
my $string = $formatter->format_link(
link => "Home Node",
wiki => $wiki,
);
An internal method exposed to make it easy to go from eg
* Foo
* Bar
to
* <a href="index.cgi?Foo">Foo</a>
* <a href="index.cgi?Bar">Bar</a>
See Macro Examples above for why you might find this useful.
C<link> should be something that would go inside your extended link
delimiters. C<wiki> is optional but should be a L<CGI::Wiki> object.
If you do supply C<wiki> then the method will be able to check whether
the node exists yet or not and so will call C<< ->make_edit_link >>
instead of C<< ->make_internal_link >> where appropriate. If you don't
supply C<wiki> then C<< ->make_internal_link >> will be called always.
This method used to be private so may do unexpected things if you use
it in a way that I haven't tested yet.
=cut
sub format_link {
my ($self, %args) = @_;
my $link = $args{link};
my %opts = $self->_format_opts;
my $wiki = $args{wiki};
my $title;
($link, $title) = split(/\|/, $link, 2) if $opts{extended};
$title =~ s/^\s*// if $title; # strip leading whitespace
$title ||= $link;
if ( $self->{_force_ucfirst_nodes} ) {
$link = $self->_do_freeupper($link);
}
$link = $self->_munge_spaces($link);
$link = $self->{_munge_node_name}($link)
if $self->{_munge_node_name};
my $editlink_not_link = 0;
# See whether the linked-to node exists, if we can.
if ( $wiki && !$wiki->node_exists( $link ) ) {
$editlink_not_link = 1;
}
$link =~ s/ /_/g if $self->{_munge_urls};
$link = uri_escape( $link );
if ( $editlink_not_link ) {
my $prefix = $self->{_edit_prefix};
my $suffix = $self->{_edit_suffix};
return $self->make_edit_link(
title => $title,
url => $prefix.$link.$suffix,
);
} else {
my $prefix = $self->{_node_prefix};
my $suffix = $self->{_node_suffix};
return $self->make_internal_link(
title => $title,
url => $prefix.$link.$suffix,
);
}
}
# CGI.pm is sometimes awkward about actually performing CGI::escapeHTML
# if there's a previous instantiation - in the calling script, for example.
( run in 1.250 second using v1.01-cache-2.11-cpan-39bf76dae61 )