---
name: "Catalyst::View::Component::SubInclude"
section: "3pm"
platform: "linux"
package: "libcatalyst-view-component-subinclude-perl"
version: "0.10-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Catalyst::View::Component::SubInclude"
---

# Catalyst::View::Component::SubInclude(3pm)

Use subincludes in your Catalyst views

## NAME

Catalyst::View::Component::SubInclude - Use subincludes in your Catalyst views

## VERSION

Version 0.10

## SYNOPSIS

```
  package MyApp::View::TT;
  use Moose;
  extends 'Catalyst::View::TT';
  with 'Catalyst::View::Component::SubInclude';
  __PACKAGE__->config( subinclude_plugin => 'SubRequest' );
```

Then, somewhere in your templates:

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

## DESCRIPTION

`"Catalyst::View::Component::SubInclude"` allows you to include content in your templates (or, more generally, somewhere in your view's `"render"` processing) which comes from another action in your application. It's implemented as a Moose::Role, so using Moose in your view is required.

Simply put, it's a way to include the output of a Catalyst sub-request somewhere in your page.

It's built in an extensible way so that you're free to use sub-requests, Varnish ESI (\<http://www.catalystframework.org/calendar/2008/17\>) or any other sub-include plugin you might want to implement.

## STASH FUNCTIONS

This component does its magic by exporting a `"subinclude"` coderef entry to the stash. This way, it's easily accessible by the templates (which is the most common use-case).

### "subinclude( $path, @args )"

This will render and return the body of the included resource (as specified by `$path`) using the default subinclude plugin.

### "subinclude\_using( $plugin, $path, @args )"

This will render and return the body of the included resource (as specified by `$path`) using the specified subinclude plugin.

The `"subinclude"` function above is implemented basically as a shortcut which calls this function using the default plugin as the first parameter.

## SUBINCLUDE PLUGINS

The module comes with two subinclude plugins: SubRequest, Visit and ESI.

By default, the `"SubRequest"` plugin will be used. This can be changed in the view's configuration options (either in the config file or in the view module itself).

Configuration file example:

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

### "set\_subinclude\_plugin( $plugin )"

This method changes the current active subinclude plugin in runtime. It expects the plugin suffix (e.g. `"ESI"` or `"SubRequest"`) or a fully-qualified class name in the `"Catalyst::View::Component::SubInclude"` namespace.

### Writing plugins

If writing your own plugin, keep in kind plugins are required to implement a class method `"generate_subinclude"` with the following signature:

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

The default plugin is stored in the `"subinclude_plugin"` which can be changed in 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.

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