NAME
Text::Multi::Block - Text::Multi BlockType superclass
SYNOPSIS
package Text::Multi::Block::Foo;
use strict;
use warnings;
use base qw( Text::Multi::Block );
use Text::Foo;
sub as_html { Text::Foo::transform( shift->content ) }DESCRIPTION
This module serves as a base class for Text::Multi block classes. Text::Multi formats text using a variety of formatters (as explained in it's documentation) and each of these formatters is implemented as a subclass of Text::Multi::Block. In most cases these subclasses are simple wrappers around other, more complicated, text formatting modules.
PARAMETERS
These are parameters that can be set in the Text::Multi tag in your text document, to provide additional information to formatter modules, and potentially to influence how the content is rendered.
section
This is a superclass paramter, that can be passed to any block type in the start tag. This is a superclass parameter so that sections can be defined for any type of block, and used to identify different sections for the application. For example, a blog application might use code like this to indicate which block contains summary information.
{{{ Markdown section=summary }}}
This is the summary block to be displayed on the main page
{{{ Markdown }}}
This block contains text that will only be seen after you click the
'Read More...' link on the main page.trim( $value );
If set to a true value, any blank lines at the beginning or end of the block will be removed prior to formatting. This allows the source file to contain extra whitespace for readability without having it affect the output. With this set to true (which is the default) these two source documents are rendered identically.
{{{ Markdown }}}
Some Test here
{{{ }}}
{{{ Markdown }}}
Some Test here
{{{ }}}METHODS
as_html
The as_html method is the only method that a Text::Multi::Block subclass is required to implement. This method should take the content of the block and return it rendered as HTML. This method returns an empty string if not overridden in the subclass.
type
This is a read-only method, which returns the block type. It is mainly useful in conjunction with "find_blocks" in Text::Multi, for searching for blocks of a specific type.
content
Returns the original, unprocessed contents of the block.
INTERNAL METHODS
These are methods you would not normally call on your own, as Text::Multi will take care of calling them during it's normal processing. You do need to know about these if you are writing subclasses of Text::Multi::Block, however.
new
Creates a new object.
detail_comment
Returns the comment that will be inserted at the beginning of the blocks output when the 'detailed' option is set (see "detailed" in Text::Multi).
wrap_content( $content );
Used by "render", this method Returns the text passed in wrapped in a suitable HTML wrapper (see "wrap_element" and "wrap_classes" for how to affect the rendering of the wrapper.)
The default is to wrap the content in a <div> with the class attribute set to the results of the "wrap_classes" method.
wrap_classes();
Returns the CSS classes that should be applied to the "wrap_element" when "wrap_content" is called. By default this returns 'text-multi' and 'text-multi-<blocktype>', although you may wish to override it to add additional classes. See Text::Multi::Block::Code for an example of a class that overrides it.
block_file( $filename );
This method returns the path (as a Path::Class::File object) to a file associated with this module. The file distribution is fairly simplistic, supporting files are simply installed into @INC alongside the modules they support. If $filename begins with a dot, it is assumed to be an extension, and the file with that extension that is found alongside the class will be returned. If $filename does not begin with a dot, then it is assumed it will be found in a subdirectory named after the block class.
For example, for the Text::Multi::Block::Code, if Code.pm is installed in $PERL/Text/Multi/Block/Code.pm, then block_file( '.css' ) would return $PERL/Text/Multi/Block/Code.css and block_file( 'support.txt' ) would return $PERL/Text/Multi/Block/Code/support.txt.
css_file();
Returns the CSS file associated with this block type.
css_inline();
Returns the contents of the CSS file associated with this block type.
css_my_class( @extra );
Returns an appropriately formatted CSS class for this block type. If any arguments are passed, they are added to the end of the class name, separated by dashes.
Examples:
# returns text-multi-code
Text::Multi::Block::Code->css_my_class();
# returns text-multi-code-perl
Text::Multi::Block::Code->css_my_class( 'perl' );render();
Renders the content of the block as HTML and returns it.
SEE ALSO
http://www.jasonkohles.com/software/Text-Multi/.
AUTHOR
Jason Kohles, <email@jasonkohles.com>.
COPYRIGHT AND LICENSE
Copyright (C) 2007 by Jason Kohles
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.