X-Callback-URL and Other URL Schemes¶
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¶
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.
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://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.