Warning! This page has the following tags:

• This page needs to be merged with docbook documentation.

The Configuration File "output_types.xml"

This is the reference documentation for the OutputTypes configuration file.

First, an example:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<configurations>
  <configuration>
    <output_types default="html">
      <output_type name="html">
        <renderer>AgaviSmartyRenderer</renderer>
        <parameters>
          <parameter name="Content-Type">text/html; charset=UTF-8</parameter>
        </parameters>
      </output_type>
      <output_type name="html_print" fallback="html">
        <renderer extension="-prin.php" ignore_slots="true">AgaviSmartyRenderer</renderer>
        <parameters>
          <parameter name="Content-Type">text/html; charset=UTF-8</parameter>
        </parameters>
      </output_type>
      <output_type name="xml">
        <renderer extension=".xml.php" ignore_decorators="true">AgaviPHPRenderer</renderer>
        <parameters>
          <parameter name="Content-Type">text/xml</parameter>
        </parameters>
      </output_type>
    </output_types>
  </configuration>
</configurations>

Here, three Output Types are defined: "html", "html_print" for print versions of pages, and "xml" for simple xml representations of documents. Now, let's walk through the parts.

Default Output Type

There has to be at least one Output Type defined, and you have to define a default Output Type via the default attribute in the <output_types> tag. This Output Type will be selected on Controller startup.

Fallbacks

Next, the fallbacks. For any Output Type, you can specify an alternative version to be used in case no template could be found for the output type that is currently set in the system. These can easily be cascaded, so Agavi won't stop after the first fallback wasn't successful either. Also, you can use default as the value for this attribute; Agavi will then fall back to the default Output Type defined in the <output_types> tag (see the section "Default Output Type" above).

Renderers

For each Output Type, you have to tell Agavi which Renderer to use (e.h. PHP, Smarty, XSL, PHPTAL etc) by specifying the class name in the <renderer> tag.

Extensions

Often, you want to use the same Renderer for multiple Output Types. Thus, the template file names must be different. By default, Renderers use a default file extension (".php", ".tpl", ".xsl" etc) that is appended to the template you have specified in the View. Use the extension attribute in the <renderer> tag to override the file extension (don't forget to include the dot!)

Decorators and Slots

Sometimes, you don't want to use decorators for certain Output Types. In our example, the XML representation of a page won't be rendered using a decorator, since we most likely are only interested in the actual Action output. If that's the case, disable Decorators for an Output Type using the ignore_decorators attribute.

Also, you sometimes might want to use a Decorator, but no slots, like in our HTML Print Version^* example above, where we want to use a Decorator template to have a header and footer for all documents, but no slots for the sidebar, as in the "normal" HTML Version. Just tell Agavi to ignore assigned slots for this Output Type via the ignore_slots attribute. And yes, of course, disabling Decorators also disables Slots, but you you guessed that already, didn't you.

_{*: yes, I know, you should do that via CSS. It's just an example man, you hear me? E-X-A-M-P-L-E :)}

Parameters

You can also define parameters in the configuration for each Output Type. The keys (parameter names) and values (tag contents) can be totally random, and you have the ability to read these parameters (and the other configuration options) for the current and all other Output Types programatically, for instance, in a filter. Agavi's WebControllers? will use the Content-Type parameter and send it back to the browser, so you should always specify this one.