# Titanium.UI.iOS.DocumentViewer

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

Availability
2.1.1
9.2.0

# Overview

The DocumentViewer is created by the Titanium.UI.iOS.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 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 or Titanium.Filesystem.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:

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 (opens new window).

# Examples

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

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

Availability
2.1.1
9.2.0
annotation :Dictionary | Array | String | Number | Date

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.


# apiName READONLY

Availability
3.2.0
9.2.0
apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.


# bubbleParent

Availability
3.0.0
9.2.0
bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true


# name READONLY

Availability
2.1.1
9.2.0
name :String

Name of the file (without the path).

Only returns a value after the document has been previewed.


# url

Availability
2.1.1
9.2.0
url :String

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

# addEventListener

Availability
2.1.1
9.2.0
addEventListener(name, callback) void

Adds the specified callback as an event listener for the named event.

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# applyProperties

Availability
3.0.0
9.2.0
applyProperties(props) void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# fireEvent

Availability
2.1.1
9.2.0
fireEvent(name[, event]) void

Fires a synthesized event to any registered listeners.

Parameters

Name Type Description
name String

Name of the event.

event Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type
void

# hide

Availability
2.1.1
9.2.0
hide([options]) void

Dismisses the document viewer.

Parameters

Name Type Description
options DocumentViewerOptions

Animation options.

Returns

Type
void

# removeEventListener

Availability
2.1.1
9.2.0
removeEventListener(name, callback) void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

# show

Availability
2.1.1
9.2.0
show([options]) void

Displays the document viewer over the current view.

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

Parameters

Name Type Description
options DocumentViewerOptions

Display options.

Returns

Type
void

# Events

# load

Availability
2.1.1
9.2.0

Fires when the document is previewed.


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


# unload

Availability
2.1.1
9.2.0

Fires when the document is dismissed.