Item8749: added examples for before- and afterUploadHandler()

git-svn-id: http://svn.foswiki.org/trunk@6852 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

EmptyPlugin/lib/Foswiki/Plugins/EmptyPlugin.pm

@@ -587,7 +587,8 @@ The attributes hash will include at least the following attributes:
    * =user= - the user id
    * =tmpFilename= - name of a temporary file containing the attachment data
 
-*Since:* Foswiki::Plugins::VERSION = 2.0
+*Since:* Foswiki::Plugins::VERSION = 2.0,
+deprecated since 2.1; please use =beforeUploadHandler()= instead.
 
 =cut
 
@@ -597,7 +598,31 @@ The attributes hash will include at least the following attributes:
 
 =begin TML
 
+---++ beforeUploadHandler(\%attrHash, $meta )
+   * =\%attrHash= - reference to hash of attachment attribute values
+   * =$meta= - the topic object where the upload will happen
+
+This handler is called once when an attachment is uploaded. When this
+handler is called, the attachment has *not* been recorded in the database.
+
+The attributes hash will include at least the following attributes:
+   * =attachment= => the attachment name
+   * =comment= - the comment
+   * =user= - the user id
+   * =tmpFilename= - name of a temporary file containing the attachment data
+
+*Since:* Foswiki::Plugins::VERSION = 2.1,
+
+=cut
+
+#sub beforeUploadHandler {
+#    my( $attrHashRef, $topic, $web ) = @_;
+#}
+
+=begin TML
+
 ---++ afterAttachmentSaveHandler(\%attrHash, $topic, $web, $error )
+
    * =\%attrHash= - reference to hash of attachment attribute values
    * =$topic= - the name of the topic in the current CGI query
    * =$web= - the name of the web in the current CGI query
@@ -608,7 +633,9 @@ will include at least the following attributes:
    * =comment= - the comment
    * =user= - the user id
 
-*Since:* Foswiki::Plugins::VERSION = 2.0
+*Since:* Foswiki::Plugins::VERSION = 2.0, 
+deprecated since 2.1; please use =afterUploadHandler()= instead.
+
 
 =cut
 
@@ -618,6 +645,26 @@ will include at least the following attributes:
 
 =begin TML
 
+---++ afterUploadHandler(\%attrHash, $meta )
+   * =\%attrHash= - reference to hash of attachment attribute values
+   * =$meta= - a topic object pointing where the upload has happened
+
+This handler is called just after the save action. The attributes hash
+will include at least the following attributes:
+   * =attachment= => the attachment name
+   * =comment= - the comment
+   * =user= - the user id
+
+*Since:* Foswiki::Plugins::VERSION = 2.1
+
+=cut
+
+#sub afterUploadHandler {
+#    my( $attrHashRef, $meta ) = @_;
+#}
+
+=begin TML
+
 ---++ mergeHandler( $diff, $old, $new, \%info ) -> $text
 Try to resolve a difference encountered during merge. The =differences= 
 array is an array of hash references, where each hash contains the 
@@ -813,7 +860,7 @@ Foswiki::Support.Faq1
 =cut
 
 #sub restExample {
-#   my ($session) = @_;
+#   my ( $session, $subject, $verb, $response ) = @_;
 #   return "This is an example of a REST invocation\n\n";
 #}