Plugin migration to Textual 6

Plugin Developers: Migrating to 6.0.0

Introduction

The codebase of Textual was modified significantly in version 6.0.0. Many classes are no longer public. Others are now immutable by default. Some methods and properties have been removed or renamed.

Because of this, to prevent crashes, Textual 6 will refuse to load any plugins that were built against Textual 5.

For the vast majority of plugins, little work will need to be done. Ensuring code references renamed methods and properties is typically all that is required. Some plugins, such as those that access Webkit, will require more work.

Compatibility

Before a plugin can be loaded, it must first state that it is compatible with Textual 6.

This can be accomplished by adding the following entry to the plugin's Info.plist file:

  <key>MinimumTextualVersion</key>
  <string>6.0.0</string>

Nullability

Textual's codebase is now non-nil by default, unless stated otherwise by a declaration of nullable or _Nullable. Methods and properties that are non-nil now throw an exception if nil input is given.

Accessing the Document Object Model (DOM)

In Textual 6, the DOM can only be accessed by evaluating JavaScript code.

TVCLogView exposes several methods to make this as pain-free as possible.

Evaluating a Function

The following methods can be used to evaluate a named function:

Arguments

function

The name of a function which already exists in the WebView

arguments

An array of arguments to send this function

completionHandler

A block that is performed when a result is returned

Methods

- (void)evaluateFunction:(NSString *)function;

- (void)evaluateFunction:(NSString *)function
           withArguments:(nullable NSArray *)arguments;

- (void)evaluateFunction:(NSString *)function
           withArguments:(nullable NSArray *)arguments
       completionHandler:(void (^ _Nullable)(id _Nullable result))completionHandler;

Discussion

An argument can be NSArray, NSDictionary, NSNull, NSNumber, or NSString.

Arguments can be nested. For example, an NSDictionary can contain multiple NSArray objects.

An unknown argument type, such as a custom class, is treated as undefined.

Examples

The following Objective-C code:

TVCLogView *webView = mainWindow().selectedItem.viewController.backingView;

NSString *remoteScriptURL = @"https://www.example.com/scripts/a.js";

[webView evaluateFunction:@"Textual.includeScriptResourceFile"
            withArguments:@[remoteScriptURL]];

Results in the following JavaScript code:

Textual.includeScriptResourceFile("https://www.example.com/scripts/a.js");

Evaluating Arbitrary Code

The following methods can be used to evaluate JavaScript code:

Methods

- (void)evaluateJavaScript:(NSString *)code;
- (void)evaluateJavaScript:(NSString *)code
         completionHandler:(void (^ _Nullable)(id _Nullable result))completionHandler;

Examples

TVCLogView *webView = mainWindow().selectedItem.viewController.backingView;

NSString *code = @"for (var i = 0; i < 100; i++) console.log(i)";

[webView evaluateJavaScript:code];

Communicating with Plugin

A plugin that injects JavaScript into the DOM can have that JavaScript send payloads back to the plugin at any time using the function: app.sendPluginPayload(payloadLabel, payloadContent)

payloadLabel is a string that describes the payload and payloadContent is the payload itself. The payload can be any type that JavaScript supports. It will be automatically translated to the appropriate Objective-C or Swift type.

The payload is sent to all plugins that declare the method –didReceiveJavaScriptPayload:fromViewController: