Textastic x-callback-url API

Textastic for iOS exposes actions that can be used by other apps using the x-callback-url specification.

All currently implemented actions involve opening an existing file or creating a new one and inserting or replacing text.

Registered URL schemes

Textastic registers the following URL schemes:

• Textastic for iPad: textastic://, x-textastic-ipad://
• Textastic for iPhone: textastic://, x-textastic-iphone://

To target either version of Textastic, use “textastic://”. The “x-” versions are provided if you need to specifically call or test for the installation of the iPad vs. iPhone version.

x-callback-url URL Format

The format for Textastic’s URL scheme looks like this:

textastic://x-callback-url/[action]?[x-callback parameters]&[action parameters]

The x-callback parameters are defined by the x-callback-url protocol, and are optional for all actions.

The action parameters are defined in the API below, and are unique to each action.

Some actions will return information to the calling app. When an action returns information, the parameters passed back to the calling app are documented with the API below.

Supported x-callback-url Parameters

All of Textastic’s actions will accept all of the x-callback parameters: x-source, x-success, x-error, and x-cancel. There are some cases where the action and callback do not make sense. For example, when the open action successfully opens a file, there is no reason to callback the x-success URL. In these cases, the x-callback parameter is ignored.

• x-source: The name of the calling app.
• x-success: A complete URL to call when the action completed successfully.
• x-error: A complete URL to call when the action failed.
• x-cancel: A complete URL to call when the action was canceled by the user.

Actions

new

Create a new file in the local file system or in iCloud.

Parameters

• location: iCloud or local. If not specified, defaults to the local file system.
• path: The directory path. If not specified, defaults to the root folder.
• name: The name of the file to create. If a file with that name already exists, Textastic will append a number to the file name to make it unique. If not specified, a file name will be generated by Textastic.
• text: The text to insert into the new file.
• snippet: The snippet to insert. If both the snippet and the text parameter are present, only the snippet parameter will be used.

If neither the text parameter nor the snippet parameter is specified, the text to append will come from the clipboard.

Examples

Create a new file “foo.txt” in the local root directory and insert “bar”:

textastic://x-callback-url/new?name=foo.txt&text=bar

Create a new file “foo.txt” in iCloud in the “test” folder and insert the snippet “foo $0 bar”. This snippet places the cursor between foo and bar after the insertion.

textastic://x-callback-url/new?location=icloud&name=foo.txt&path=test&snippet=foo%20$0%20bar

---

open

Open an existing file in the local file system or in iCloud. If the file doesn’t exist, calls the url from the x-error parameter.

Parameters

• location: iCloud or local. If not specified, defaults to the local file system.
• path: The directory path. If not specified, defaults to the root folder.
• name: The name of the file to open.

Example

Open the file “index.html” in the “example.com” folder in the local file system.

textastic://x-callback-url/open?path=example.com&name=index.html

---

append

Open an existing file or create a new file and append text.

Parameters

• location: iCloud or local. If not specified, defaults to the local file system.
• path: The directory path. If not specified, defaults to the root folder.
• name: The name of the file to open. If the file doesn’t exist, it will be created.
• text: The text to append to the file.
• snippet: The snippet to append to the file. If both the snippet and the text parameter are present, only the snippet parameter will be used.

If neither the text parameter nor the snippet parameter is specified, the text to append will come from the clipboard.

Example

Append the contents of the clipboard to the file clipboard.txt in the iCloud root folder:

textastic://x-callback-url/append?location=iCloud&name=clipboard.txt

---

replace

Open an existing file or create a new file and replace its contents with the specified text.

Parameters

• location: iCloud or local. If not specified, defaults to the local file system.
• path: The directory path. If not specified, defaults to the root folder.
• name: The name of the file to open. If the file doesn’t exist, it will be created.
• text: The text to insert into the file after its contents are deleted.
• snippet: The snippet to insert into the file after its contents are deleted. If both the snippet and the text parameter are present, only the snippet parameter will be used.

If neither the text parameter nor the snippet parameter is specified, the replacement text will come from the clipboard.

Example

Replace the contents of the file scratchpad.txt in the iCloud root folder with the string “foo”:

textastic://x-callback-url/replace?location=iCloud&name=scratchpad.txt&text=foo

Download using the textastic:// scheme

In addition to x-callback-url support, the textastic:// scheme can be used to easily download the server response of HTTP URLs.

You can use this feature to view the source code of a website or download files into Textastic.

This is what you need to do:

• Make sure your iPad or iPhone has an active internet connection
• Open a website in Safari or another browser app like Chrome
• Tap on the address bar
• Replace http:// with textastic://
• Hit Return
• Textastic will open and start to download the file at the URL. It will be saved to the root directory in the local file system. When the file is downloaded, it will be opened in the editor.