# Gnome ReadNews Perl Hooks

Several hooks can be called sequentally in order they were `GRN::add_hook()`'ed. You simply have to return 0 in all the hooks in the chain, except the last one.

Note, that field keys are case-sensitive. For example, `$MSG{from}` will return a `NULL`, while `$MSG{From}` will return the author of the message.

You can find some hook examples in samples/hooks/Perl directory.

Here is the list of described hooks:
- GetScore
- PreShow
- PreShowHeader
- PreShowPart
- PreShowFooter
- PrePost
- PreSend
- TemplateNew
- TemplateMNew
- TemplateReply
- TemplateMReply
- TemplateForward
- TemplateMForward

## GetScore

Returns article's score, based on standard NNTP headers.

Accepts: `%MSG` in global scope, the following fields are passed:

Group | Newsgroup, where the article is in
Number | Article's number in the NNTP-server's spool
Lines | Number of lines in the article
Size | Size of the article, in bytes
ParsedDate | Parsed date, in seconds since 1 Jan 1970 00:00:00
Subject
From
Date
Message-ID
References
Xref | in the format: ("%s %s:%d", nntp_server, Group, Number)
Path

Returns:

0 | Nothing changed, next handler will be called if any
1 | The message is marked by the blue ball
2 | green ball
3 | cyan ball
4 | red ball
5 | magenta ball
6 | brown ball
7 | grey ball
8 | undefined
9 | light blue ball
10 | light green ball
11 | light cyan ball
12 | light red ball
13 | light magenta ball
14 | yellow ball
15 | white ball
16 | undefined
17-98 | reserved
99 | Article not listed
100-65535 | Article's score

## PreShow

Converts message to HTML format. Can be used to colorify messages while viewing, or to process message in any other way before showing.

Accepts: `%MSG` in global scope, the following fields are passed:

Group | Newsgroup, where the article is in
Number | Article's number in the NNTP-server's spool
Lines | Number of lines in the article
Size | Size of the article, in bytes
ParsedDate | Parsed date, in seconds since 1 Jan 1970 00:00:00
Subject
From
Date
Message-ID
References
Xref | in the format: ("%s %s:%d", nntp_server, Group, Number)
Path
body | Message body
nChildren | Number of underlying messages in the tree, where the current message is the root
tagged

Also all additional headers (like `X-Comment-To`). use "Message headers" window to view all of them.

Returns:

<= 0 | on fail
> 0 | on success

Output: On successfull return, Grn assumes that `$MSG{body}` contains HTMLized message (see example in `samples/hooks/Perl/PreShow.pl`). All chars have to be escaped by the `GRN::html_escape()` function. You can also change all the message headers.

## PrePost

Does the last-minute changes in the message, right before the posting.

Accepts: `%MSG` in global scope, all fields are described here.

Returns:

<= 0 | on fail
> 0 | on success

## PreSend

Does the same thing as PrePost but impacts only the message sent via SMTP.

Accepts: `%MSG` in global scope, all fields are described here.

Returns:

<= 0 | on fail
> 0 | on success

## TemplateNew

Generates template for new article.

Accepts: `%MSG` in global scope, all fields are described here. Some fields may be empty.

Returns:

<= 0 | on fail
> 0 | on success

Output:

`$MSG{pos}` | Current cursor position
`$MSG{body}` | Text to be inserted into the editor

You may also change or add any field in `%MSG`.

## TemplateMNew

Generates template for new message to be sent via SMTP.

Accepts: See TemplateNew.

Returns: See TemplateNew.

Output: See TemplateNew.

## TemplateReply

Generates template for newsgroup follow-up.

Accepts: `%MSG` and `%MSG1` in global scope, all fields are described here. Some fields may be empty. `%MSG1` is the original message you're replying to.

Returns: See TemplateNew.

Output: See TemplateNew.

## TemplateMReply

Generates template for replying via mail.

Accepts: See TemplateReply.

Returns: See TemplateNew.

Output: See TemplateNew.

## TemplateForward

Generates template for forwarding.

Accepts: See TemplateReply.

Returns: See TemplateNew.

Output: See TemplateNew.

## TemplateMForward

Generates template for forwarding via mail.

Accepts: See TemplateReply.

Returns: See TemplateNew.

Output: See TemplateNew.