# Output

## Basic Usage

```markup
<xf:output ref="text"/>
```

or:

```markup
<xf:output value="current-dateTime()"/>
```

## Using a media type

`<xf:output>` supports a `mediatype` attribute on that element allowing display of other media types.

### Image mediatypes

For the `<xf:output>` control to display an image, you need to:

* Have a `mediatype` attribute on the `<xf:output>`. That attribute must refer to an image mediatype, such as `image/*` or `image/jpeg`.
* Use the `value` attribute on `<xf:output>` or bind to the control to a node without type, with an `xs:anyURI` type or with an `xs:base64Binary` type.

The resulting value from the instance is interpreted either as a URI pointing to an image, or as a base64-encoded binary representation of the image. The image will display in place of the `<xf:output>`. It is possible to dynamically change the image pointed to. For example:

```markup
<xf:output 
    mediatype="image/*" 
    value="'/images/moon.jpg'"/>
```

or:

```markup
<xf:model>
  <xf:instance>
    <image-uri/>
  </xf:instance>
  <xf:bind ref="image-uri" type="xs:anyURI"/>
</xf:model>
...
<xf:output mediatype="image/*" ref="image-uri"/>
```

The image URI may or may not be reachable from the client browser. Orbeon Forms hides this from the developer. For example, to upload and show an image:

```markup
<!-- Hide xf:output when there is no URI available -->
<xf:group ref="image[normalize-space() != '']">
  <!-- Image output -->
  <xf:output ref="." mediatype="image/*">
    <xf:label/>
  </xf:output>
</xf:group>
<!-- File chooser -->
<xf:upload ref="image">
  <xf:label/>
  <xf:filename  ref="@filename"/>
  <xf:mediatype ref="@mediatype"/>
  <xxf:size     ref="@size"/>
</xf:upload>
```

In that example, the upload control stores a temporary URI pointing to a local `file:` resource. While this URI is not visible from the client web browser, the output control automatically proxies it so that the end user can see the image.

### HTML mediatype

When an `<xf:output>` control has a `mediatype` attribute with value `text/html`, the value of the node to which the control is bound is interpreted as HTML content. Consider the following XForms instance:

```markup
<xf:instance id="my-instance">
  <form>
    <html-content> This is in &lt;b&gt;bold&lt;/b&gt;! </html-content>
  </form>
</xf:instance>
```

You bind an `<xf:output>` control to the `html-content` node as follows:

```markup
<xf:output ref="instance('my-instance')/html-content" mediatype="text/html"/>
```

This will display the result as HTML, as expected: "This is in **bold**!". If the `mediatype` is not specified, the result would be instead: "This is in **bold**!". In the XForms instance, the HTML content must be escaped as text. On the other hand, the following content will not work as expected:

```markup
<xf:instance>
  <form>
    <html-content> This is in in <b>bold</b>! </html-content>
  </form>
</xf:instance>
```

*NOTE: When using a* `mediatype="text/html"`*, an HTML* `<div>` *element will be generated by the XForms engine to hold the HTML data. As in HTML a* `<div>` *cannot be embedded into a* `<p>`*, if you have a* `<xf:output mediatype="text/html">` *control, you should not put that control into a* `<xh:p>`*.*

## xxf:download appearance

`<xf:output>` supports the `xxf:download` appearance, which causes the the resource identified by the single-node binding to be downloadable through a link.

Like `<xf:upload>`, when using this appearance, `<xf:mediatype>` and `<xf:filename>` children elements are allowed (but not the `<xxf:size>` element). When serving the file, if these elements are present, they are passed to the resulting HTTP response to provide mediatype and file name hints to the browser. Example:

```markup
<xf:instance id="my-instance">
  <instance>
    <file mediatype="" filename="" size=""/>
  </instance>
</xf:instance>
...
<xf:upload ref="file">
  <xf:label>Upload</xf:label>
  <xf:mediatype ref="@mediatype"/>
  <xf:filename  ref="@filename"/>
  <xxf:size     ref="@size"/>
</xf:upload>


<xf:output ref="file" appearance="xxf:download">
  <xf:label>Download</xf:label>
  <xf:mediatype ref="@mediatype"/>
  <xf:filename  ref="@filename"/>
</xf:output>
```

The data type for the resource must be `xs:anyURI` or `xs:base64Binary`.

## HTTP headers

When the output control performs an HTTP request as a result of dereferencing a URL, for example, as the result of using an image mediatype, the nested `<xf:header>` child element allows specifying custom headers to set on the HTTP request.

The syntax for `<xf:header>` is the same as the `<xf:header>` child element of `<xf:submission>`.

```markup
<xf:output ref="instance()" mediatype="image/*">
    <xf:header ref="instance('headers')/header">
        <xf:name  value="@name"/>
        <xf:value value="@value"/>
    </xf:header>
</xf:output>
```