TextExpander touch SDK

(Release notes are found at the bottom of this document.)

Smile provides the TextExpander framework so that you can include TextExpander functionality in your iOS app, custom keyboard, or extension, subject to the License Agreement below.

TextExpander touch SDK home page

TextExpander touch home page

Google Group tetouch-sdk (for announcements)

The TextExpanderDemoApp project is a working example app demonstrating how to add TextExpander functionality to your app and custom keyboard.

How to Add TextExpander to your iOS App

Grab the latest TextExpander touch SDK from GitHub

1. Launch Terminal
2. Change the the directory into which you'd like to download the SDK
3. Run this command:

<pre>git clone https://github.com/SmileSoftware/TextExpanderTouchSDK</pre>

Build the Sample Project

TextExpanderDemoApp demonstrates the key aspects of integrating TextExpander functionality into your iOS app:

• adding TextExpander to your app's build configuration, and required info settings
• acquiring and updating snippet data - DemoApp uses its Settings view
• using the TextExpander delegate in UITextField, UITextView, UISearchBar, and UIWebView, including a regular web view and a content editable web view
• using TextExpander in a custom keyboard (most apps will not need this).

TextExpanderDemoApp is not meant to be a model iOS app. It's meant to demonstrate TextExpander functionality so that you can see it in context and adopt it easily into your app.

1. Download TextExpander from the App Store
2. Open the TextExpanderTouchSDK folder from step 1
3. Double-click TextExpanderDemoApp.xcodeproj or TextExpanderDemoAppSwift.xcodeproj to open the sample project in Xcode
4. Choose Product -> Run to run the sample
5. Tap Settings
6. Turn on "Use TextExpander"
7. Tap Fetch Snippets to get the snippets from TextExpander
8. Tap on the views and expand snippets into them, such as "ddate" or "sig1"

Note: To dismiss the keyboard, tap the whitespace to the left or right of the text field.

Add TextExpander to Your Project

1. Drag TextExpander.xcframework into your project
2. Select your app's target
3. Click on "General"
4. Scroll down to "Frameworks, Libraries, and Embedded Content"
5. Drag the TextExpander.xcframework from your project to that list
6. Select "Embed & Sign" from the popup to the right of where TextExpander.xcframework appears in the list

Allow querying and opening the TextExpander touch app

As of iOS 9 you must add TextExpander URL schemes to LSApplicationQueriesSchemes so that canOpenURL can work properly.

1. Select your app's target
2. Click on "Info"
3. Add a LSApplicationQueriesSchemes key (if your project does not yet have one) with an Array value
4. Add three TextExpander URL scheme values to this array: tetouch, tetouch-xc, and tetouch-settings

Add TextExpander to Your View

TextExpander works with these views:

• UITextView
• UITextField
• UISearchBar
• UIWebView

Objective-C:

1. Import the TextExpander header into your view controller's header:<pre>#import "SMTEDelegateController.h"</pre>
2. Add an SMTEDelegateController to your view controller:<pre>@property (nonatomic, strong) SMTEDelegateController *textExpander;</pre>
3. In your view controller's viewDidLoad method, initialize SMTEDelegateController and make it the delegate of your view(s):<pre>self.textExpander = [[SMTEDelegateController alloc] init];<br>[self.textView setDelegate:self.textExpander];<br>[self.textExpander setNextDelegate:self];</pre>

Swift:

1. Import the TextExpander module into your view controller class:<pre>import TextExpander</pre>
2. Add an SMTEDelegateController to your view controller:<pre>var textExpander: SMTEDelegateController?</pre>
3. In your view controller's viewDidLoad method, initialize SMTEDelegateController and make it a delegate of your view(s):<pre>self.textExpander = SMTEDelegateController(); self.textView!.delegate = self.textExpander</pre>

Disabling TextExpander Custom Keyboard Expansions

TextExpander 3 and 4 ship with a custom keyboard, which can expand TextExpander abbreviations when typed.

Custom keyboards do not support rich text, and their UI is limited such that they cannot support fill-ins.

If your app implements the SDK, you'll want to disable TextExpander custom keyboard expansion for the best user experience.

To disable TextExpander custom keyboard expansion, you'll add a listener for the Darwin notification "com.smileonmymac.tetouch.keyboard.viewWillAppear" and in that listener you'll call [SMTEDelegateController setCustomKeyboardExpansionEnabled:NO]. Here's an example:

<pre> int status = notify_register_dispatch("com.smileonmymac.tetouch.keyboard.viewWillAppear", &SMAppDelegateCustomKeyboardWillAppearToken, dispatch_get_main_queue(), ^(int t) { [SMTEDelegateController setCustomKeyboardExpansionEnabled:NO]; }); </pre>

