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.

insert_signature

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

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.

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

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.)

get_instant

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.

As a valued partner and proud supporter of MetaCPAN, StickerYou is
happy to offer a 10% discount on all Custom Stickers,
Business Labels, Roll Labels,
Vinyl Lettering or Custom Decals. StickerYou.com
is your one-stop shop to make your business stick.
Use code METACPAN10 at checkout to apply your discount.