App::ZofCMS::Plugin::Syntax::Highlight::HTML - provide HTML code snippets on your site

In ZofCMS template:

    {
        body        => \'index.tmpl',
        highlight_html => {
            foohtml => '<div class="bar">beer</div>',
            bar     => sub { return '<div class="bar">beer</div>' },
            beer    => \ 'filename.of.the.file.with.HTML.in.datastore.dir',
        },
        plugins     => [ qw/Syntax::Highlight::HTML/ ],
    }

In HTML::Template template:

    <tmpl_var name="foohtml">
    <tmpl_var name="bar">
    <tmpl_var name="beer">

The module is a plugin for App::ZofCMS. It provides means to include HTML (HyperText Markup Lanugage) code snippets with syntax highlights on your pages.

This documentation assumes you've read App::ZofCMS, App::ZofCMS::Config and App::ZofCMS::Template

    {
        plugins => [ qw/Syntax::Highlight::HTML/ ],
    }

First and obvious is that you'd want to include the plugin in the list of plugins to run.

    {
        highlight_html => {
            foohtml => '<div class="bar">beer</div>',
            bar     => sub { return '<div class="bar">beer</div>' },
            beer    => \ 'filename.of.the.file.with.HTML.in.datastore.dir',
        },
    }

The highlight_html is the heart key of the plugin. It takes a hashref as a value. The keys of this hashref except for two special keys described below are the name of <tmpl_var name=""> tags in your HTML::Template template into which to stuff the syntax-highlighted code. The value of those keys can be either a scalar, subref or a scalarref. They are interpreted by the plugin as follows:

    highlight_html => {
        foohtml => '<div class="bar">beer</div>'
    }

When the value of the key is a scalar it will be interpreted as HTML code to be highlighted. This will do it for short snippets.

    highlight_html => {
        beer    => \ 'filename.of.the.file.with.HTML.in.datastore.dir',
    },

When the value is a scalarref it will be interpreted as the name of a file in the data_store dir. That file will be read and its contents will be understood as HTML code to be highlighted. If an error occured during opening of the file, your <tmpl_var name=""> tag allocated for this entry will be populated with an error message.

    highlight_html => {
        bar     => sub { return '<div class="bar">beer</div>' },
    },

When the value is a subref, it will be executed and its return value will be taken as HTML code to highlight. The @_ of that sub when called will contain the following: $template, $query, $config where $template is a hashref of your ZofCMS template, $query is a hashref of the parameter query whether it's a POST or a GET request, and $config is the App::ZofCMS::Config object.

    highlight_html => {
        nnn => 1,
        pre => 0,
    },

There are two special keys, namely nnn and pre, in highlight_html hashref. Their values will affect the resulting highlighted HTML code.

    highlight_html => {
        nnn => 1,
    }

Instructs the highlighter to activate line numbering. Default value: 0 (disabled).

    highlight_html => {
        nnn => 0,
    }

Instructs the highlighter to surround result by <pre>...</pre> tags. Default value: 1 (enabled).

    {
        highlight_before => '<div class="highlights">',
    }

Takes a scalar as a value. When specified, every highlighted HTML code will be prefixed with whatever you specify here.

    {
        highlight_after => '</div>',
    }

Takes a scalar as a value. When specified, every highlighted HTML code will be postfixed with whatever you specify here.

Given '<foo class="bar">beer</foo>' as input plugin will generate the following code:

    <pre>
        <span class="h-ab">&lt;</span><span class="h-tag">foo</span>
        <span class="h-attr">class</span>=<span class="h-attv">"bar</span>"
        <span class="h-ab">&gt;</span>beer<span class="h-ab">&lt;/</span>
        <span class="h-tag">foo</span><span class="h-ab">&gt;</span>
    </pre>

Now you'd use CSS to highlight specific parts of HTML syntax. Here are the classes that you can define in your stylesheet (list shamelessly stolen from Syntax::Highlight::HTML documentation):

• .h-decl - for a markup declaration; in a HTML document, the only markup declaration is the DOCTYPE, like: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
• .h-pi - for a process instruction like <?html ...> or <?xml ...?>
• .h-com - for a comment, <!-- ... -->
• .h-ab - for the characters '<' and '>' as tag delimiters
• .h-tag - for the tag name of an element
• .h-attr - for the attribute name
• .h-attv - for the attribute value
• .h-ent - for any entities: é «
• .h-lno - for the line numbers

Sebastien Aperghis-Tramoni, the author of Syntax::Highlight::HTML, was kind enough to provide sample CSS code defining the look of each element of HTML syntax. It is presented below:

    .h-decl { color: #336699; font-style: italic; }   /* doctype declaration  */
    .h-pi   { color: #336699;                     }   /* process instruction  */
    .h-com  { color: #338833; font-style: italic; }   /* comment              */
    .h-ab   { color: #000000; font-weight: bold;  }   /* angles as tag delim. */
    .h-tag  { color: #993399; font-weight: bold;  }   /* tag name             */
    .h-attr { color: #000000; font-weight: bold;  }   /* attribute name       */
    .h-attv { color: #333399;                     }   /* attribute value      */
    .h-ent  { color: #cc3333;                     }   /* entity               */

    .h-lno  { color: #aaaaaa; background: #f7f7f7;}   /* line numbers         */

Despite the ZofCMS design this module uses Syntax::Highlight::HTML which in turn uses HTML::Parser which needs a C compiler to install.

This module requires Syntax::Highlight::HTML and File::Spec (the later is part of the core)

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

Please report any bugs or feature requests to bug-app-zofcms-plugin-syntax-highlight-html at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-ZofCMS-Plugin-Syntax-Highlight-HTML. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

    perldoc App::ZofCMS::Plugin::Syntax::Highlight::HTML

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=App-ZofCMS-Plugin-Syntax-Highlight-HTML

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/App-ZofCMS-Plugin-Syntax-Highlight-HTML

* CPAN Ratings

http://cpanratings.perl.org/d/App-ZofCMS-Plugin-Syntax-Highlight-HTML

* Search CPAN

http://search.cpan.org/dist/App-ZofCMS-Plugin-Syntax-Highlight-HTML

Copyright 2008 Zoffix Znet, all rights reserved.

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