Wiki-Toolkit-Formatter-UseMod-0.24/ 0002755 0001750 0001750 00000000000 12011755446 015247 5 ustar dom dom Wiki-Toolkit-Formatter-UseMod-0.24/Changes 0000644 0001750 0001750 00000007052 12011755100 016527 0 ustar dom dom 0.24 12 August 2012 Add new "external_link_class" option to ->new, for people who prefer to style their external links with CSS. 0.23 1 February 2009 Fix POD errors and add POD test (#46) 0.22 18 April 2008 Add missing prerequisite of Wiki::Toolkit to aid automated testing. Clean up test sqlite databases correctly 0.21 12 April 2008 Made Test::MockObject optional. Skip tests broken by Text::WikiFormat bug (see http://www.wiki-toolkit.org/ticket/12) 0.20 6 June 2006 Update copyright notice. Fix bug with badly-formed internal links. 0.19 27 April 2006 Rename to Wiki::Toolkit::Formatter::UseMod 0.18 30 November 2004 Skip CGI::Wiki-requiring tests if CGI::Wiki not installed (thanks to CPAN tester "nothingmuch" for failure report). 0.17 26 November 2004 Removed debugging info accidentally left in last release. 0.16 20 September 2004 Added the "pass_wiki_to_macros" flag to let you write more powerful macros - see perldoc for details. Exposed the ->format_link method - see perldoc for details. 0.15 7 August 2004 Added very simple table support: || foo || bar || || bax || quux || Tables are added with a class of "user_table" so you can manipulate them in your stylesheet without affecting any other tables on your site. 0.14 9 July 2004 Allow subclassing to alter hyperlink appearance - see SUBCLASSING in perldoc CGI::Wiki::Formatter::UseMod. 0.13 4 June 2004 Leading ':' (which creates a definition list for an indent effect) now has better HTML, plus adds a leading to allow blank lines in the indented text. 0.12 2 June 2004 Indentation now causes
, as per the UseMod spec. 0.11 20 November 2003 Added (experimental, advanced) "munge_node_name" parameter. 0.10 20 October 2003 Fixed bug - ordered lists shouldn't require indent. 0.09 22 September 2003 Changed the way we call Text::WikiFormat, to avoid), } # 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; }, } format 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 Wiki::Toolkit 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 Wiki::Toolkit. 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 * Foo * Bar See Macro Examples above for why you might find this useful. "link" should be something that would go inside your extended link delimiters. "wiki" is optional but should be a Wiki::Toolkit object. If you do supply "wiki" then the method will be able to check whether the node exists yet or not and so will call "->make_edit_link" instead of "->make_internal_link" where appropriate. If you don't supply "wiki" then "->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. find_internal_links my @links_to = $formatter->find_internal_links( $content ); Returns a list of all nodes that the supplied content links to. node_name_to_node_param 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. Note that unless "munge_urls" was set to true when "new" was called, this method will do nothing. node_param_to_node_name 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. Note that unless "munge_urls" was set to true when "new" was called, this method will do nothing. SUBCLASSING The following methods can be overridden to provide custom behaviour. make_edit_link my $link = $self->make_edit_link( title => "Home Page", url => "http://example.com/?id=Home", ); This method will be passed a title and a url and should return an HTML snippet. For example, you can add a "title" attribute to the link like so: sub make_edit_link { my ($self, %args) = @_; my $title = $args{title}; my $url = $args{url}; return qq|[$title]?|; } make_internal_link my $link = $self->make_internal_link( title => "Home Page", url => "http://example.com/?id=Home", ); This method will be passed a title and a url and should return an HTML snippet. For example, you can add a "class" attribute to the link like so: sub make_internal_link { my ($self, %args) = @_; my $title = $args{title}; my $url = $args{url}; return qq|$title|; } make_external_link my $link = $self->make_external_link( title => "London Perlmongers", url => "http://london.pm.org", ); This method will be passed a title and a url and should return an HTML snippet. For example, you can add a little icon after each external link like so: sub make_external_link { my ($self, %args) = @_; my $title = $args{title}; my $url = $args{url}; return qq|$title
new in order for this to happen. **** RELATED NOTE FOR PEOPLE WITH OPENGUIDES INSTALLS **** Do *not* install this version of CGI::Wiki::Formatter::UseMod unless you are using OpenGuides version 0.21 or later. 0.04 14 May 2003 ->node_name_to_node_param method now takes notice of the force_ucfirst_nodes attribute. 0.03 28 April 2003 Subs in macros are now called with up to nine arguments. I know this is a bit arbitrary, but I now need it to support two arguments and I might as well allow a few more while I'm at it. 0.02 5 April 2003 Macros can now substitute the output of subs as well as plain strings. 0.01 3 March 2003 Initial release. Wiki-Toolkit-Formatter-UseMod-0.24/README 0000644 0001750 0001750 00000032415 10421647355 016134 0 ustar dom dom NAME Wiki::Toolkit::Formatter::UseMod - UseModWiki-style formatting for Wiki::Toolkit DESCRIPTION A formatter backend for Wiki::Toolkit that supports UseMod-style formatting. SYNOPSIS use Wiki::Toolkit::Formatter::UseMod; # Instantiate - see below for parameter details. my $formatter = Wiki::Toolkit::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); METHODS new my $formatter = Wiki::Toolkit::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 => {}, pass_wiki_to_macros => 0, 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). Internal links "node_prefix", "node_suffix", "edit_prefix" and "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 "wiki.pl?Home" and a link to the edit form for the Home node will have the URL "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!) Internal links - advanced options If you wish to have greater control over the links, you may use the "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 *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; } Note: This is *advanced* usage and you should only do it if you *really* know what you're doing. Consider in particular whether and how your munged nodes are going to be treated by "retrieve_node". URL munging If you set "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 "node_name_to_node_param"), so the default is to not munge URLs. Macros Be aware that macros are processed *after* filtering out disallowed HTML tags and *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: * Pass the wiki object to the "->formatter" call as described below. * Pass a true value in the "pass_wiki_to_macros" parameter when calling "->new". If you do this, then *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 "pass_wiki_to_macros" may cause backwards compatibility issues. Macro examples: # Simple example - substitute a little search box for '@SEARCHBOX' macros => { '@SEARCHBOX' => qq(