PhotoGrok is customizable using a JavaScript API.


Update: Version 2.80

PhotoGrok can now run two different graal script engines. The newer
"graaljs" uses the Context-based API. "graal.js" uses a ScriptEngine
API. Both implementations report script_engine_name as "graal.js".
The graal engines require graal.js to be installed. Ther is a standalone
PhotoGrok install which includes the more modern and performant graal.js.

A folder named "plugins" is included. The scripts there follow
the PhotoGrok plugin standard and work in Rhino, Nashorn and graal.js.
See below for information on loading the plugins.

PhotoGrok now loads the included plugins by default in new installations.
Comment out or remove the related code in the script editor if you do
not want these plugins (you can also edit defaults.js to include just
the plugins you want).

To load the plugins for existing scripts, open the script editor with
CTRL+SHIFT+J and enter the following code (adjust for correct paths):

load('path to defaults.js'); // located in plugins directory by default
var ds = new DefaultSetup('path to plugins folder');
ds.init();

In 2.80, the default script engine is selected in the following order when
not specified in the top-level script: graal.js, nashorn, rhino.
The "jdkrhino" engine has been removed. Any Java 6 or 7 users should use
included "rhino" engine.

*************************************************************************


OVERVIEW

Some of the example scripts might need modification to run in Java 6
or Java 7. Java 8 and above is highly recommended for performance reasons.

Included scripts may need to be modified to suit your environment.
Please read the comments for specifics. Not all scripts will run in 
earlier versions of PhotoGrok.

To try one of the example scripts, simply copy all of the text into the
script editor which can be opened with CTRL+SHIFT+J or from the Tools menu.
The entire script can be loaded in the editor using the load() mechanism
and either a file path or url. Example: 

load('plugin_path/jhfilters.js');

When using this mechanism, pre-processing directives (see below) must be
added outside of the load call in the top-level script.

Scripts share the same scope with tree filters and custom tags. Tree filters
are particularly useful as the filter is called for every image/file as the
tree is created. Example scripts requiring a custom JavaScript filter will
describe the requirement in the header comments.



SCRIPT PRE-PROCESSOR ANNOTATIONS

Annotations must appear on a comment line in the top-level script to be
recognized.

@nashornopts 

By default, nashorn scripts (Java 8 and above) run with optimistic typing
and nashorn's scripting enhancements. Some scripts may run better with
different or additional options. If this annotation appears, it completely
overrides the defaults. Examples:

// mimick the defaults, optimistic types set to true with scripting
// @nashornopts -ot=true,-scripting

// turn off optimistic types, use a persistent disk cache for scripts
// and turn off lazy compilation
// @nashornopts -ot=false,-pcc,-scripting,--lazy-compilation=false

See the nashorn documentation for other useful options.

@graalopts

Scripts using // @scriptengine graaljs or // @scriptengine graal.js
can use @graalopts to configure the engines.

// @graalopts js.nashorn-compat=false,js.ecmascript-version=2023

See notes below about running graal.js at the bottom of this
document. See the graal.js documentation for more potentially useful
options.

@rhinoopts

This directive provides two options to configure the rhino script
engine. "-optLevel" can range -1 to 9. -1 is interpretive mode. 0 is 
no optimizations and 1 through 9 are varying levels of optimization. 
"-defaultLang" sets the version of the JavaScript language. 
180 is 1.8, 170 is 1.7 and so forth. See Rhino documentation for more
details on these settings.

// @rhinoopts -optLevel=9,defaultLang=180


@threadsafe

True by default. The threadsafe annotation can be used if a script is not
thread safe. In PhotoGrok, this usually means a painter which doesn't render
correctly on the thumbnail screen. When set to false, only one thread is
used to draw thumbnails. Example:

// @threadsafe false

Please note that graal.js always runs in threadsafe false mode due to it's
threading model.

@scriptengine

Choose the JavaScript engine. On Java 8 and above you can choose either
Rhino, Nashorn or graal.js when available. Java 6 & 7 users can use 
Mozilla Rhino or the version of Rhino included in the JVM. Mozilla rhino
allows more features than rhino in the jdk and is likely more performant.
Examples - @scriptengine must be commented in the top-level script:

// all versions of java can use mozilla rhino
// @scriptengine rhino

or

// all versions java 8+ can now use the included nashorn (default on those
// platforms)
// @scriptengine nashorn

or

// only java 6 and 7 can use jdkrhino (the default on those systems)
// @scriptengine jdkrhino

or

// java 8 and above can be configured to use the graal.js engine
// using Java's ScriptEngine API when graal.js is available.
// @scriptengine graal.js

or

// java 8 and above can be configured to use the graal.js engine
// using Context API when graal.js is available.
// @scriptengine graaljs

 
***************************************************************************

Running "// @scriptengine graaljs"

You may have to adjust existing scripts/plugins to make them work with this
scripting engine as nashorn compatibility mode is off by default. You can
turn on compatibility mode in your top-level script:

// @graalopts js.nashorn-compat=true

In this case however, you may lose the ability to use the latest JavaScript
language features. 

All PhotoGrok plugins have been updated to work in this engine (as well as in
Rhino and Nashorn). If your existing script is failing, you may consider
examining the source for these plugins before turning on compatibility mode.

You can choose the language specification:

// @graalopts js.ecmascript-version=2023
or
// @graalopts js.ecmascript-version=2022
or
// @graalopts js.ecmascript-version=2021

Multiple @graalopts must appear on the same commented line delimited by commas:

// @graalopts js.webassembly=true,js.ecmascript-version=2023

See https://www.graalvm.org/latest/reference-manual/js/Options/


