Once you have basic TextExpander support up and running, you’ll probably want to take advantage of a new feature in TextExpander touch 2.0: support for fill-in snippets. Fill-ins allow the user to set up a longer snippet with one or more variable fields embedded, which can be text fields, conditionally included sections, and popup menus to choose among selected options.
The fill-in process uses x-callback URLs; the app switches to the TextExpander touch app, where the user fills out field values, then switches back to your app, where the completed text is inserted. You can learn more about the x-callback-url specification at http://x-callback-url.com. It might be useful to learn more if you want to support x-callback URLs to provide other functionality to your app, but we’ll include all the information you need to support fill-in snippets here in this document.
You can read more about the TextExpander touch SDK at smilesoftware.com/sdk, and download (or clone) the SDK itself here on Github. The SDK includes a great sample project that will get you up and running with integrating TextExpander touch into your app. If you'd like to download the code for this example (which is smaller and simpler than the one in the SDK itself), you can get it at github.com/cantoni/TextExpanderSDKExample.
Add a URL Scheme to your App
First, add a URL scheme to your app so that other applications can talk back to you. Add the scheme to your app's target under Info > "URL Types”. If you’re already using a URL scheme, you can leave it as is—we make it easy to differentiate between callbacks intended for TextExpander touch fill-ins and callbacks intended for other purposes.
Add open:URL: to App Delegate
In your app delegate, implement application:openURL:sourceApplication:annotation: and call the SMTEDelegateController's handleFillCompletionURL: with any URL's that have that scheme.
Set Up Fill-In support in your View Controller
Now we should add fill-in support to your view controller. First, let’s make your SMTEDelegateController recognize support for fill-ins. To do that, we set a few properties on the SMTEDelegateController:
1. Set the fillCompletionScheme property with your application’s callback URL.
2. Set the fillDelegate property with your SMTEFillDelegate implementing object
3. Set the fillForAppName property with your app's name (eg. "SuperTyper"). This will appear in the fill-in view's title, something like "SuperTyper fill-in: [fill abrv]"
Implement the SMTEFillDelegate protocol
The SMTEFillDelegate protocol lets TextExpander touch return first responder status to the correct text item and insert a completed fill-in snippet. It has three parts: identifierForTextArea:uiTextObject, which figures out what text area was being typed in; prepareForFillSwitch, which gives the application a chance to save its state before the snippet triggers, and makeIdentifiedTextObjectFirstResponder, which returns the snippet to the correct text area and pastes it in.
These methods are heavily commented in the sample project distributed with the TextExpander touch SDK; for this smaller, simpler example, we've taken out some of the comment and implemented these as simply as possible.
Now test it out!
When you invoke the sample snippet "dnthx", the sample app will switch to TextExpander touch and fill in the snippet with fields as below.
Returning Back to the App
The expansion should trigger and get pasted in place when you press "Done" and are returned to your app.