[Spamassassin Wiki] Update of "PluginWritingTips" by MartinSchuette

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Spamassassin Wiki" for change notification.

The following page has been changed by MartinSchuette:
http://wiki.apache.org/spamassassin/PluginWritingTips

The comment on the change is:
show documented API got_hit() instead of internal _handle_hit()

------------------------------------------------------------------------------
      ...
      #Now we assume that the score you calculated is in $score
      
+ 
+     #optional: change the description for report and summary
+     my $description = $pms->{conf}->{descriptions}->{EXAMPLE_RULE_NAME};
+     $description .= " -- with score $score";
+     $pms->{conf}->{descriptions}->{EXAMPLE_RULE_NAME} = $description;
+ 
      #If the score is 0, then you don't need to do anything (obviously)
- 
      if($score) {
-         #Fetch the description of your rule from the configuration file
-         my $description = $pms->{conf}->{descriptions}->{EXAMPLE_RULE_NAME};
- 
          #The magic call
-         $pms->_handle_hit("EXAMPLE_RULE_NAME", $score, "HEADER: ", $description);
+         $pms->got_hit("EXAMPLE_RULE_NAME", "HEADER: ", score => $score);
  
          #Yet another magic call
          for my $set (0..3) {
@@ -89, +91 @@

  }
  }}}
  
- And thats it. The {{{ _handle_hit($rule, $score, $area, $description) }}} call will trigger a hit for the specified rule with the specified score. Area means for example BODY or HEADER, so this has to be changed according to what you are doing. Description is obvious, but in our example, we fetch the description from the configuration file, so you don't have to hardcode the description. Feel free to add additional dynamic data to the description, for example the ammount of hits or other useful informations.
+ And thats it. The {{{ got_hit ($rule, $area, %params) }}} call will trigger a hit for the specified rule with the specified score. Area means for example BODY or HEADER, so this has to be changed according to what you are doing. (See [http://spamassassin.apache.org/full/3.2.x/doc/Mail_SpamAssassin_PerMsgStatus.html Mail::SpamAssassin::PerMsgStatus] for other possible params.)
  
+ The rule description is accessible with {{{ $pms->{conf}->{descriptions}->{EXAMPLE_RULE_NAME} }}}. It is usually set by {{{ describe EXAMPLE_RULE_NAME }}} in the rules file but can also be changed at runtime.
+ 
- Setting {{{ $pms->{conf}->{scoreset}->[$set]->{"EXAMPLE_RULE_NAME"} }}} lets the dynamic score appear in the template tag _TESTSSCORES_, which might be used for the X-Spam-Status line. (The for loop is necessary to set all 4 values, for their explanation see [http://spamassassin.apache.org/full/3.1.x/doc/Mail_SpamAssassin_Conf.html Mail::SpamAssassin::Conf] item {{{score SYMBOLIC_TEST_NAME n.nn}}} )
+ Setting {{{ $pms->{conf}->{scoreset}->[$set]->{"EXAMPLE_RULE_NAME"} }}} lets the dynamic score appear in the template tag _TESTSSCORES_, which might be used for the X-Spam-Status line. (The for loop is necessary to set all 4 values, for their explanation see [http://spamassassin.apache.org/full/3.2.x/doc/Mail_SpamAssassin_Conf.html Mail::SpamAssassin::Conf] item {{{score SYMBOLIC_TEST_NAME n.nn}}} )
  
  The {{{ return 0; }}} is important because that will make sure that the actual rule that we defined earlier with the {{{ eval:check_example() }}} never evaluates to true so it doesn't score. It doesn't need to score because the actual scoring is completely being done inside the subroutine. So even if you defined a score in the configuration file earlier, it would never be used.