view release on metacpan or  search on metacpan

lib/HTML/BBReverse.pm  view on Meta::CPAN

  # convert generated HTML back to BBCode
  my $bbcode = $bbr->reverse($html);

=head1 DESCRIPTION

C<HTML::BBReverse> is a pure perl module for converting BBCode to HTML and is
able to convert the generated HTML back to BBCode.

And why would you want to reverse the generated HTML? Well, when you have a
nice dynamic website where you and/or visitors can post messages, and in
those messages BBCode is used for markup. In normal cases, your website has
a lot more pageviews than edits, and saving all those messages as HTML will
be a lot faster than saving them as the original BBCode and parsing them to
HTML for every visit.

So now all BBCode gets converted to HTML before it will be saved, but what
if you want to edit a message? Just reverse the generated HTML back to
BBCode, edit your message, and save it as HTML again.

=head2 METHODS

The following methods can be used

=head3 new

  my $bbr = HTML::BBReverse->new(
    allowed_tags => [
      qw( b i u code url size color img quote list email html )
    ],
    reverse_for_edit => 1,
    in_paragraph => 0,
    no_jslink => 1,
  );

C<new> creates a new HTML::BBReverse object using the configuration passed to
it. 

=head4 options

The following options can be passed to C<new>:

=over 4

=item allowed_tags

Specifies which BBCode tags will be parsed, for the current supported tags, see
L<the list of supported tags|/"SUPPORTED TAGS"> below. Defaults to all
supported tags.

=item reverse_for_edit

When set to a positive value, the C<reverse> method will parse C<&>, C<E<gt>> and
C<E<lt>> to their HTML entity equivalent. This option is useful when reversing
HTML to BBCode for editing in a browser, in a normal C<textarea>. When set to
zero, the C<reverse> method should just ignore these characters. Defaults to 1.

=item in_paragraph

Specifies wether the generated HTML is used between HTML paragraphs (C<E<lt>pE<gt>>
and C<E<lt>/pE<gt>>), and adds a C<E<lt>/pE<gt>> in front of and a C<E<lt>pE<gt>>
after every list. (XHTML 1.0 strict document types do not allow lists in
paragraphs) Defaults to 0.

=item no_jslink

When true, URLs starting with C<javascript:> will be disabled for the C<[url]>
and C<[img]> tags. Enabled by default.

=back

=head3 parse

Parses BBCode text supplied as a single scalar string and returns the HTML as a
single scalar string. See L<Supported tags|/"SUPPORTED TAGS"> below for the
supported tags and their usage.

=head3 reverse

Parses HTML generated from C<parse> supplied as a single scalar string and
returns BBCode as a single scalar string.
B<Note that this method can only be used to reverse HTML generated by the
C<parse> method of this module, it won't be able to parse just any HTML to
BBCode>

=head2 SUPPORTED TAGS

The following BBCode tags are supported:

=over 4

=item b, i, u

Standard markup tags, any text between C<[b]> and C<[/b]> will be B<bold>,
text between C<[i]> and C<[/i]> will be italic and text between C<[u]> and
C<[/u]> will be underlined. For example:

  [i]italic[/i]
  [b]bold[/b]
  [u]underlined[/u]

Will be C<parse>d to:

  <i>italic</i>
  <b>bold</b>
  <span style="text-decoration: underline">underlined</span>

Note that the HTML C<E<lt>uE<gt>> and C<E<lt>/uE<gt>> tags are not used for
underlining, this is because they are deprecated and not allowed in XHTML
1.0 Strict.

=item img

Adds an image, can be used in two ways, one for an image without description
and one for an image with description. For example:

  [img]/path/to/image.jpg[/img]
  [img=image.jpg]description[/img]

Will be C<parse>d to:

  <img src="/path/to/image.jpg" alt="" />