Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SVN::Notify::HTML(3)  User Contributed Perl Documentation SVN::Notify::HTML(3)

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@justatheory.com>

Copyright and License
       Copyright (c) 2004-2016 David E.	Wheeler. Some Rights Reserved.

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

perl v5.24.1			  2017-07-02		  SVN::Notify::HTML(3)

Name | Synopsis | Description | Prerequisites | Usage | Class Interface | Instance Interface | See Also | Author | Copyright and License

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=SVN::Notify::HTML&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help