# Titanium.UI.iOS.DocumentViewer

> A DocumentViewer provides in-app support for managing user interactions with files on the local system.

- Source: https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.UI.iOS.DocumentViewer
- Titanium SDK version: 13.1.1
- Kind: proxy
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK iPhone 2.1.1, iPad 2.1.1, macOS 9.2.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

The DocumentViewer is created by the [Titanium.UI.iOS.createDocumentViewer](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#createDocumentViewer) method.

Use this class to present an user interface for previewing files,
such as an e-mail program that previews attachments.

The DocumentViewer displays previews for the following document types:

  * Microsoft Office (DOC, XLS, PPT) (Office 97-2004), the XML versions are not supported
  * Portable Document Format files (PDF)
  * Images (JPEG, GIF, PNG)
  * Rich Text Format files (RTF)
  * HTML and XML files
  * Plain text files
  * Comma-separated value files (CSV)

Note: Using HTML content in the DocumentViewer is not recommended, since it does not support
all HTML-capabilities. Please use [Titanium.UI.WebView](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md) to display complex HTML files.

You can launch the document either in the document viewer or with another application with the
options menu. To use the options menu, you need to specify a view with the `show` method to
anchor the options menu to.

In the document viewer, click the **Done** button to dismiss the document viewer or click the
right navigation button to open the options menu to perform another action with the document,
such as printing the document or opening the document in another application.

**Note for iOS 11 and later**
When using the DocumentViewer in iOS 11 and later, documents need to be placed in the app-bundle
in order to be shared to third-party apps. This is a privacy restriction and can be solved by
using either a document from the `Resources` directory (classic Titanium) or `app/assets` (Alloy).
Alternatively, documents can also be stored in the [Titanium.Filesystem.applicationCacheDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#applicationCacheDirectory)
or [Titanium.Filesystem.applicationDataDirectory](https://titaniumsdk.com/docs/sdk/Titanium.Filesystem.md#applicationDataDirectory).

**Note for iOS 11.2 and later**
Apple introduced a regression in iOS 11.2 that forces **all** files to be in the application data
directory. We handle this workaround for you in Titanium SDK 7.0.2+, but you
can also work around it without an SDK update. Here is an example:

``` js
var fileName = 'example.pdf';

// For iOS 11.2, workaround the Apple issue by creating a temporary file and
// reference it. It will be removed from filesystem once the app closes.
// Read more here: http://nshipster.com/nstemporarydirectory/
if (isiOS11_2()) {
  fileName = fileInApplicationDataDirectory(fileName);
}

var docViewer = Ti.UI.iOS.createDocumentViewer({
  url: fileName
});

docViewer.show();

// Check if the current device runs iOS 11.2+
function isiOS11_2() {
  var version = Ti.Platform.version.split(".");
  return (parseInt(version[0]) >= 11 && parseInt(version[1]) >= 2);
}

// Create a temporary file with the contents of the old file
// Expects the file to be in the resources directory. If you receive the file
// from an API-call, receive pass the Ti.Blob/Ti.File/text to "write" directly.
function fileInApplicationDataDirectory(fileName) {
  var file = Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, fileName);

  if (!file.exists()) {
    alert('File does not exist in resources!');
    return;
  }

  var newFile = Titanium.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, fileName);
  newFile.createFile();

  if (!newFile.exists()) {
    alert('New file could not be created in application data directory!');
    return;
  }

  newFile.write(file);

  return newFile.nativePath;
}
```

Read more about the issue in [TIMOB-25680](https://jira-archive.titaniumsdk.com/TIMOB-25680).

## Example: Document Viewer Example

In the example below, the navigation bar's right button opens the options menu,
while the window button immediately launches the document in the document viewer.

``` js
var navButton = Ti.UI.createButton({
    title: 'Launch'
});

var win = Ti.UI.createWindow({
    rightNavButton: navButton
});

var navWin = Ti.UI.createNavigationWindow({
    window: win
});

var winButton = Ti.UI.createButton({
    title: 'Launch',
    height: 40,
    width: 200,
    top: 270
});

win.add(winButton);

// Create a document viewer to preview a PDF file ("Example.pdf")
docViewer = Ti.UI.iOS.createDocumentViewer({
    url: 'Example.pdf'
});

// Opens the options menu and when the user clicks on 'Quick Look'
// the document viewer launches with an animated transition
navButton.addEventListener('click', function() {
    docViewer.show({
        view: navButton,
        animated: true
    });
});

// The document viewer immediately launches without an animation
winButton.addEventListener('click', function(){
    docViewer.show()
});

navWin.open();
```

## Properties

### annotation

- Type: Dictionary | Array | String | Number | Date
- Platforms: iPhone, iPad, macOS

Custom property list information for the target file.

Use this property to pass information about the document type to the app responsible for opening it.

### name

- Type: String
- Platforms: iPhone, iPad, macOS
- Permission: read-only

Name of the file (without the path).

Only returns a value after the document has been previewed.

### title

- Type: String
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 12.7.0

Title of the file.

Use this property to specify the document title that is displayed in the navigation bar.
If not set, it uses the URL path of the loaded document.

### url

- Type: String
- Platforms: iPhone, iPad, macOS

URL of the document being previewed.

Important note: For iOS 11.2 and later, you need to reference this URL
from either the application data directory or temporary directory. Read
more about this change in the "Note for iOS 11.2 and later" paragraph of
the API summary.

## Methods

### hide

- Platforms: iPhone, iPad, macOS

Dismisses the document viewer.

Parameters:

- `options` (DocumentViewerOptions, optional): Animation options.

### show

- Platforms: iPhone, iPad, macOS

Displays the document viewer over the current view.

To show the options menu, set the `view` key of the options object.

Parameters:

- `options` (DocumentViewerOptions, optional): Display options.

## Events

### load

- Platforms: iPhone, iPad, macOS

Fires when the document is previewed.

### menu

- Platforms: iPhone, iPad, macOS

Fires when the options menu appears before the document is previewed.

### unload

- Platforms: iPhone, iPad, macOS

Fires when the document is dismissed.

## Inherited members

6 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.