Agile Tortoise

← Back to Developers

If you implement, or plan on implementing, Terminology integration in your app, please drop us a line and let us know, we’d be happy to help.

Terminology on both iPhone and iPad provides support for integration with other apps via the x-callback-url protocol. Two methods are provided, one for simple word lookup and one allowing the user to select an alternate word and pass it back to your app. Terminology registers the “terminology://” URL schema. For more information on implementation, visit the x-callback-url website.

x-callback-url Actions

/lookup

  • Action: lookup
  • Parameters:
    • text [string, required] : The text to lookup. Can be a single word, or a text selection.
    • x-source [string, optional] : A friendly name for the app making the call. It will be displayed to the user to identify the request.
    • x-success [string, optional] : The URL to use to return the user to the calling application. If provided, the user will get a dialog to allow them to easily return to the calling app after viewing the definition.
  • Description: Calling this action with the required “text” parameter will launch Terminology and lookup the text, just as if the user had searched for and selected the text from inside Terminology.
  • Example URL, lookup the word “white”:
    • terminology://x-callback-url/lookup?text=white
  • Example URL, lookup the phrase “a good deal”:
    • terminology://x-callback-url/lookup?text=a%20good%20deal

/replace

  • Action: replace
  • Parameters:
    • text [string, required] : The text to lookup. Can be a single word, or a text selection.
      • x-source [string, required] : A friendly name for the app making the call. It will be displayed to the user to identify the request.
      • x-success [string, required] : The URL to use to return the user to the calling application when a replacement word has been selected.
      • x-cancel [string, optional] : The URL to use to return the user to the calling application, in the case where the user request cancellation of the action. If not provided, “cancel” will remain in Terminology.
  • Description: Calling this action with the required “text” parameter will launch Terminology and lookup the text, just as if the user had searched for and selected the text from inside Terminology. The user can then browse in Terminology for synonyms, antonyms or completely different words. An action dialog will be presented near the bottom of the screen, which allows the user to cancel and continue to browse in Terminology, or select “Send to App” (value from the x-source parameter is used for the App name if provided) which will call the URL in the x-success parameter with two additional parameters added: “text” (the original text sent to Terminology) and “replaceWith” (this select word). The intention is that the originating app would then substitute the value from “text” parameter with the value in the “replaceWith” parameter.
  • Example URL, request a replacement fo the word “white”:
    • terminology://x-callback-url/replace?text=white&
      x-source=MyAppName&
      x-success=myappurl://x-callback-url/returnAction