1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
# Movable Type (r) Open Source (C) 2001-2008 Six Apart, Ltd.
# This program is distributed under the terms of the
# GNU General Public License, version 2.
#
# $Id: Callback.pm 1174 2008-01-08 21:02:50Z bchoate $
package MT::Callback;
use strict;
use MT::ErrorHandler;
@MT::Callback::ISA = qw( MT::ErrorHandler );
sub new {
my $class = shift;
my ($cb) = ref$_[0] ? @_ : {@_};
bless $cb, $class;
}
sub name {
my $cb = shift;
$cb->{method} || $cb->{name};
}
sub method {
my $cb = shift;
$cb->{method};
}
sub invoke {
my $cb = shift;
unless (ref($cb->{code})) {
$cb->{code} = MT->handler_to_coderef($cb->{code});
}
return $cb->{code}->($cb, @_);
}
sub plugin {
my $cb = shift;
$cb->{plugin};
}
1;
__END__
=head1 NAME
MT::Callback - Movable Type wrapper for executable code with error state
=head1 SYNOPSIS
$cb = new MT::Callback(name => <name>, code => sub { <callback code> });
E<lt>nameE<gt> is a human-readable string which identifies the
surrounding body of code, for example the name of a plugin--the name
will help identify errors in the activity log.
=head1 METHODS
=head2 new(\%param) or new(%param)
Constructs a new object, using the given parameters. The parameters
recognized for a callback object are:
=over 4
=item name
The name of the callback.
=item code
A coderef that is invoked when running the callback.
=item plugin
The L<MT::Plugin> that is associated with this callback.
=item priority
The priority to assign for the callback, which determines the order
it is invoked when multiple callbacks are tied to the same method.
=item method
The name of the method this callback is associated with.
=back
=head2 $cb->name()
Returns the registered name of the callback.
=head2 $cb->invoke(@params)
Executes the callback, passing the MT::Callback object as the first
parameter, followed by any parameters sent to the invoke method.
=head2 $cb->plugin()
Returns the 'plugin' element associated with the callback object.
=head1 CALLBACK CALLING CONVENTIONS
The parameters passed to each callback routine depends on the operation
in questions, as follows:
=over 4
=item * load(), load_iter()
Before loading items from the database, load() and load_iter()
call the callback registered as <class>::pre_load, allowing a callback
writer to munge the arguments before the database is
called.
An example E<lt>classE<gt>::pre_load might be written as follows:
sub pre_load {
my ($cb, $args) = @_;
....
}
Each object I<returned> by load() or by an iterator will,
before it is returned, be processeed by all callbacks registered as
E<lt>classE<gt>::post_load. An example E<lt>classE<gt>::post_load
function
sub post_load {
my ($cb, $args, $obj) = @_;
....
}
The C<$args> parameter for both the C<pre_load> and C<post_load>
callback is an array reference of all parameters
that were supplied to the load or load_iter methods.
=item * save()
Callbacks for the save method might be written as follows:
sub pre_save {
my ($cb, $obj, $original) = @_;
....
}
sub post_save {
my ($cb, $obj, $original) = @_;
....
}
By altering the $obj in pre_save, you can affect what data gets stored
in the database.
By creating pre_save and post_load functions which have inverse
effects on the object, you might be able to store data in the database
in a special form, while keeping the usual in-memory representation.
=item * remove()
E<lt>classE<gt>::pre_remove and E<lt>classE<gt>::post_remove
are called at the very beginning and very end of the respective
operations. The callback routine is called as follows:
sub pre_remove {
my ($cb, $obj) = @_;
....
}
The signature for the post_remove operation is the same.
E<lt>classE<gt>::pre_remove_all and
E<lt>classE<gt>::post_remove_all are called at the very beginning and
very end of the respective operations, with no arguments except the
MT::Callback object.
=back
=head1 ERROR HANDLING
The first argument to any callback routine is an L<MT::Callback>
object. You can use this object to return errors to MT.
To signal an error, just use its error() method:
sub my_callback {
my ($cb, $arg2, $arg3) = @_;
....
if (some_condition) {
return $cb->error("The foofiddle was invalid.");
}
...
}
=head1 AUTHOR & COPYRIGHTS
Please see the I<MT> manpage for author, copyright, and license information.
=cut
|
