1Wiki::Toolkit(3) User Contributed Perl Documentation Wiki::Toolkit(3)
2
6 Wiki::Toolkit - A toolkit for building Wikis.
7
9 Helps you develop Wikis quickly by taking care of the boring bits for
10 you. You will still need to write some code - this isn't an instant
11 Wiki.
12
14 # Set up a wiki object with an SQLite storage backend, and an
15 # inverted index/DB_File search backend. This store/search
16 # combination can be used on systems with no access to an actual
17 # database server.
18 #
19 # The database should already exist; it can be created using
20 # the supplied wiki-toolkit-setupdb script.
21 my $store = Wiki::Toolkit::Store::SQLite->new(
23 dbname => "/home/wiki/store.db" );
24 my $indexdb = Search::InvertedIndex::DB::DB_File_SplitHash->new(
25 -map_name => "/home/wiki/indexes.db",
26 -lock_mode => "EX" );
27 my $search = Wiki::Toolkit::Search::SII->new(
28 indexdb => $indexdb );
29 my $wiki = Wiki::Toolkit->new( store => $store,
31 search => $search );
32 # Do all the CGI stuff.
34 my $q = CGI->new;
35 my $action = $q->param("action");
36 my $node = $q->param("node");
37 if ($action eq 'display') {
39 my $raw = $wiki->retrieve_node($node);
40 my $cooked = $wiki->format($raw);
41 print_page(node => $node,
42 content => $cooked);
43 } elsif ($action eq 'preview') {
44 my $submitted_content = $q->param("content");
45 my $preview_html = $wiki->format($submitted_content);
46 print_editform(node => $node,
47 content => $submitted_content,
48 preview => $preview_html);
49 } elsif ($action eq 'commit') {
50 my $submitted_content = $q->param("content");
51 my $cksum = $q->param("checksum");
52 my $written = $wiki->write_node($node, $submitted_content, $cksum);
53 if ($written) {
54 print_success($node);
55 } else {
56 handle_conflict($node, $submitted_content);
57 }
58 }
59
61 new
62 # Set up store, search and formatter objects.
63 my $store = Wiki::Toolkit::Store::SQLite->new(
64 dbname => "/home/wiki/store.db" );
65 my $indexdb = Search::InvertedIndex::DB::DB_File_SplitHash->new(
66 -map_name => "/home/wiki/indexes.db",
67 -lock_mode => "EX" );
68 my $search = Wiki::Toolkit::Search::SII->new(
69 indexdb => $indexdb );
70 my $formatter = My::HomeMade::Formatter->new;
71 my $wiki = Wiki::Toolkit->new(
73 store => $store, # mandatory
74 search => $search, # defaults to undef
75 formatter => $formatter # defaults to something suitable
76 );
77 "store" must be an object of type "Wiki::Toolkit::Store::*" and
79 "search" if supplied must be of type "Wiki::Toolkit::Search::*"
80 (though this isn't checked yet - FIXME). If "formatter" isn't
81 supplied, it defaults to an object of class
82 Wiki::Toolkit::Formatter::Default.
83 You can get a searchable Wiki up and running on a system without an
85 actual database server by using the SQLite storage backend with the
86 SII/DB_File search backend - cut and paste the lines above for a
87 quick start, and see Wiki::Toolkit::Store::SQLite,
88 Wiki::Toolkit::Search::SII, and
89 Search::InvertedIndex::DB::DB_File_SplitHash when you want to learn
90 the details.
91 "formatter" can be any object that behaves in the right way; this
93 essentially means that it needs to provide a "format" method which
94 takes in raw text and returns the formatted version. See
95 Wiki::Toolkit::Formatter::Default for a simple example. Note that
96 you can create a suitable object from a sub very quickly by using
97 Test::MockObject like so:
98 my $formatter = Test::MockObject->new();
100 $formatter->mock( 'format', sub { my ($self, $raw) = @_;
101 return uc( $raw );
102 } );
103 I'm not sure whether to put this in the module or not - it'd let
105 you just supply a sub instead of an object as the formatter, but it
106 feels wrong to be using a Test::* module in actual code.
107 retrieve_node
109 my $content = $wiki->retrieve_node($node);
110 # Or get additional data about the node as well.
112 my %node = $wiki->retrieve_node("HomePage");
113 print "Current Version: " . $node{version};
114 # Maybe we stored some of our own custom metadata too.
116 my $categories = $node{metadata}{category};
117 print "Categories: " . join(", ", @$categories);
118 print "Postcode: $node{metadata}{postcode}[0]";
119 # Or get an earlier version:
121 my %node = $wiki->retrieve_node( name => "HomePage",
122 version => 2,
123 );
124 print $node{content};
125 In scalar context, returns the current (raw Wiki language) contents
127 of the specified node. In list context, returns a hash containing
128 the contents of the node plus additional data:
129 last_modified
131 version
132 checksum
133 metadata - a reference to a hash containing any caller-supplied
134 metadata sent along the last time the node was written
135 The "node" parameter is mandatory. The "version" parameter is
137 optional and defaults to the newest version. If the node hasn't
138 been created yet, it is considered to exist but be empty (this
139 behaviour might change).
140 Note on metadata - each hash value is returned as an array ref,
142 even if that type of metadata only has one value.
143 moderate_node
145 my $ok = $wiki->moderate_node(name => $node, version => $version);
146 Marks the given version of the node as moderated. If this is the
148 highest moderated version, then update the node's contents to hold
149 this version.
150 set_node_moderation
152 my $ok = $wiki->set_node_moderation(name => $node, required => $required);
153 Sets if a node requires moderation or not. (Moderation is required
155 when $required is true).
156 When moderation is required, new versions of a node will sit about
158 until they're tagged as moderated, when they will become the new
159 node.
160 rename_node
162 my $ok = $wiki->rename_node(old_name => $old_name, new_name => $new_name, create_new_versions => $create_new_versions );
163 Renames a node, updating any references to it as required.
165 Uses the internal_links table to identify the nodes that link to
167 this one, and re-writes any wiki links in these to point to the new
168 name. If required, it can mark these updates to other pages as a
169 new version.
170 verify_checksum
172 my $ok = $wiki->verify_checksum($node, $checksum);
173 Sees whether your checksum is current for the given node. Returns
175 true if so, false if not.
176 NOTE: Be aware that when called directly and without locking, this
178 might not be accurate, since there is a small window between the
179 checking and the returning where the node might be changed, so
180 don't rely on it for safe commits; use "write_node" for that. It
181 can however be useful when previewing edits, for example.
182 list_backlinks
184 # List all nodes that link to the Home Page.
185 my @links = $wiki->list_backlinks( node => "Home Page" );
186 list_dangling_links
188 # List all nodes that have been linked to from other nodes but don't
189 # yet exist.
190 my @links = $wiki->list_dangling_links;
191 Each node is returned once only, regardless of how many other nodes
193 link to it.
194 list_all_nodes
196 my @nodes = $wiki->list_all_nodes;
197 Returns a list containing the name of every existing node. The
199 list won't be in any kind of order; do any sorting in your calling
200 script.
201 list_nodes_by_metadata
203 # All documentation nodes.
204 my @nodes = $wiki->list_nodes_by_metadata(
205 metadata_type => "category",
206 metadata_value => "documentation",
207 ignore_case => 1, # optional but recommended (see below)
208 );
209 # All pubs in Hammersmith.
211 my @pubs = $wiki->list_nodes_by_metadata(
212 metadata_type => "category",
213 metadata_value => "Pub",
214 );
215 my @hsm = $wiki->list_nodes_by_metadata(
216 metadata_type => "category",
217 metadata_value => "Hammersmith",
218 );
219 my @results = my_l33t_method_for_ANDing_arrays( \@pubs, \@hsm );
220 Returns a list containing the name of every node whose caller-
222 supplied metadata matches the criteria given in the parameters.
223 By default, the case-sensitivity of both "metadata_type" and
225 "metadata_value" depends on your database - if it will return rows
226 with an attribute value of "Pubs" when you asked for "pubs", or
227 not. If you supply a true value to the "ignore_case" parameter,
228 then you can be sure of its being case-insensitive. This is
229 recommended.
230 If you don't supply any criteria then you'll get an empty list.
232 This is a really really really simple way of finding things; if you
234 want to be more complicated then you'll need to call the method
235 multiple times and combine the results yourself, or write a plugin.
236 list_nodes_by_missing_metadata Returns nodes where either the metadata
238 doesn't exist, or is blank
239 Unlike list_nodes_by_metadata(), the metadata value is optional
240 (the metadata type is required).
241 # All nodes missing documentation
243 my @nodes = $store->list_nodes_by_missing_metadata(
244 metadata_type => "category",
245 metadata_value => "documentation",
246 ignore_case => 1, # optional but recommended (see below)
247 );
248 # All nodes which don't have a latitude defined
250 my @nodes = $store->list_nodes_by_missing_metadata(
251 metadata_type => "latitude"
252 );
253 list_recent_changes
255 This is documented in Wiki::Toolkit::Store::Database; see there for
256 parameters and return values. All parameters are passed through
257 directly to the store object, so, for example,
258 my @nodes = $wiki->list_recent_changes( days => 7 );
260 does exactly the same thing as
262 my @nodes = $wiki->store->list_recent_changes( days => 7 );
264 list_unmoderated_nodes
266 my @nodes = $wiki->list_unmoderated_nodes();
267 my @nodes = $wiki->list_unmoderated_nodes(
268 only_where_latest => 1
269 );
270 $nodes[0]->{'name'} # The name of the node
272 $nodes[0]->{'node_id'} # The id of the node
273 $nodes[0]->{'version'} # The version in need of moderation
274 $nodes[0]->{'moderated_version'} # The newest moderated version
275 Fetches details of all the node versions that require moderation (id,
277 name, version, and latest moderated version).
278 If only_where_latest is set, then only the latest version of nodes where
280 the latest version needs moderating are returned.
281 Otherwise, all node versions (including old ones, and possibly multiple
282 per node) are returned.
283 list_node_all_versions
285 my @versions = $wiki->list_node_all_versions("HomePage");
286 my @versions = $wiki->list_node_all_versions(
288 name => 'HomePage',
289 with_content => 1,
290 with_metadata => 0
291 );
292 Returns all the versions of a node, optionally including the
294 content and metadata, as an array of hashes (newest versions
295 first).
296 list_last_version_before List the last version of every node before a
298 given date. If no version existed before that date, will return undef
299 for version. Returns a hash of id, name, version and date
300 my @nv = $wiki->list_last_version_before('2007-01-02 10:34:11')
301 foreach my $data (@nv) {
302 }
304 node_exists
306 my $ok = $wiki->node_exists( "Wombat Defenestration" );
307 # or ignore case - optional but recommended
309 my $ok = $wiki->node_exists(
310 name => "monkey brains",
311 ignore_case => 1,
312 );
313 Returns true if the node has ever been created (even if it is
315 currently empty), and false otherwise.
316 By default, the case-sensitivity of "node_exists" depends on your
318 store backend. If you supply a true value to the "ignore_case"
319 parameter, then you can be sure of its being case-insensitive.
320 This is recommended.
321 node_required_moderation
323 my $needs = $wiki->node_required_moderation( "Wombat Defenestration" );
324 Returns true if the node exists and requires moderation, and false
326 otherwise.
327 delete_node
329 $wiki->delete_node( name => "Home Page", version => 15 );
330 "version" is optional. If it is supplied then only that version of
332 the node will be deleted. Otherwise the node and all its history
333 will be completely deleted.
334 Doesn't do any locking though - to fix? You probably don't want to
336 let anyone except Wiki admins call this. You may not want to use it
337 at all.
338 Croaks on error, silently does nothing if the node or version
340 doesn't exist, returns true if no error.
341 search_nodes
343 # Find all the nodes which contain the word 'expert'.
344 my %results = $wiki->search_nodes('expert');
345 Returns a (possibly empty) hash whose keys are the node names and
347 whose values are the scores in some kind of relevance-scoring
348 system I haven't entirely come up with yet. For OR searches, this
349 could initially be the number of terms that appear in the node,
350 perhaps.
351 Defaults to AND searches (if $and_or is not supplied, or is
353 anything other than "OR" or "or").
354 Searches are case-insensitive.
356 Croaks if you haven't defined a search backend.
358 supports_phrase_searches
360 if ( $wiki->supports_phrase_searches ) {
361 return $wiki->search_nodes( '"fox in socks"' );
362 }
363 Returns true if your chosen search backend supports phrase
365 searching, and false otherwise.
366 supports_fuzzy_searches
368 if ( $wiki->supports_fuzzy_searches ) {
369 return $wiki->fuzzy_title_match( 'Kings Cross, St Pancreas' );
370 }
371 Returns true if your chosen search backend supports fuzzy title
373 searching, and false otherwise.
374 fuzzy_title_match
376 NOTE: This section of the documentation assumes you are using a
377 search engine which supports fuzzy matching. (See above.) The
378 Wiki::Toolkit::Search::DBIxFTS backend in particular does not.
379 $wiki->write_node( "King's Cross St Pancras", "A station." );
381 my %matches = $wiki->fuzzy_title_match( "Kings Cross St. Pancras" );
382 Returns a (possibly empty) hash whose keys are the node names and
384 whose values are the scores in some kind of relevance-scoring
385 system I haven't entirely come up with yet.
386 Note that even if an exact match is found, any other similar enough
388 matches will also be returned. However, any exact match is
389 guaranteed to have the highest relevance score.
390 The matching is done against "canonicalised" forms of the search
392 string and the node titles in the database: stripping vowels,
393 repeated letters and non-word characters, and lowercasing.
394 Croaks if you haven't defined a search backend.
396 register_plugin
398 my $plugin = Wiki::Toolkit::Plugin::Foo->new;
399 $wiki->register_plugin( plugin => $plugin );
400 Registers the plugin with the wiki as one that needs to be informed
402 when we write a node.
403 If the plugin "isa" Wiki::Toolkit::Plugin, calls the methods set up
405 by that parent class to let it know about the backend store, search
406 and formatter objects.
407 Finally, calls the plugin class's "on_register" method, which
409 should be used to check tables are set up etc. Note that because of
410 the order these things are done in, "on_register" for
411 Wiki::Toolkit::Plugin subclasses can use the "datastore", "indexer"
412 and "formatter" methods as it needs to.
413 get_registered_plugins
415 my @plugins = $wiki->get_registered_plugins;
416 Returns an array of plugin objects.
418 write_node
420 my $written = $wiki->write_node($node, $content, $checksum, \%metadata, $requires_moderation);
421 if ($written) {
422 display_node($node);
423 } else {
424 handle_conflict();
425 }
426 Writes the specified content into the specified node in the backend
428 storage; and indexes/reindexes the node in the search indexes (if a
429 search is set up); calls "post_write" on any registered plugins.
430 Note that you can blank out a node without deleting it by passing
432 the empty string as $content, if you want to.
433 If you expect the node to already exist, you must supply a
435 checksum, and the node is write-locked until either your checksum
436 has been proved old, or your checksum has been accepted and your
437 change committed. If no checksum is supplied, and the node is
438 found to already exist and be nonempty, a conflict will be raised.
439 The first two parameters are mandatory, the others optional. If you
441 want to supply metadata but have no checksum (for a newly-created
442 node), supply a checksum of "undef".
443 The final parameter, $requires_moderation (which defaults to
445 false), is ignored except on new nodes. For existing nodes, use
446 $wiki->toggle_node_moderation to change the node moderation flag.
447 Returns the version of the updated node on success, 0 on conflict,
449 croaks on error.
450 Note on the metadata hashref: Any data in here that you wish to
452 access directly later must be a key-value pair in which the value
453 is either a scalar or a reference to an array of scalars. For
454 example:
455 $wiki->write_node( "Calthorpe Arms", "nice pub", $checksum,
457 { category => [ "Pubs", "Bloomsbury" ],
458 postcode => "WC1X 8JR" } );
459 # and later
461 my @nodes = $wiki->list_nodes_by_metadata(
463 metadata_type => "category",
464 metadata_value => "Pubs" );
465 For more advanced usage (passing data through to registered
467 plugins) you may if you wish pass key-value pairs in which the
468 value is a hashref or an array of hashrefs. The data in the
469 hashrefs will not be stored as metadata; it will be checksummed and
470 the checksum will be stored instead. Such data can only be accessed
471 via plugins.
472 format
474 my $cooked = $wiki->format($raw, $metadata);
475 Passed straight through to your chosen formatter object. You do not
477 have to supply the $metadata hashref, but if your formatter allows
478 node metadata to affect the rendering of the node then you will
479 want to.
480 store
482 my $store = $wiki->store;
483 my $dbname = eval { $wiki->store->dbname; }
484 or warn "Not a DB backend";
485 Returns the storage backend object.
487 search_obj
489 my $search_obj = $wiki->search_obj;
490 Returns the search backend object.
492 formatter
494 my $formatter = $wiki->formatter;
495 Returns the formatter backend object.
497
499 For a very quick Wiki startup without any of that icky programming
500 stuff, see Tom Insam's Wiki::Toolkit::Kwiki, an instant wiki based on
501 Wiki::Toolkit.
502 Or for the specialised application of a wiki about a city, see the
504 OpenGuides distribution.
505 Wiki::Toolkit allows you to use different formatting modules.
507 Text::WikiFormat might be useful for anyone wanting to write a custom
508 formatter. Existing formatters include:
509 • Wiki::Toolkit::Formatter::Default (in this distro)
511 • Wiki::Toolkit::Formatter::Pod
513 • Wiki::Toolkit::Formatter::UseMod
515 There's currently a choice of three storage backends - all database-
517 backed.
518 • Wiki::Toolkit::Store::MySQL (in this distro)
520 • Wiki::Toolkit::Store::Pg (in this distro)
522 • Wiki::Toolkit::Store::SQLite (in this distro)
524 • Wiki::Toolkit::Store::Database (parent class for the above - in
526 this distro)
527 A search backend is optional:
529 • Wiki::Toolkit::Search::DBIxFTS (in this distro, uses
531 DBIx::FullTextSearch)
532 • Wiki::Toolkit::Search::SII (in this distro, uses
534 Search::InvertedIndex)
535 Standalone plugins can also be written - currently they should only
537 read from the backend storage, but write access guidelines are coming
538 soon. Plugins written so far and available from CPAN:
539 • Wiki::Toolkit::Plugin::GeoCache
541 • Wiki::Toolkit::Plugin::Categoriser
543 • Wiki::Toolkit::Plugin::Locator::UK
545 • Wiki::Toolkit::Plugin::RSS::ModWiki
547 If writing a plugin you might want an easy way to run tests for it on
549 all possible backends:
550 • Wiki::Toolkit::TestConfig::Utilities (in this distro)
552 Other ways to implement Wikis in Perl include:
554 • CGI::Kwiki (an instant wiki)
556 • CGI::pWiki
558 • AxKit::XSP::Wiki
560 • Apache::MiniWiki
562 • UseModWiki <http://usemod.com>
564 • Chiq Chaq <http://chiqchaq.sourceforge.net/>
566
568 Kake Pugh (kake@earth.li) and the Wiki::Toolkit team (including Nick
569 Burch and Dominic Hargreaves)
570
572 Questions should go to cgi-wiki-dev@earth.li.
573
575 Copyright (C) 2002-2004 Kake Pugh. All Rights Reserved.
576 Copyright (C) 2006-2013 the Wiki::Toolkit team. All Rights Reserved.
577 This module is free software; you can redistribute it and/or modify it
579 under the same terms as Perl itself.
580
582 The developer web site and bug tracker is at
583 http://www.wiki-toolkit.org/ - please file bugs there as appropriate.
584 You could also subscribe to the dev list at
586 http://www.earth.li/cgi-bin/mailman/listinfo/cgi-wiki-dev
587
589 Bugs are documented at
590 <https://github.com/OpenGuides/Wiki-Toolkit/issues>
591
593 Various London.pm types helped out with code review, encouragement,
594 JFDI, style advice, code snippets, module recommendations, and so on;
595 far too many to name individually, but particularly Richard Clamp, Tony
596 Fisher, Mark Fowler, and Chris Ball.
597 blair christensen sent patches and gave me some good ideas. chromatic
599 continues to patiently apply my patches to Text::WikiFormat and help me
600 get it working in just the way I need. Paul Makepeace helped me add
601 support for connecting to non-local databases. Shevek has been prodding
602 me a lot lately. The OpenGuides team keep me well-supplied with
603 encouragement and bug reports.
604 Nick Burch has been leading the way with development leading up to the
606 release under the Wiki::Toolkit name.
607
609 I'm only obsessed with Wikis because of the Open Guide to London --
610 <http://openguides.org/london/>
611perl v5.34.0 2022-01-21 Wiki::Toolkit(3)