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.

Not much is required for most plugins to support Textual 6. Ensuring code points to renamed methods and properties is usually all that is required. Some plugins, such as those requiring access to Webkit, will require more work.

Compatibility

Before a plugin can be loaded, it must first state that it's 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: