https://github.com/rsrchboy/html-builder
A declarative approach to HTML generation
https://github.com/rsrchboy/html-builder
Last synced: 3 months ago
JSON representation
A declarative approach to HTML generation
- Host: GitHub
- URL: https://github.com/rsrchboy/html-builder
- Owner: rsrchboy
- License: other
- Created: 2012-02-14T19:17:04.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2015-05-05T16:39:25.000Z (about 10 years ago)
- Last Synced: 2025-01-16T04:21:13.554Z (5 months ago)
- Language: Perl
- Homepage: http://metacpan.org/release/HTML-Builder/
- Size: 136 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.mkdn
- Changelog: Changes
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/RsrchBoy/html-builder)
[](http://cpants.charsbar.org/dist/overview/HTML-Builder)
# NAME
HTML::Builder - A declarative approach to HTML generation
# VERSION
This document describes version 0.009 of HTML::Builder - released April 21, 2015 as part of HTML-Builder.
# SYNOPSIS
use HTML::Builder ':minimal';
# $html is:
Something, huh?
my $html = div { id gets 'main'; p { 'Something, huh?' } };
# DESCRIPTION
A quick and dirty set of helper functions to make generating small bits of
HTML a little less tedious.
# FUNCTIONS
## our\_tags
A unique, sorted list of the HTML tags we know about (and handle).
## tag($tag\_name, $code\_ref)
The actual function responsible for handling the tagging. All of the helper
functions pass off to tag() (e.g. `div()` is `sub div(&) { unshift 'div';
goto \&tag }`).
## html5\_tags()
The list of tags we think are HTML5.
## html\_tags()
The list of tags we think are HTML ( < HTML5, that is).
## deprecated\_tags()
HTML elements considered to be deprecated.
## our\_tags()
The unique, sorted list of all tags returned by html5\_tags() and html\_tags().
## html5\_minimal\_tags()
A minimal subset of HTML5 tags as returned by html5\_tags():
article aside footer header nav
## conflicting\_tags
Returns a HashRef of tags that conflict with Perl builtins: our named exports
for the tags are the keys; the tags themselves are the values.
## form\_tags
A list of tags related to forms, that will belong to the `:form` group.
## table\_tags
A list of tags related to tables, that will belong to the `:table` group.
## minimal\_tags
A list of tags we consider a "minimal" set. These will belong to the
`:minimal` group.
## our\_tags
The set of all the tags we know of.
## attr(&)
An alternative to using `gets` (or instances where it won't work, e.g. `for
gets 'name'`). Takes a coderef, expects that coderef to return a list of
attribute => value pairs, e.g.
div {
attr {
id => 'one',
bip => 'two',
};
};
# USAGE
Each supported HTML tag takes a coderef, executes it, and returns the output
the coderef writes to STDOUT with the return value appended.
That is:
div { say h1 { 'Hi there! }; p { "Nice day, isn't it?" } }
Generates:
Hi there!
Nice day, isn't it?
Element attributes are handled by specifying them with `gets`. e.g.:
div { id gets 'main'; 'Hi!' }
Generates:
Hi!
[gets](https://metacpan.org/pod/gets) may be specified multiple times, for multiple attributes.
## Nested Tags
When one tag function is called from within another, the nested tag will print
its output to STDOUT rather than returning it. That means that this:
div { print h1 { 'Hi there! }; p { "Nice day, isn't it?" } }
...and this:
div { h1 { 'Hi there! }; p { "Nice day, isn't it?" } }
Behave identically, from the perspective of the caller.
# RENAMING EXPORTED FUNCTIONS
This package uses [Sub::Exporter](https://metacpan.org/pod/Sub::Exporter), so you can take advantage of the features
that package provides. For example, if you wanted to import the tags in the
'minimal' group, but wanted to prefix each function with 'html\_', you could
do:
use HTML::Builder -minimal => { -prefix => 'html_' };
# EXPORTED FUNCTIONS
Each tag we handle is capable of being exported, and called with a coderef.
This coderef is executed, and the return is wrapped in the tag. Attributes on
the tag can be set from within the coderef by using [gets](https://metacpan.org/pod/gets), a la `id gets
'foo'`.
By default we export the `:minimal` group.
## Export Groups
### :all
Everything not conflicting with Perl builtins.
This isn't an optimal group to use as-is -- it will cause a ton of functions
to be imported, including some that will conflict with several Perl builtins.
If you use this group, you are highly encouraged to supply a prefix for it,
like:
use HTML::Builder -all => { -prefix => 'html_' };
### :minimal
A basic set of the most commonly used tags:
h1..h4 div p img span script br ul ol li style a
### :html5
HTML5 tags (`article`, `header`, `nav`, etc) -- or at least what Wikipedia
thinks are HTML5 tags.
### :table
The table tags:
table thead tbody tfoot tr th td
As `tr` would conflict with a Perl builtin, it is recommended that this group
be imported with a prefix ('table\_' would seem to suggest itself).
### :header
Header tags:
header hgroup
### :form
Form tags:
form fieldset button input label optgroup option select textarea
# ACKNOWLEDGMENTS
This package was inspired by [Template::Declare::Tags](https://metacpan.org/pod/Template::Declare::Tags)... In particular, our
`gets::AUTOLOAD` is pretty much a straight-up copy of Template::Declare::Tags'
`is::AUTOLOAD`, with some modifications. We also pass off to [HTML::Tiny](https://metacpan.org/pod/HTML::Tiny),
and allow it to do the work of actually generating the output. Thanks! :)
# SEE ALSO
Please see those modules/websites for more information related to this module.
- [HTML::Tiny](https://metacpan.org/pod/HTML::Tiny)
- [Template::Declare::Tags](https://metacpan.org/pod/Template::Declare::Tags)
- [HTML::HTML5::Builder](https://metacpan.org/pod/HTML::HTML5::Builder)
# SOURCE
The development version is on github at [http://https://github.com/RsrchBoy/html-builder](http://https://github.com/RsrchBoy/html-builder)
and may be cloned from [git://https://github.com/RsrchBoy/html-builder.git](git://https://github.com/RsrchBoy/html-builder.git)
# BUGS
Please report any bugs or feature requests on the bugtracker website
https://github.com/RsrchBoy/html-builder/issues
When submitting a bug or request, please include a test-file or a
patch to an existing test-file that illustrates the bug or desired
feature.
# AUTHOR
Chris Weyl
## I'm a material boy in a material world
Please note **I do not expect to be gittip'ed or flattr'ed for this work**,
rather **it is simply a very pleasant surprise**. I largely create and release
works like this because I need them or I find it enjoyable; however, don't let
that stop you if you feel like it ;)
[Flattr this](https://flattr.com/submit/auto?user_id=RsrchBoy&url=https%3A%2F%2Fgithub.com%2FRsrchBoy%2Fhtml-builder&title=RsrchBoy's%20CPAN%20HTML-Builder&tags=%22RsrchBoy's%20HTML-Builder%20in%20the%20CPAN%22),
[gittip me](https://www.gittip.com/RsrchBoy/), or indulge my
[Amazon Wishlist](http://bit.ly/rsrchboys-wishlist)... If you so desire.
# CONTRIBUTOR
Olaf Alders
# COPYRIGHT AND LICENSE
This software is Copyright (c) 2012 by Chris Weyl.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999