X-Callback-URL API and Other URL Schemes
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
To target any installed version of Textastic, use the textastic:// URL scheme.
These additional URL schemes are registered by the various versions of Textastic:
App |
URL Scheme |
|---|---|
Textastic v6 and later (universal app) |
x-textastic-universal:// |
Textastic v5 and earlier for iPad |
x-textastic-ipad:// |
Textastic v5 and earlier for iPhone |
x-textastic-iphone:// |
The “x-” versions are provided if you need to specifically call or test for the installation of the Universal vs. the iPad or 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.
If a file with the specified name already exists, Textastic will generate a unique file name by appending a number to the file name (e.g. “test 2.txt” instead of “test.txt”).
Parameters
location: iCloud, local, or external. 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.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
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
Create a new file “test.txt” in the specified external folder in the “test” folder and insert the clipboard contents.
textastic://x-callback-url/new?location=external&externalUUID=62E8D362-7DFA-413C-874E-20C1D98B17C0&name=test.txt&path=test
open
Open an existing file in the local file system, iCloud, or an external folder.
If the file doesn’t exist, calls the url from the x-error parameter.
Parameters
location: iCloud, local, external, or fullPath.
If not specified, defaults to the local file system.
Use “fullPath” to open an external file if you don’t know the UUID of an external folder, but have the full local path of the file in the file system. This is useful for apps that include a file provider and want to open a file in Textastic. It is used by the “Edit in Textastic” command of the Git client app Working Copy.
path: The directory path. If not specified, defaults to the root folder.
name: The name of the file to open.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
suggestedExternalFolderPath: If location is “fullPath”, you can specify this parameter and Textastic will prompt for adding that folder as an external folder if the file could not be accessed.
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, local, or external. 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.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
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, local, or external. 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.
externalUUID: If location is “external”, use this parameter to specify the identifier of an external folder. You can get the UUID by showing the context menu of an external folder in Textastic and selecting “Copy Identifier (UUID)”.
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://withtextastic://Tap Go on the on-screen keyboard
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.