Cataly...Include(3pm)

💖 Catalyst::View::Component::SubInclude 💖

okay bestie so this is a page from the User Contributed Perl Documentation set, and it's giving "let me stitch other actions' output into my templates" energy. Here's the whole vibe, no cap. 🦋

---

✨ NAME ✨

Catalyst::View::Component::SubInclude — use subincludes in your Catalyst views 🎀

---

✨ VERSION ✨

Version 0.10 💅

---

✨ SYNOPSIS ✨

so first, you set up your view like this:

package MyApp::View::TT;
use Moose;

extends 'Catalyst::View::TT';
with 'Catalyst::View::Component::SubInclude';

__PACKAGE__->config( subinclude_plugin => 'SubRequest' );

and then, literally somewhere in your templates:

[% subinclude('/my/widget') %]
[% subinclude_using('SubRequest', '/page/footer') %]

slay. that's it. that's the whole vibe. ✨

---

✨ DESCRIPTION ✨

Catalyst::View::Component::SubInclude lets you pull content into your templates (or, more generally, anywhere in your view's render processing, bestie, we're not picky) where that content comes from another action in your application. It's built as a Moose::Role, so yeah — you need Moose in your view. no Moose, no magic. 🙈

put simply: it's a way to drop the output of a Catalyst sub-request into your page. 🫶

and the way it's built? extensible 💚 so you're totally free to use sub-requests, Varnish ESI (<http://www.catalystframework.org/calendar/2008/17>) or literally any other sub-include plugin you feel like implementing. main character energy, honestly.

---

✨ STASH FUNCTIONS ✨

this component does its lil magic by exporting a subinclude coderef entry into the stash. so it's right there for your templates to grab — which, let's be real, is the most common use-case. 💅

subinclude( $path, @args )

this renders and returns the body of the included resource (whatever $path says) using the default subinclude plugin. 🎀

subinclude_using( $plugin, $path, @args )

this renders and returns the body of the included resource (as specified by $path) using the specified subinclude plugin.

and the subinclude function up there? it's basically a shortcut that calls this one, with the default plugin as the first parameter. iconic behaviour, tbh.

---

✨ SUBINCLUDE PLUGINS ✨

the module comes with two subinclude plugins: SubRequest, Visit and ESI. 😭 (yes bestie, i typed exactly what the page says, the counting is not my problem, i just work here)

by default, the SubRequest plugin gets used. you can change that in the view's configuration options — either in the config file or right in the view module itself. 💖

config file example:

<View::TT>
    subinclude_plugin   ESI
</View::TT>

set_subinclude_plugin( $plugin )

this method swaps the currently active subinclude plugin at runtime. it expects the plugin suffix (like ESI or SubRequest) or a fully-qualified class name in the Catalyst::View::Component::SubInclude namespace. 🌸

Writing plugins

if you're writing your own plugin, keep in mind (ngl the original typo'd this as "keep in kind" and i think about it constantly) that plugins are required to implement a class method generate_subinclude with this exact signature:

sub generate_subinclude {
    my ($class, $c, @args) = @_;
}

the default plugin is stored in the subinclude_plugin, which can be changed at runtime. it expects a fully qualified class name. ✨

---

✨ SEE ALSO ✨

• Catalyst::Plugin::SubRequest
• Moose::Role
• Moose
• <http://www.catalystframework.org/calendar/2008/17>

---

✨ BUGS ✨

please report any bugs or feature requests to bug-catalyst-view-component-subinclude at rt.cpan.org, or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Catalyst-View-Component-SubInclude>. i will be notified, and then you'll automatically be notified of progress on your bug as i make changes. 🫶 we love a feedback loop.

---

✨ AUTHOR ✨

Nilson Santos Figueiredo Junior, <nilsonsfj at cpan.org> 👑

---

✨ CONTRIBUTORS ✨

• Tomas Doran (t0m) <bobtfish@bobtfish.net.
• Vladimir Timofeev, <vovkasm at gmail.com>.
• Wallace Reis (wreis) <wreis@cpan.org>.

---

✨ SPONSORSHIP ✨

development sponsored by Ionzero LLC <http://www.ionzero.com/>. 💰✨

---

✨ COPYRIGHT & LICENSE ✨

• Copyright (C) 2010 Nilson Santos Figueiredo Junior and the above contributors.
• Copyright (C) 2009 Nilson Santos Figueiredo Junior.
• Copyright (C) 2009 Ionzero LLC.

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🎀

---

fr fr that's the whole page, every flag-free fact intact, nothing skipped. 💜

perl v5.34.0 · 2022-06-09 · Cataly...Include(3pm) — ok bye bestie, go subinclude something cute 🌈💖✨