There is also a corresponding "com.smileonmymac.tetouch.keyboard.viewWillDisappear" notification. It is not necessary to register for that to re-enable expansion.

If you're writing in Swift, you'll need to do this in Objective-C. Please see SMSwiftWorkarounds.h, SMSwiftWorkarounds.m, and TextExpanderDemoAppSwift-Bridging-Header.h in TextExpanderDemoAppSwift.xcodeproj for an example of how to do this.

Add TextExpander to Your Custom Keyboard or Other Extension

Your app which contains your extension ("containing app") will have to acquire snippet data from TextExpander (see Acquiring / Updating Snippet Data below).

Both your containing app and your extension will have to turn on the App Group capability in the Info section of their Xcode targets, and they'll have to share an identically named app group. You can see an example of this in the TextExpanderDemoApp project and its custom keyboard.

1. Import the TextExpander header into your view controller's header:<pre>#import "SMTEDelegateController.h"</pre>
2. Add an SMTEDelegateController to your view controller's subclass:<pre>@property (nonatomic, strong) SMTEDelegateController *textExpander;</pre>
3. In your view controller's viewDidLoad method, initialize SMTEDelegateController and set its appGroupIdentifier:<pre>self.textExpander = [[SMTEDelegateController alloc] init];<br>self.textExpander.appGroupIdentifier = @"<YOUR APP GROUP IDENTIFIER>";</pre>
4. Implement Acquiring / Updating Snippet Data in your containing app as described below

The TextExpander SDK will call [NSFileManager containerURLForSecurityApplicationGroupIdentifier:appGroupIdentifier] to obtain your app group container, and it will store and retrieve its snippet data from an appended path component of: Library/Application Support/TextExpander, creating the folders if necessary.

A custom keyboard won't use views and delegate methods. It will interact with TextExpander using:

<pre>[SMTEDelegateController stringByExpandingAbbreviations:stringToExpand cursorPosition:&cursorPosition options:expansionOptions];</pre>

This method extends the previous stringByExpandingAbbreviations: method by returning the index of the cursor in the expanded text when the user expands a snippet with cursor positioning.

The TextExpanderDemoApp includes a custom keyboard target, which serves as an example of how to support TextExpander in a custom keyboard. To add the custom keyboard to the demo app:

1. Select the TextExpanderDemoApp target, and in its Build Phases tab, add the DemoAppKeyboard as a Target dependency
2. In the TextExpanderDemoApp target, set the Code Signing Entitlements to TextExpanderDemoApp/TextExpanderDemoApp.Entitlements
3. On developer.apple.com, you'll need to do the following, but with your own IDs in place of our examples:

• Create an App Group (e.g. group.com.smileonmymac.textexpander.demoapp)
• Create an App ID (e.g. com.smileonmymac.TextExpanderDemoApp)
• Edit the App ID to add the App Group
• Create a Provisioning Profile for development, download it, and drag it to Xcode
• Create another App ID for the keyboard (e.g. com.smileonmymac.TextExpanderDemoApp.DemoAppKeyboard)
• Edit the App ID to add the App Group
• Create a Provisioning Profile for development, download it, and drag it to Xcode

4. Select the TextExpanderDemoApp target, and in its Capabilities tab, turn your App Group on, and check the appropriate Group
5. Select the DemoAppKeyboard target, and in its Capabilities tab, turn your App Group on, and check the appropriate Group
6. Select the TextExpanderDemoApp target, and in its Build Phases tab, add the DemoAppKeyboard to Embed App Extensions
7. Change the appGroupIdentifier setting in SMFirstViewController, SMSecondViewController, SMThirdViewController, and KeyboardViewController to match yours (search and replace @"group.com.smileonmymac.textexpander.demoapp")
8. Run the demo app, and update its snippets (so that they get written to the app group container)
9. Add your keyboard and do the test expansion in any app

Note: Snippet changes made in TextExpander touch are not automatically available to your custom keyboard. It gets its snippets from its container app, which uses the x-callback-url method described below to acquire and update snippet data.

Acquiring / Updating Snippet Data

To acquire / update snippet data, your app needs to:

1. Provide a URL scheme for getting snippets via x-callback-url:

   • Set the getSnippetsScheme property of the SMTEDelegateController
   • Add the scheme to your app's Info in Xcode under "URL Types"
   • Implement application:openURL:sourceApplication:annotation: or application:handleOpenURL: in your app delegate, and