1Wiki::Toolkit::ExtendinUgs(e3r)Contributed Perl DocumentWaitkiio:n:Toolkit::Extending(3)
2
6 Extending.pod - How to extend Wiki::Toolkit with your own plugins.
7
9 The extension mechanism is currently only defined for database-backed
10 setups, but since nobody has written any other kind of backend I think
11 we're fine for now.
12
14 You can extend Wiki::Toolkit in a fairly simplified way without the use
15 of plugins, by supplying a hash of metadata when you write a node. For
16 example:
17 $wiki->write_node( $node, $content, $checksum,
19 { postcode => $postcode } );
20 and on node retrieval you'll get it back again:
22 my %node = $wiki->retrieve_node( $node );
24 my $postcode = $node{metadata}{postcode}[0];
25 You can supply more than one value for each type of metadata:
27 $wiki->write_node( $node, $content, $checksum,
29 { postcode => "W6 9PL",
30 category => [ "Thai Food", "Restaurant", "Hammersmith" ] } );
31 And get back a list of nodes which have a given value for a given
33 metadata type:
34 my @nodes = $wiki->list_nodes_by_metadata(
36 metadata_type => "category",
37 metadata_value => "Hammersmith" );
38 For anything more complicated you will need to write a plugin.
40
42 Plugins should inherit from "Wiki::Toolkit::Plugin". This base class
43 provides the following methods to give access to a "Wiki::Toolkit"
44 object's backends:
45 • "datastore" - returns the store object
47 • "indexer" - returns the search object
49 • "formatter" - returns the formatter object
51 If you want these methods to return anything useful then call
53 $wiki->register_plugin( plugin => $plugin);
55 before calling say
57 my %node_data = $plugin->datastore->retrieve_node( "Foo" );
59
61 my $plugin = Wiki::Toolkit::Plugin::Foo->new( ...any required args... );
62 $wiki->register_plugin( plugin => $plugin );
63 $wiki->write_node( "Test Node" ,"Test", $checksum,
65 { foo_data => { a => "apple",
66 b => "banana" }
67 } );
68 my $bee = $plugin->get_word( node => "Test Node", letter => "b" );
70 or
72 my $plugin = OpenGuides::London::Underground->new;
74 $wiki->register_plugin( plugin => $plugin );
75 $wiki->write_node( "Hammersmith Station", "a station", $checksum,
76 { tube_data => [
77 { line => "Piccadilly",
78 direction => "Eastbound",
79 next_station => "Baron's Court Station"
80 },
81 { line => "Piccadilly",
82 direction => "Westbound",
83 next_station => "Acton Town Station"
84 }
85 ]
86 }
87 );
88 # Put more data in, then
90 my @route = $plugin->find_route( from => "Holborn Station",
92 to => "Acton Town Station" );
93
95 A plugin named Wiki::Toolkit::Plugin::Foo may access the backend
96 database directly like so:
97 • Read-only access to any table
99 • Read-write access to any table whose name begins with "p_" .
101 $Wiki::Toolkit::Plugin::Foo::plugin_key . "_"
102 $Wiki::Toolkit::Plugin::Foo::plugin_key should be different from
104 the keys of all other plugins. No, I haven't set anything up to
105 ensure this.
106
108 Either be database-agnostic, or state clearly in your docs which
109 databases you support, and handle errors nicely. Be aware that non-
110 database backends may exist in the future.
111 Be aware of whether you need to check for locks explicitly in different
113 databases (see code of Wiki::Toolkit::Store::* to find out).
114
116 on_register
117 Check that any tables you require are set up, and set them up if
118 not.
119
121 post_write
122 This will be called every time a node is written, with the
123 arguments like so:
124 $plugin->post_write( node => $node_name,
126 version => $version_number,
127 content => $content,
128 metadata => \%user_defined_metadata );
129 This will happen after the node data is all written, but before any
131 lock is released.
132 We could probably reimplement the searches as plugins like this if
134 we want to, but this will require writing extra backends for
135 Search::InvertedIndex so it can work within the same database.
136 The user-defined metadata will already have been stored in the
138 backend but it is available here for you to do what you will with
139 it.
140 Its return value should be true on success and false on error.
142 post_read
144 THIS IS NOT YET IMPLEMENTED.
145 This will be called every time a node is read, with the arguments
147 like so:
148 $plugin->post_read( node => $node_name,
150 version => $version_number,
151 content => $content,
152 metadata => \%user_defined_metadata );
153 It cannot affect the data returned to the caller. It should be used
155 for its side-effects, for example tracking the number of times a
156 given node is accessed.
157 Its return value should be true on success and false on error.
159
161 What if we have more than one plugin registered? What if we change the
162 mechanism to allow the plugins to change the data stored in the
163 database/returned to the caller?
164perl v5.38.0 2023-07-21 Wiki::Toolkit::Extending(3)