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
{ 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
{ 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:
<tmpl_var name="">
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.
data_store
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.
@_
$template, $query, $config
$template
$query
$config
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.
nnn
pre
highlight_html => { nnn => 1, }
Instructs the highlighter to activate line numbering. Default value: 0 (disabled).
0
highlight_html => { nnn => 0, }
Instructs the highlighter to surround result by <pre>...</pre> tags. Default value: 1 (enabled).
1
highlight_before
{ 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
{ 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:
'<foo class="bar">beer</foo>'
<pre> <span class="h-ab"><</span><span class="h-tag">foo</span> <span class="h-attr">class</span>=<span class="h-attv">"bar</span>" <span class="h-ab">></span>beer<span class="h-ab"></</span> <span class="h-tag">foo</span><span class="h-ab">></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-decl
DOCTYPE
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
.h-pi - for a process instruction like <?html ...> or <?xml ...?>
.h-pi
<?html ...>
<?xml ...?>
.h-com - for a comment, <!-- ... -->
.h-com
<!-- ... -->
.h-ab - for the characters '<' and '>' as tag delimiters
.h-ab
'<'
'>'
.h-tag - for the tag name of an element
.h-tag
.h-attr - for the attribute name
.h-attr
.h-attv - for the attribute value
.h-attv
.h-ent - for any entities: é «
.h-ent
é
«
.h-lno - for the line numbers
.h-lno
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)
Fork this module on GitHub: https://github.com/zoffixznet/App-ZofCMS
To report bugs or request features, please use https://github.com/zoffixznet/App-ZofCMS/issues
If you can't access GitHub, you can email your request to bug-App-ZofCMS at rt.cpan.org
bug-App-ZofCMS at rt.cpan.org
Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)
You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.
LICENSE
To install App::ZofCMS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::ZofCMS
CPAN shell
perl -MCPAN -e shell install App::ZofCMS
For more information on module installation, please visit the detailed CPAN module installation guide.