/ 
Mojo-SAML-0.07
River stage zero No dependents
/ Mojo::SAML::Document

NAME

Mojo::SAML::Document - Base class for classes representing and generating XML snippets

SYNOPSIS

# use as a base class
package Mojo::SAML::Document::MyDocument;
use Mojo::Base 'Mojo::SAML::Document';

has template => sub { shift->build_template(<<'TEMPLATE') };
<SomeXML>...</SomeXML>
TEMPLATE

# direct usage
my $doc = Mojo::SAML::Document->new;
$doc->template($doc->build_template(<<'TEMPLATE'));
<SomeXML>...</SomeXML>
TEMPLATE
my $output = $doc->to_string;
my $ouput = "$doc";

DESCRIPTION

Mojo::SAML::Document is a base class for classes that represent XML snippets and can be used to generate those snippets from data. These objects stringify to their XML representation (based on their "template") making them easily composable.

While intended as a base class, it can also be used directly for one-off snippets when setting the "template" manually.

ATTRIBUTES

Mojo::SAML::Document inherits all of the attributes from Mojo::Base and implements the following new ones.

insert_signature

Optional. A signature document, likely an instance of Mojo::SAML::Docuemnt::Signature to insert. See later methods for more description.

insert_xml_declaration

Optional, undefined (false) by default. If true the resulting rendered document will contain an XML declaration. This should only be set (if at all) on the outermost document snippet. See later methods for more description.

sign_with_key

Optional. A key to sign the document, likely an instance of Crypt::OpenSSL::RSA. See later methods for more description.

template

An instance of Mojo::Template used to generate the XML. The default implementation dies if not set. Commonly, subclasses will overload this to provide an appropriate template for the class.

METHODS

Mojo::SAML::Document inherits all of the methods from Mojo::Base and implements the following new ones.

after_render

$xml = $doc->after_render($xml);

Called during rendering (see "to_string") after the document is rendered but before it is wrapped in a Mojo::ByteStream and returned. It is provided here to allow overriding by specific document types. This method can be used to post-process the rendered document.

The default implementation of this method calls "after_render_insert_signature" if a signature is given in "insert_signature". If then calls "after_render_sign" if a key is given in "sign_with_key". Finally it calls "after_render_insert_xml_declaration" if "insert_xml_declaration" is true.

This default implementation allows any document to be signed during rendering by giving an appropriate document (likely a Mojo::SAML::Document::Signature) and a key (an instance of Crypt::OpenSSL::RSA). Note that you probably only want to sign once on a full document render (not once per snippet) so keep that in mind when composing your snippets.

after_render_insert_signature

$xml = $doc->after_render_insert_signature($xml, $signature);

Called during the default "after_render" implementation. It is provided here to allow overriding the insert by specific documents types. Note that this default implementation requires a Mojo::SAML::Document::Sigature object when called and actually returns a Mojo::DOM reprenting the parsed form of its input.

Note that this is probably not that useful to call directly.

after_render_insert_xml_declaration

$xml = $doc->after_render_insert_xml_declaration($xml);

Called during the default "after_render" implementation. It is provided here to allow overriding the insert by specific documents types. It prepends a standard XML declaration to the passed-in document.

Note that this is probably not that useful to call directly.

after_render_sign

$xml = $doc->after_render_sign($xml, $key);

Called during the default "after_render" implementation. It is provided here to allow overriding the signing process by specific documents types. Calls "sign" in Mojo::XMLSig with the XML payload and the given key.

Note that this is probably not that useful to call directly.

before_render

$doc->before_render();

Called during rendering (see "to_string") before the document is rendered. It is provided here to allow overriding by specific document types. This method can be used to pre-process and/or validate the object before rendering. The return value is ignored.

The default implementation does nothing.

build_template

has template => sub { shift->build_template($string) };

Builds an instance of Mojo::Template from a given string. This is especially useful in the "template" initializer.

The resulting template sets autoescape to true which promotes good xml escaping. It configures the template to shift off the invocant as $self for use during the template. (Note that during "to_string" or stringification no arguments are passed to the template rendering, so this is very useful.)

Finally, it sets namespace to Mojo::SAML::TemplateSandbox. This namespace is prepopulated with "binding" in Mojo::SAML::Names and "nameid_format" in Mojo::SAML::Names functions as well as a version of "tag" in Mojolicious::Plugins::TagHelpers.

get_guid

my $guid = $doc->get_guid;

Generates a GUID using "guid_string" in Data::GUID.

get_instant

my $instant = $doc->get_instant;

Generates an "http://tools.ietf.org/html/rfc3339" in "RFC 3339" datetime representing the current time using "to_datetime" in Mojo::Date.

to_string

my $xml = $doc->to_string;

Generates a string representation of the document. First calls "before_render" for possible validation. Then renders the "template" using "process" in Mojo::Template passing the document itself into the template. Then it post-processes the document by calling "after_render" with the rendered result. Finally that result is wrapped in a Mojo::ByteStream object (to prevent later rendering from xml escaping) and returned.

to_string_deflate

Calls "to_string" but further DEFLATE encodes and base64 encodes the result. This is useful when the document is going to passed as a query parameter. Note that when you do this, you probably don't want to include a signature nor sign it as in this case there is a different signing procedure.

OPERATORS

Mojo::SAML::Document overloads the following operators.

bool

my $bool = !!$doc;

Always true.

stringify

my $str = "$doc";

Alias for "to_string".