Provided by: libsvn-notify-perl_2.81-1_all bug

Name

       SVN::Notify::HTML - Subversion activity HTML notification

Synopsis

       Use svnnotify in post-commit:

         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;

Description

       This subclass of SVN::Notify sends HTML formatted email messages for Subversion activity,
       rather than the default plain text.

Prerequisites

       In addition to the modules required by SVN::Notify, this class requires:

       HTML::Entities

Usage

       To use SVN::Notify::HTML, simply follow the instructions in SVN::Notify, but when using
       svnnotify, specify "--handler HTML".

Class Interface

   Constructor
       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:

       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.

       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 "<link
           rel="stylesheet">" tag after the CSS generated by SVN::Notify::HTML or its subclasses.
           What that means is that the CSS file specified by "css_url" need not completely style
           the HTML, but simply override the default settings. This approach nicely takes
           advantage of the "cascading" abilities of CSS.

       ticket_map
             svnnotify --ticket-map '(BUG-(\d+))=http://bugs.example.com/?show=%s'

           This attribute is inherited from SVN::Notify, but its semantics are slightly
           different: the regular expression passed as the regular expression used for the key
           should return two 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 "ticket_url" format
           string. The first set of parentheses capture the whole string, while the parentheses
           around "\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 "ticket_url".
           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.

       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 not 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.

   Class Methods
       content_type

       Returns the content type of the notification message, "text/html". Used to set the
       Content-Type header for the message.

Instance Interface

   Instance Methods
       start_html

         $notifier->start_html($file_handle);

       This method starts the HTML of the notification message. It outputs the opening "<html>",
       "<head>", and "<body>" tags. Note that if the "language" attribute is set to a value, it
       will be specified in the
        "<html>" tag.

       All of the HTML will be passed to any "start_html" output filters. See Writing Output
       Filters for details on filters.

       start_body

       This method starts the body of the HTML notification message. It first calls
       "start_html()", and then outputs the "<style>" tag, calling "output_css()" between them.
       It then outputs an opening "<div>" tag.

       If the "header" attribute is set, "start_body()" outputs it between "<div>" tags with the
       ID "header". Furthermore, if the header happens to start with the character "<",
       "start_body()" assumes that it contains valid HTML and therefore will not escape it.

       If a "start_body" output filter has been specified, it will be passed the lines with the
       "<div>" tag and the header. To filter the CSS, use a "css" filter, and to filter the
       declaration of the HTML document and its "<head>" section, use a "start_html" filter. See
       Writing Output Filters for details on filters.

       output_css

         $notifier->output_css($file_handle);

       This method starts outputs the CSS for the HTML message. It is called by "start_body()",
       and which wraps the output of "output_css()" in the appropriate "<style>" tags.

       An output filter named "css" may be added to modify the output of CSS. The filter
       subroutine name should be "css" and expect an array reference of lines of CSS. See Writing
       Output Filters for details on filters.

       output_metadata

         $notifier->output_metadata($file_handle);

       This method outputs a definition list containing the meta data of the commit, including
       the revision number, author (user), and date of the revision. If the "revision_url"
       attribute has been set, then the appropriate URL for the revision will be used to turn the
       revision number into a link.

       If there are any "log_message" filters, this method will do no HTML formatting, but
       redispatch to SVN::Notify::output_metadata. See Writing Output Filters for details on
       filters.

       output_log_message

         $notifier->output_log_message($file_handle);

       Outputs the commit log message in "<pre>" tags, and the label "Log Message" in "<h3>"
       tags. If the "bugzilla_url" attribute is set, then any strings like "Bug 2" or "bug # 567"
       will be turned into links.

       If there are any "log_message" filters, the filters will be assumed to escape the HTML,
       create inline links, and link ticket URLs. Otherwise, this method will do those things.
       See Writing Output Filters for details on filters.

       output_file_lists

         $notifier->output_log_message($file_handle);

       Outputs the lists of modified, added, deleted, files, as well as the list of files for
       which properties were changed as unordered lists. The labels used for each group are
       pulled in from the "file_label_map()" class method and output in "<h3>" tags.

       If there are any "file_lists" filters, this method will do no HTML formatting, but
       redispatch to SVN::Notify::output_file_lists. See Writing Output Filters for details on
       filters.

       end_body

         $notifier->end_body($file_handle);

       Closes out the body of the email by outputting the closing "</body>" and "</html>" tags.
       Designed to be called when the body of the message is complete, and before any call to
       "output_attached_diff()".

       If the "footer" attribute is set, "end_body()" outputs it between "<div>" tags with the ID
       "footer". Furthermore, if the footer happens to end with the character "<", "end_body()"
       assumes that it contains valid HTML and therefore will not escape it.

       All of the HTML will be passed to any "end_body" output filters. See Writing Output
       Filters for details on filters.

       output_diff

         $notifier->output_diff($out_file_handle, $diff_file_handle);

       Sends the output of "svnlook diff" to the specified file handle for inclusion in the
       notification message. The diff is output between "<pre>" tags, and Each line of the diff
       file is escaped by "HTML::Entities::encode_entities()".  The diff data will be read from
       $diff_file_handle and printed to $out_file_handle.

       If there are any "diff" filters, this method will do no HTML formatting, but redispatch to
       SVN::Notify::output_diff. See Writing Output Filters for details on filters.

   Accessors
       In addition to those supported by SVN::Notify, SVN::Notify::HTML supports the following
       accessors:

       linkize

         my $linkize = $notifier->linkize;
         $notifier = $notifier->linkize($linkize);

       Gets or sets the value of the "linkize" attribute.

       css_url

         my $css_url = $notifier->css_url;
         $notifier = $notifier->css_url($css_url);

       Gets or sets the value of the "css_url" attribute.

See Also

       SVN::Notify

Author

       David E. Wheeler <david@kineticode.com>

Copyright and License

       Copyright (c) 2004-2009 Kineticode, Inc. Some Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.