package SVN::Notify::HTML; use strict; use HTML::Entities; use SVN::Notify (); $SVN::Notify::HTML::VERSION = '2.83'; @SVN::Notify::HTML::ISA = qw(SVN::Notify); __PACKAGE__->register_attributes( linkize => 'linkize', css_url => 'css-url=s', wrap_log => 'wrap-log', ); =head1 Name SVN::Notify::HTML - Subversion activity HTML notification =head1 Synopsis Use F in F: svnnotify --repos-path "$1" --revision "$2" \ --to developers@example.com --handler HTML [options] Use the class in a custom script: use SVN::Notify::HTML; my $notifier = SVN::Notify::HTML->new(%params); $notifier->prepare; $notifier->execute; =head1 Description This subclass of L sends HTML formatted email messages for Subversion activity, rather than the default plain text. =head1 Prerequisites In addition to the modules required by SVN::Notify, this class requires: =over =item HTML::Entities =back =head1 Usage To use SVN::Notify::HTML, simply follow the L in SVN::Notify, but when using F, specify C<--handler HTML>. =cut ############################################################################## =head1 Class Interface =head2 Constructor =head3 new my $notifier = SVN::Notify::HTML->new(%params); Constructs and returns a new SVN::Notify object. All parameters supported by SVN::Notity are supported here, but SVN::Notify::HTML supports a few additional parameters: =over =item linkize svnnotify --linkize A boolean attribute to specify whether or not to "linkize" the SVN log message--that is, to turn any URLs or email addresses in the log message into links. =item css_url svnnotify --css-url http://example.com/svnnotify.css URL for a CSS file that will can style the HTML output by SVN::Notify::HTML or its subclasses. Note that the URL will be added to the output via a C<< >> tag I the CSS generated by SVN::Notify::HTML or its subclasses. What that means is that the CSS file specified by C need not completely style the HTML, but simply override the default settings. This approach nicely takes advantage of the "cascading" abilities of CSS. =item ticket_map svnnotify --ticket-map '(BUG-(\d+))=http://bugs.example.com/?show=%s' This attribute is inherited from L, but its semantics are slightly different: the regular expression passed as the regular expression used for the key should return I matches instead of one: the text to link and the ticket ID itself. For example, '(BUG-(\d+))' will match "BUG-1234567", and "BUG-1234567" will be used for the link text, while "1234567" will be used to fill in the C format string. The first set of parentheses capture the whole string, while the parentheses around C<\d+> match the number only. Also note that it is wise to use "\b" on either side of the regular expression to insure that you don't get spurious matches. So a better version would be '\b(BUG-(\d+))\b'. As a fallback, if your regular expression returns only a single match string, it will be used both for the link text and for the the ticket URL generated from C. For example, '\bBUG-(\d+)\b' would make a link only of the number in 'BUG-1234567', as only the number has been captured by the regular expression. But two matches are of course recommended (and likely to work better, as well). You can use more complicated regular expressions if commit messages are likely to format ticket numbers in various ways. For example, this regular expression: \b\[?\s*(Ticket\s*#\s*(\d+))\s*\]?\b' Will match: String Matched Link Text Ticket Number --------------------|--------------------|--------------- [Ticket#1234] [Ticket#1234] 1234 [ Ticket # 1234 ] [ Ticket # 1234 ] 1234 Ticket #1234 Ticket #1234 1234 Ticket # 1234 Ticket #1234 1234 In any of these cases, you can see that the match is successful, properly creates the link text (simply using the text as typed in by the committer, and correctly extracts the ticket number for use in the URL. To learn more about the power of Regular expressions, I highly recommend _Mastering Regular Expressions, Second Edition_, by Jeffrey Friedl. =item wrap_log svnnotify --wrap-log A boolean attribute to specify whether or not to wrap the log message in the output HTML. By default, log messages are I wrapped, on the assumption that they should appear exactly as typed. But if that's not the case, specify this option to wrap the log message. =back =cut ############################################################################## =head2 Class Methods =head3 content_type Returns the content type of the notification message, "text/html". Used to set the Content-Type header for the message. =cut sub content_type { 'text/html' } ############################################################################## =head1 Instance Interface =head2 Instance Methods =head3 start_html $notifier->start_html($file_handle); This method starts the HTML of the notification message. It outputs the opening C<< >>, C<< >>, and C<< >> tags. Note that if the C attribute is set to a value, it will be specified in the C<< >> tag. All of the HTML will be passed to any "start_html" output filters. See L for details on filters. =cut sub start_html { my ($self, $out) = @_; my $lang = $self->language; my $char = lc $self->encoding; my @html = ( qq{\n}, qq{\n\n}, ( $self->{css_url} ? ( '\n} ) : () ), '', encode_entities($self->subject, '<>&"'), qq{\n\n\n\n} ); print $out @{ $self->run_filters( start_html => \@html ) }; return $self; } ############################################################################## =head3 start_body This method starts the body of the HTML notification message. It first calls C, and then outputs the C<< \n}; my @html = ( qq{
\n} ); if (my $header = $self->header) { push @html, ( '\n", ); } print $out @{ $self->run_filters( start_body => \@html ) }; return $self; } ############################################################################## =head3 output_css $notifier->output_css($file_handle); This method starts outputs the CSS for the HTML message. It is called by C, and which wraps the output of C in the appropriate C<<