Wiki::Toolkit(3pm) | User Contributed Perl Documentation | Wiki::Toolkit(3pm) |
NAME¶
Wiki::Toolkit - A toolkit for building Wikis.DESCRIPTION¶
Helps you develop Wikis quickly by taking care of the boring bits for you. You will still need to write some code - this isn't an instant Wiki.SYNOPSIS¶
# Set up a wiki object with an SQLite storage backend, and an # inverted index/DB_File search backend. This store/search # combination can be used on systems with no access to an actual # database server. my $store = Wiki::Toolkit::Store::SQLite->new( dbname => "/home/wiki/store.db" ); my $indexdb = Search::InvertedIndex::DB::DB_File_SplitHash->new( -map_name => "/home/wiki/indexes.db", -lock_mode => "EX" ); my $search = Wiki::Toolkit::Search::SII->new( indexdb => $indexdb ); my $wiki = Wiki::Toolkit->new( store => $store, search => $search ); # Do all the CGI stuff. my $q = CGI->new; my $action = $q->param("action"); my $node = $q->param("node"); if ($action eq 'display') { my $raw = $wiki->retrieve_node($node); my $cooked = $wiki->format($raw); print_page(node => $node, content => $cooked); } elsif ($action eq 'preview') { my $submitted_content = $q->param("content"); my $preview_html = $wiki->format($submitted_content); print_editform(node => $node, content => $submitted_content, preview => $preview_html); } elsif ($action eq 'commit') { my $submitted_content = $q->param("content"); my $cksum = $q->param("checksum"); my $written = $wiki->write_node($node, $submitted_content, $cksum); if ($written) { print_success($node); } else { handle_conflict($node, $submitted_content); } }
METHODS¶
- new
-
# Set up store, search and formatter objects. my $store = Wiki::Toolkit::Store::SQLite->new( dbname => "/home/wiki/store.db" ); my $indexdb = Search::InvertedIndex::DB::DB_File_SplitHash->new( -map_name => "/home/wiki/indexes.db", -lock_mode => "EX" ); my $search = Wiki::Toolkit::Search::SII->new( indexdb => $indexdb ); my $formatter = My::HomeMade::Formatter->new; my $wiki = Wiki::Toolkit->new( store => $store, # mandatory search => $search, # defaults to undef formatter => $formatter # defaults to something suitable );
my $formatter = Test::MockObject->new(); $formatter->mock( 'format', sub { my ($self, $raw) = @_; return uc( $raw ); } );
- retrieve_node
-
my $content = $wiki->retrieve_node($node); # Or get additional data about the node as well. my %node = $wiki->retrieve_node("HomePage"); print "Current Version: " . $node{version}; # Maybe we stored some of our own custom metadata too. my $categories = $node{metadata}{category}; print "Categories: " . join(", ", @$categories); print "Postcode: $node{metadata}{postcode}[0]"; # Or get an earlier version: my %node = $wiki->retrieve_node( name => "HomePage", version => 2, ); print $node{content};
- last_modified
- version
- checksum
- metadata - a reference to a hash containing any caller-supplied metadata sent along the last time the node was written
- moderate_node
-
my $ok = $wiki->moderate_node(name => $node, version => $version);
- set_node_moderation
-
my $ok = $wiki->set_node_moderation(name => $node, required => $required);
- rename_node
-
my $ok = $wiki->rename_node(old_name => $old_name, new_name => $new_name, create_new_versions => $create_new_versions );
- verify_checksum
-
my $ok = $wiki->verify_checksum($node, $checksum);
- list_backlinks
-
# List all nodes that link to the Home Page. my @links = $wiki->list_backlinks( node => "Home Page" );
- list_dangling_links
-
# List all nodes that have been linked to from other nodes but don't # yet exist. my @links = $wiki->list_dangling_links;
- list_all_nodes
-
my @nodes = $wiki->list_all_nodes;
- list_nodes_by_metadata
-
# All documentation nodes. my @nodes = $wiki->list_nodes_by_metadata( metadata_type => "category", metadata_value => "documentation", ignore_case => 1, # optional but recommended (see below) ); # All pubs in Hammersmith. my @pubs = $wiki->list_nodes_by_metadata( metadata_type => "category", metadata_value => "Pub", ); my @hsm = $wiki->list_nodes_by_metadata( metadata_type => "category", metadata_value => "Hammersmith", ); my @results = my_l33t_method_for_ANDing_arrays( \@pubs, \@hsm );
- list_nodes_by_missing_metadata Returns nodes where either the metadata doesn't exist, or is blank
- Unlike list_nodes_by_metadata(), the metadata value
is optional (the metadata type is required).
# All nodes missing documentation my @nodes = $store->list_nodes_by_missing_metadata( metadata_type => "category", metadata_value => "documentation", ignore_case => 1, # optional but recommended (see below) ); # All nodes which don't have a latitude defined my @nodes = $store->list_nodes_by_missing_metadata( metadata_type => "latitude" );
- list_recent_changes
- This is documented in Wiki::Toolkit::Store::Database; see
there for parameters and return values. All parameters are passed through
directly to the store object, so, for example,
my @nodes = $wiki->list_recent_changes( days => 7 );
my @nodes = $wiki->store->list_recent_changes( days => 7 );
- list_unmoderated_nodes
-
my @nodes = $wiki->list_unmoderated_nodes(); my @nodes = $wiki->list_unmoderated_nodes( only_where_latest => 1 ); $nodes[0]->{'name'} # The name of the node $nodes[0]->{'node_id'} # The id of the node $nodes[0]->{'version'} # The version in need of moderation $nodes[0]->{'moderated_version'} # The newest moderated version Fetches details of all the node versions that require moderation (id, name, version, and latest moderated version). If only_where_latest is set, then only the latest version of nodes where the latest version needs moderating are returned. Otherwise, all node versions (including old ones, and possibly multiple per node) are returned.
- list_node_all_versions
-
my @versions = $wiki->list_node_all_versions("HomePage"); my @versions = $wiki->list_node_all_versions( name => 'HomePage', with_content => 1, with_metadata => 0 );
- list_last_version_before List the last version of every node before a given date. If no version existed before that date, will return undef for version. Returns a hash of id, name, version and date
-
my @nv = $wiki->list_last_version_before('2007-01-02 10:34:11') foreach my $data (@nv) { }
- node_exists
-
my $ok = $wiki->node_exists( "Wombat Defenestration" ); # or ignore case - optional but recommended my $ok = $wiki->node_exists( name => "monkey brains", ignore_case => 1, );
- node_required_moderation
-
my $needs = $wiki->node_required_moderation( "Wombat Defenestration" );
- delete_node
-
$wiki->delete_node( name => "Home Page", version => 15 );
- search_nodes
-
# Find all the nodes which contain the word 'expert'. my %results = $wiki->search_nodes('expert');
- supports_phrase_searches
-
if ( $wiki->supports_phrase_searches ) { return $wiki->search_nodes( '"fox in socks"' ); }
- supports_fuzzy_searches
-
if ( $wiki->supports_fuzzy_searches ) { return $wiki->fuzzy_title_match( 'Kings Cross, St Pancreas' ); }
- fuzzy_title_match
- NOTE: This section of the documentation assumes you
are using a search engine which supports fuzzy matching. (See above.) The
Wiki::Toolkit::Search::DBIxFTS backend in particular does not.
$wiki->write_node( "King's Cross St Pancras", "A station." ); my %matches = $wiki->fuzzy_title_match( "Kings Cross St. Pancras" );
- register_plugin
-
my $plugin = Wiki::Toolkit::Plugin::Foo->new; $wiki->register_plugin( plugin => $plugin );
- get_registered_plugins
-
my @plugins = $wiki->get_registered_plugins;
- write_node
-
my $written = $wiki->write_node($node, $content, $checksum, \%metadata, $requires_moderation); if ($written) { display_node($node); } else { handle_conflict(); }
$wiki->write_node( "Calthorpe Arms", "nice pub", $checksum, { category => [ "Pubs", "Bloomsbury" ], postcode => "WC1X 8JR" } ); # and later my @nodes = $wiki->list_nodes_by_metadata( metadata_type => "category", metadata_value => "Pubs" );
- format
-
my $cooked = $wiki->format($raw, $metadata);
- store
-
my $store = $wiki->store; my $dbname = eval { $wiki->store->dbname; } or warn "Not a DB backend";
- search_obj
-
my $search_obj = $wiki->search_obj;
- formatter
-
my $formatter = $wiki->formatter;
SEE ALSO¶
For a very quick Wiki startup without any of that icky programming stuff, see Tom Insam's Wiki::Toolkit::Kwiki, an instant wiki based on Wiki::Toolkit. Or for the specialised application of a wiki about a city, see the OpenGuides distribution. Wiki::Toolkit allows you to use different formatting modules. Text::WikiFormat might be useful for anyone wanting to write a custom formatter. Existing formatters include:- •
- Wiki::Toolkit::Formatter::Default (in this distro)
- •
- Wiki::Toolkit::Formatter::Pod
- •
- Wiki::Toolkit::Formatter::UseMod
- •
- Wiki::Toolkit::Store::MySQL (in this distro)
- •
- Wiki::Toolkit::Store::Pg (in this distro)
- •
- Wiki::Toolkit::Store::SQLite (in this distro)
- •
- Wiki::Toolkit::Store::Database (parent class for the above - in this distro)
- •
- Wiki::Toolkit::Search::DBIxFTS (in this distro, uses DBIx::FullTextSearch)
- •
- Wiki::Toolkit::Search::SII (in this distro, uses Search::InvertedIndex)
- •
- Wiki::Toolkit::Plugin::GeoCache
- •
- Wiki::Toolkit::Plugin::Categoriser
- •
- Wiki::Toolkit::Plugin::Locator::UK
- •
- Wiki::Toolkit::Plugin::RSS::ModWiki
- •
- Wiki::Toolkit::TestConfig::Utilities (in this distro)
- •
- CGI::Kwiki (an instant wiki)
- •
- CGI::pWiki
- •
- AxKit::XSP::Wiki
- •
- Apache::MiniWiki
- •
- UseModWiki <http://usemod.com>
- •
- Chiq Chaq <http://chiqchaq.sourceforge.net/>
AUTHOR¶
Kake Pugh (kake@earth.li) and the Wiki::Toolkit team (including Nick Burch and Dominic Hargreaves)SUPPORT¶
Questions should go to cgi-wiki-dev@earth.li.COPYRIGHT¶
Copyright (C) 2002-2004 Kake Pugh. All Rights Reserved. Copyright (C) 2006-2012 the Wiki::Toolkit team. All Rights Reserved.This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
FEEDBACK¶
The developer web site and bug tracker is athttp://www.wiki-toolkit.org/ - please file bugs there as appropriate. You could also subscribe to the dev list at
http://www.earth.li/cgi-bin/mailman/listinfo/cgi-wiki-dev
BUGS¶
Versions between 0.75 and 0.79 inclusive contain a bug which prevents Recent Changes routines from working correctly if minor changes are excluded <http://www.wiki-toolkit.org/ticket/41>. You may wish to avoid upgrading to this version until it is fixed if this is important to you; the fix is however not trivial so noone has been able to step up yet. Other minor bugs are documented at <http://www.wiki-toolkit.org/report>CREDITS¶
Various London.pm types helped out with code review, encouragement, JFDI, style advice, code snippets, module recommendations, and so on; far too many to name individually, but particularly Richard Clamp, Tony Fisher, Mark Fowler, and Chris Ball. blair christensen sent patches and gave me some good ideas. chromatic continues to patiently apply my patches to Text::WikiFormat and help me get it working in just the way I need. Paul Makepeace helped me add support for connecting to non-local databases. Shevek has been prodding me a lot lately. The OpenGuides team keep me well-supplied with encouragement and bug reports. Nick Burch has been leading the way with development leading up to the release under the Wiki::Toolkit name.GRATUITOUS PLUG¶
I'm only obsessed with Wikis because of the Open Guide to London -- <http://openguides.org/london/>2012-05-28 | perl v5.14.2 |