Instant JChem Scripting

In IJC 5.4 initial scripting support was added. This functionality was experimental and incomplete. Improvements were made in each version since, and further improvements are planned. The current status should still be considered to be somewhat experimental. That said, scripting can and has been used for several purposes. Its main purpose is to allow easy extension of IJC - to make it do things it can't do out of the box, or to make things easier to perform.

Since the release the user has to have the ROLE_EDIT_SCRIPT assigned to be able to create a new script or edit an existing one. This allows the administrator to improve the database security. The user roles are described here .

What can be scripted?

Currently scripts can be run against a particular data tree or schema. This means that the data tree or schema is passed into the script context as a variable, and the script can operate on this item using the IJC API. This potentially provides a very powerful way to extend IJC, for example:

  • Performing complex operations not possible through the IJC user interface

  • Automating functions, simple and extensive

  • Accessing ChemAxon's extensive chemical language

  • Performing specialized or batch queries

  • Automating table populating

The developer's section has a library of example scripts, plugins, and scriptlets. These provide an excellent learning tool, and can be mixed and matched to suit your needs. Additionally, button widgets can be added to a form to run scripts on command.

The users scripting options are significantly improved with the new 5.11 version. Now a script can be executed after the double click event of several commonly used widgets. The script text can be edited in the code tab and can access table data. The widgets that are supported are: MolMatrix, MolPane, text area, text field and the table widget. An example use case is a custom input dialog with distinct predefined input values used for updating the the textual field in the database - it will modify the field to one of it's predefined values. Please follow the link to see the sample script with drop-down menu.

Another scripts can be performed during schema connection or disconnection ( Edit Schema -> Miscellaneous tab ).

What scripting language is used?

The language for the scripts is Groovy , a dynamic programming language that is closely linked to the Java language that most of IJC is written in. Groovy provides a powerful programming environment, but also a simple syntax that avoids some of the complexity of programming. Look at the documentation on the Groovy web site for more details. There are also some books available. For advanced usage you definitely need to understand Groovy, but for simple cases you should just be able to follow the examples described here.

We may support additional languages such as Python and JavaScript in future, but this is undecided. Because of its close alignment with the Java language that IJC is written in Groovy is generally going to be a better choice.

How to install and use a script

To install a script, right click on the schema or data tree node in the Projects window and choose 'New script'. You will be prompted for a name of the new Groovy script, and a very simple example script will open in the editor window. This script will be saved to a 'Scripts' folder under the schema or data tree. Simply delete the demo script and copy in an existing script to use it. If you do, pay close attention to where the script is located (data tree or schema). A script installed to the wrong location will not work. To edit or run an existing script locate the script in the Scripts folder and double click it to open it.

To run a script, click on the 'Run script' button in the editor toolbar (the first button). Any output from the script will be written to an output window.

If you want your script to run as a button in a form then add a button widget in design mode. One of the button's properties is the script. Edit this, and then in browse mode clicking on the button will execute the script.

As default, the scripts are user specific items which can be shared in a similar way as views, lists or queries. When shared, the script can be used also by other users that its owner.

Example scripts

The best way to learn how to use or write scripts is by starting with some examples. The developer's section has an extensive array of example scripts, scriptlets and plugins which can be used or tweaked for your own purposes. If you wish to learn more about writing scripts, please visit the developer's section for more detail.