1Wiki::Toolkit::ExtendinUgs(e3r)Contributed Perl DocumentWaitkiio:n:Toolkit::Extending(3)
2
3
4

NAME

6       Extending.pod - How to extend Wiki::Toolkit with your own plugins.
7

LIMITATIONS

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

THE SIMPLEST WAY

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
18         $wiki->write_node( $node, $content, $checksum,
19                            { postcode => $postcode }   );
20
21       and on node retrieval you'll get it back again:
22
23         my %node = $wiki->retrieve_node( $node );
24         my $postcode = $node{metadata}{postcode}[0];
25
26       You can supply more than one value for each type of metadata:
27
28         $wiki->write_node( $node, $content, $checksum,
29             { postcode => "W6 9PL",
30               category => [ "Thai Food", "Restaurant", "Hammersmith" ] } );
31
32       And get back a list of nodes which have a given value for a given
33       metadata type:
34
35         my @nodes = $wiki->list_nodes_by_metadata(
36             metadata_type  => "category",
37             metadata_value => "Hammersmith" );
38
39       For anything more complicated you will need to write a plugin.
40

PLUGIN BASE CLASS

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
46       •   "datastore" - returns the store object
47
48       •   "indexer" - returns the search object
49
50       •   "formatter" - returns the formatter object
51
52       If you want these methods to return anything useful then call
53
54         $wiki->register_plugin( plugin => $plugin);
55
56       before calling say
57
58         my %node_data = $plugin->datastore->retrieve_node( "Foo" );
59

CALLING API

61         my $plugin = Wiki::Toolkit::Plugin::Foo->new( ...any required args... );
62         $wiki->register_plugin( plugin => $plugin );
63
64         $wiki->write_node( "Test Node" ,"Test", $checksum,
65                            { foo_data => { a => "apple",
66                                            b => "banana" }
67                            } );
68
69         my $bee = $plugin->get_word( node => "Test Node", letter => "b" );
70
71       or
72
73         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
89         # Put more data in, then
90
91         my @route = $plugin->find_route( from => "Holborn Station",
92                                          to   => "Acton Town Station" );
93

STORE ACCESS

95       A plugin named Wiki::Toolkit::Plugin::Foo may access the backend
96       database directly like so:
97
98       •   Read-only access to any table
99
100       •   Read-write access to any table whose name begins with "p_" .
101           $Wiki::Toolkit::Plugin::Foo::plugin_key . "_"
102
103           $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

REQUIREMENTS FOR PLUGIN AUTHORS

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
112       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

REQUIRED METHODS

116       on_register
117           Check that any tables you require are set up, and set them up if
118           not.
119

OPTIONAL METHODS

121       post_write
122           This will be called every time a node is written, with the
123           arguments like so:
124
125             $plugin->post_write( node     => $node_name,
126                                  version  => $version_number,
127                                  content  => $content,
128                                  metadata => \%user_defined_metadata );
129
130           This will happen after the node data is all written, but before any
131           lock is released.
132
133           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
137           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
141           Its return value should be true on success and false on error.
142
143       post_read
144           THIS IS NOT YET IMPLEMENTED.
145
146           This will be called every time a node is read, with the arguments
147           like so:
148
149             $plugin->post_read( node     => $node_name,
150                                 version  => $version_number,
151                                 content  => $content,
152                                 metadata => \%user_defined_metadata );
153
154           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
158           Its return value should be true on success and false on error.
159

PLUGIN CONFLICTS

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?
164
165
166
167perl v5.34.0                      2022-01-21       Wiki::Toolkit::Extending(3)
Impressum