# NAME
Tk::HyperText - An ROText widget which renders HTML code.
# SYNOPSIS
use Tk::HyperText;
my $html = $mw->Scrolled ('HyperText',
-scrollbars => 'ose',
-wrap => 'word',
)->pack (-fill => 'both', -expand => 1);
$html->setHandler (Title => \&onNewTitle);
$html->setHandler (Resource => \&onResource);
$html->setHandler (Submit => \&onFormSubmit);
$html->loadString (qq~
Hello world!
Hello, world!
~);
# DESCRIPTION
`Tk::HyperText` is a widget derived from `Tk::ROText` that renders HTML
code.
## PURPOSE
First of all, **Tk::HyperText is NOT expected to become a full-fledged web
browser widget**. This module's original idea was just to be a simple
HTML-rendering widget, specifically to match the capabilities of the
_AOL Instant Messenger_'s HTML widgets. That is, to render basic text
formatting, images, and hyperlinks. Anything this module does that's extra
is only there because I was up to the challenge.
## VERSION 0.06+
This module is **NOT** backwards compatible with versions 0.05 and below.
Specifically, the module was rewritten to use `HTML::TokeParser` as its
HTML parsing engine instead of parsing it as plain text. Also, the methods
have all been changed. The old module's overloading of the standard
`Tk::Text` methods was causing all kinds of problems, and since this isn't
really a "drop-in" replacement for the other Text widgets, its methods don't
need to follow the same format.
Also, support for Cascading StyleSheets doesn't work at this time. It may be
re-implemented at a later date, but, as this widget is not meant to become
a full-fledged web browser (see ["PURPOSE"](#purpose)), the CSS support might not
return.
## EXAMPLE
Run the \`demo.pl\` script included in the distribution.
# WIDGET-SPECIFIC OPTIONS
- \-continuous, -continue
Setting this option to 1 tells the widget **not** to re-render the entire
contents of the widget each time the contents are updated. The default value
is 0, so the entire page contents are rendered on any updates. This causes
the code to be "continuous", so that i.e. if you fail to close a bold tag and
then insert more code, the new code should carry on the unclosed tag and
appear in bold. Setting this option to 1 would render the new code
independently from the existing page and is therefore unnatural in HTML.
`-continue` is an alias for `-continuous` if you're terrible at spelling.
- \-allow, -deny
Define tags that are allowed or denied. See ["WIDGET METHODS"](#widget-methods) for more
details.
- \-attributes
Since Tk::HyperText doesn't yet support Cascading Style Sheets, the only
alternative is to send in `-attributes`. This data structure defines some
default styles for use within the rendered pages.
my $html = $mw->Scrolled('HyperText',
-attributes => {
-anchor => { # Hyperlink colors
-normal => '#0000FF', # or 'blue'
-hover => '#FF0000', # or 'red'
-active => '#FF0000', # or 'red'
-visited => '#990099', # or 'purple'
},
-font => {
-family => 'Times',
-mono => 'Courier',
-size => 'medium', # or any HTML size
# (1..6, xx-small..xx-large)
# Text styles, set them to 1 to apply the effect.
# I don't see why anyone would want to use these,
# but they're here anyway.
-bold => 0, # Bold
-italic => 0, # Italic
-under => 0, # Underline
-over => 0, # Overstrike
},
-style => {
-margins => 0, # Text margins
-color => '#000000', # Text color
-back => '#FFFFFF', # Text BG color
},
},
);
# WIDGET METHODS
- _$text_\->__setHandler__ _(name => event)_
Define a handler for certain events that happen within the widget. See
["EVENTS"](#events) for more information.
$html->setHandler (Title => sub {
my ($self,$newTitle) = @_;
$mw->configure (-title => $newTitle);
});
- _$text_\->__allowedTags__ _(tags)_
Specify a set of tags that are allowed to be rendered. Pass in the tag names
as an array. If the "allow list" has any entries, **only** these tags will be
rendered.
- _$text_\->__deniedTags__ _(tags)_
Specify a set of tags that are **not** allowed to be rendered. If the "allow
list" is empty and the "denied list" has any entries, then all tags are
allowed **except** for those in the denied list. If any entries in the denied
list conflict with entries in the allowed list, those tags are **not**
allowed.
- _$text_\->__allowHypertext__ _()_
This is a preset allow/deny scheme. It allows all hypertext tags (basic
text formatting, images, and horizontal rules) but doesn't allow tables,
forms, lists, or other complicated tags. This will make it match the
capabilities of _AOL Instant Messenger_'s HTML rendering widgets.
It will allow the following tags:
, , , <body>, <a>, <p>, <br>, <hr>,
<img>, <font>, <center>, <sup>, <sub>, <b>, <i>,
<u>, <s>
All other tags are denied.
- _$text_\->__allowEverything__ _()_
Allows all supported tags to be rendered. It resets the "allow" and
"deny" lists to be blank.
- _$text_\->__loadString__ _(html\_code)_
Render a string of HTML code into the text widget. This will replace all of
the current contents of the widget with the new HTML code.
- _$text_\->__loadBlank__ _()_
Blanks out the contents of the widget (similar to the "`about:blank`" URI
in most modern web browsers).
- _$text_\->__clearHistory__ _()_
Resets the browsing history (so "visited links" will become "normal links"
again).
- _$text_\->__getText__ _(\[as\_html\])_
Returns the contents of the widget as a string. Send a true value as an
argument to get the contents back including HTML code. Otherwise, only the
plain text content is returned.
# EVENTS
All events receive a reference to its parent widget as `$_[0]`.
The following are the event handlers currently supported by
`Tk::HyperText`:
- Title ($self, $newTitle)
This event is called every time a `<title>...` sequence is found
in the HTML code. `$newTitle` is the text of the new page title.
- Resource ($self, %info)
This event is called whenever an external resource is requested (such as an
image or a hyperlink trying to link to another page). `%info` contains all
the information about the requested resource.
# For hyperlinks ( tags)
%info = (
tag => 'a', # The HTML tag.
href => 'http://google.com', # The attribute.
src => 'http://google.com', # src is an alias for href
target => '_blank', # The attribute
);
# For images (![]()
tags)
%info = (
tag => 'img', # The HTML tag.
src => 'avatar.jpg', # The ![]()
attribute.
width => 48, # The ![]()
attribute.
height => 48, # The ![]()
attribute.
vspace => '', # ![]()
hspace => '', # ![]()
align => '', # ![]()
alt => 'alt text', # ![]()
);
**Note about Images:** The `Resource` event, when called for an image, wants
you to return the image's data, Base64-encoded. Otherwise, the image on the
page will show up as a "broken image" icon. Here is an example of how to
handle image resources:
use LWP::Simple;
use MIME::Base64 qw(encode_base64);
$html->setHandler (Resource => sub {
my ($self,%info) = @_;
if ($info{tag} eq 'img') {
# If an http:// link, get the image from the web.
if ($info{src} =~ /^http/i) {
my $bin = get $info{src};
my $enc = encode_base64($bin);
return $enc;
}
# Otherwise, read it from a local file.
else {
if (-f $src) {
open (READ, $src);
binmode READ;
my @bin = ;
close (READ);
chomp @bin;
my $enc = encode_base64(join("\n",@bin));
return enc;
}
}
}
return undef;
});
On hyperlink resources, the module doesn't need or expect any return value.
It should be up to the handler to do what it needs (i.e. fetch the source
of the page, blank out the HTML widget and then `loadString` the new code
into it).
- Submit ($self,%info)
This event is called when an HTML form has been submitted. `%info` is a
hash containing the information about the event.
%info = (
form => 'login', # The