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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.orbeon.com/xforms/controls/output.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.