NAME

Any::Renderer - Common API for modules that convert data structures into strings

SYNOPSIS

$renderer = new Any::Renderer ( $format, \%options );
$string = $renderer->render ( $structure );
$bool = Any::Renderer::requires_template ( $format );
$list_ref = Any::Renderer::available_formats ();

DESCRIPTION

A renderer in this context is something that turns a data structure into a string. This includes templating engines, serialisers etc.

This module provides a consistent API to these services so that your application can generate output in an extensible variety of formats. Formats currently supported include:

- XML (via XML::Simple)
- XML+XSLT
- Data::Dumper
- Javascript, Javascript::Anon & JSON
- UrlEncoded
- The formats supported by Data::Serializer (e.g. Config::General and Config::Wrest)
- Any templating language supported by Any::Template

The module will discover any backend modules and offer up their formats. Once loaded, Any::Renderer will look for a module to handle any new formats it doesn't know about, so adding new formats in a persistent environment won't require the module to be reloaded. However if you CHANGE which module provides a format you will need to reload Any::Renderer (e.g. send a SIGHUP to modperl).

METHODS

$r = new Any::Renderer($format,\%options)

Create a new instance of an Any::Render object using a rendering format of $format and the options listed in the hash %options (see individual rendering module documentation for details of which options various modules accept).

$string = $r->render($data_structure)

Render the data structure $data_structure with the Any::Renderer object $r. The resulting string will be returned.

$bool = Any::Renderer::requires_template($format)

Determine whether or not the rendering format $format requires a template to be passed as an option to the object constructor. If the format does require a template than 1 will be returned, otherwise 0.

$list_ref = Any::Renderer::available_formats()

Discover a list of all known rendering formats that the backend modules provide, e.g. ( 'HTML::Template', 'JavaScript' [, ...]).

GLOBAL VARIABLES

@Any::Renderer::LowPriProviders

A list of backend providers which have lower precedence (if there is more than one module which provides a given format). The earlier things appear in this list, the lower the precedence.

Defaults to Data::Serializer as this provides both XML::Simple and Data::Dumper (which have native Any::Renderer backends).

WRITING A CUSTOM BACKEND

Back-end modules should have the same public interface as Any::Renderer itself:

$o = new Any::Renderer::MyBackend($format, \%options);

$string = $o->render($data_structure);

$bool = requires_template($format)

$arrayref = available_formats()

For example:

package Any::Renderer::MyFormat;
sub new {
  my ( $class, $format, $options ) = @_;
  die("Invalid format $format") unless($format eq 'MyFormat');
  return bless({}, $class); #More complex classes might stash away options and format 
}

sub render {
  my ( $self, $data ) = @_;
  return _my_format($data);
}

sub requires_template {
  die("Invalid format") unless($_[0] eq 'MyFormat');
  return 0; #No template required
}

sub handle_formats {
  return [ 'MyFormat' ]; #Just the one
}

SEE ALSO

All the modules in the Any::Renderer:: distribution

http://search.cpan.org/dist/Any-Renderer. Each module lists the formats it supports in the FORMATS section. Many of also include sample output fragments.

Any::Template

A templating engine is a special case of a renderer (one that uses a template, usually from a file or string, to control formatting). If you are considering exposing another templating language via Any::Renderer, instead consider exposing it via Any::Template. All the templating engines supported by Any::Template are automatically available via Any::Renderer.

Data::Serializer

A serializer is a special case of a renderer which offers bidirectional processing (rendering == serialization, deserialisation does not map to the renderer interface). If you are considering exposing another serialization mechanism via Any::Renderer, instead consider exposing it via Data::Serializer. All the serializers supported by Data::Serializer are automatically available via Any::Renderer.

VERSION

$Revision: 1.14 $ on $Date: 2006/09/04 12:15:52 $ by $Author: johna $

AUTHOR

Matt Wilson (original version by John Alden) <cpan _at_ bbc _dot_ co _dot_ uk>

COPYRIGHT

(c) BBC 2006. This program is free software; you can redistribute it and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt