Custom Gateway Scripts Autocomplete and Documentation

Module Development
,
1

I'm developing a custom gateway module using Java which provides custom scripting modules in the Gateway context. The scripting modules and their functions are working, but I have a couple of problems:

  1. The documentation I’ve written isn't loading. Instead of seeing my descriptions,
    I'm getting question marks like ¿MyScripting.myMethod.param.paramName?
  2. Top-level methods and classes auto-complete, but instance methods of classes don’t seem to auto-complete or have any hints at all.

What I've Implemented:
I want to provide a fluent interface to construct complex objects using a Builder pattern. For example, this ExampleMethod can be called directly with 3 arguments, or you can build an ExampleConfig line by line by calling the with methods, then pass that object to the ExampleMethod:

import com.inductiveautomation.ignition.common.script.hints.ScriptArg;
import com.inductiveautomation.ignition.common.script.hints.ScriptFunction;

public final class ExampleScripting {
  @ScriptFunction(docBundlePrefix = "ExampleScripting")
  public boolean exampleMethod(
      @ScriptArg("exampleString") String exampleString,
      @ScriptArg("exampleInteger") int exampleInteger,
      @ScriptArg("exampleBoolean") boolean exampleBoolean) {
    return true;
  }

  @ScriptFunction(docBundlePrefix = "ExampleScripting")
  public boolean exampleMethod(@ScriptArg("config") ExampleConfig config) {
    return exampleMethod(config.exampleString(), config.exampleInteger(), config.exampleBoolean());
  }

  @ScriptFunction(docBundlePrefix = "ExampleScripting")
  public ExampleBuilder exampleBuilder() {
    return new ExampleBuilder();
  }

  public static final class ExampleBuilder {
    private String exampleString = "";
    private int exampleInteger;
    private boolean exampleBoolean;

    public ExampleBuilder withExampleString(@ScriptArg("exampleString") String exampleString) {
      this.exampleString = exampleString;
      return this;
    }

    public ExampleBuilder withExampleInteger(@ScriptArg("exampleInteger") int exampleInteger) {
      this.exampleInteger = exampleInteger;
      return this;
    }

    public ExampleBuilder withExampleBoolean(@ScriptArg("exampleBoolean") boolean exampleBoolean) {
      this.exampleBoolean = exampleBoolean;
      return this;
    }

    public ExampleConfig build() {
      return new ExampleConfig(exampleString, exampleInteger, exampleBoolean);
    }
  }

  public record ExampleConfig(String exampleString, int exampleInteger, boolean exampleBoolean) {}
}

This builder interface has readability and usability benefits over a long list of method arguments for constructing complex objects. However, when writing a script which calls these methods in the Scripting Editor (Designer > Tag Browser > Any Tag > Scripting > Value Change > Script), I run into the two issues mentioned above:

  1. The documentation pop-up doesn’t show the custom documentation I’ve written. It shows:

exampleMethod(

exampleString: String
exampleInteger: int
exampleBoolean: boolean

)

Method on Ignition.custom.example

null

Returns:

  • No return value.

Parameters

  • exampleString: String

    • ¿ExampleScripting.exampleMethod.param.exampleString?

  • exampleInteger: int

    • ¿ExampleScripting.exampleMethod.param.exampleInteger?

  • exampleBoolean: boolean

    • ¿ExampleScripting.exampleMethod.param.exampleBoolean?

I have an ExampleScripting.properties file located in src/main/resources/, which documents each method and parameter like this:

Method.desc=Example method demonstrating basic parameter types
myMethod.param.exampleString=A string parameter for demonstration purposes
myMethod.param.exampleInteger=An integer parameter for demonstration purposes
myMethod.param.exampleBoolean=A boolean parameter for demonstration purposes
myMethod.returns=Always returns true for demonstration purposes

In my GatewayHook.java file, I add the script module as follows:

@Override
public void initializeScriptManager(ScriptManager manager) {
super.initializeScriptManager(manager);

manager.addScriptModule(
    "system.custom.example",
    new ExampleScripting(),
    new PropertiesFileDocProvider());
}

But I’m not seeing this method description, parameter descriptions, or return types in the documentation pop-up. The documentation DOES show the method and parameter names and types - Where is it getting this information? How can I properly implement custom documentation for my scripting methods?

And problem 2: I get autocomplete hints for system.custom.example.exampleBuilder(), but after that, I get no hints for which methods are available on the ExampleBuilder object that exampleBuilder() returns. I’d like to see a pop-up appear with autocomplete options for withExampleString, withExampleInteger, withExampleBoolean, and build, so that script writers can see exactly which options are available - but I get no autocomplete hints at all. Is this a limitation of the system, or something I’m not implementing correctly?

Any insight into this would be highly appreciated! I’ve looked through the documentation and tutorials, and can’t seem to find where I’ve gone wrong. Thank you!

2

You need to load your properties file with BundleUtil.

Ignition's system. scripting namespace doesn't support documenting nested class methods.

1 Like