Jinx Settings

[JINX]
classes = Comma or new line delimited list of classes to load.
error_handler = How to deal with errors.
developer_mode = When enabled (default) the developer tools are added to the Jinx menu.
external_config = Paths of additional config files to load.
startup_script = Path or URL of startup script.
ribbon_xml_file = Filename of ribbon XML file to load.
ribbon_xml_resource = Resource name of ribbon XML to load.
shadow_path = Optional path to use for copying anything on the class path to before loading.
reload_exclude = Optional list of classes (or wildcards) to exclude when reloading.
reload_include = Optional list of classes (or wildchads) to include when reloading.

classes

When Jinx starts it loads each classes listed and scans them for Jinx annotations. Annotated methods are registered as Excel functions.

These classes must be available on the classpath (set in the Java section of the config file).

error_handler

This may be set to one of:

• default
• quiet
• none
• a customer error handler class

See Error Handling for details.

developer_mode

Enabled (1) by default. When enabled the developer tools are added to the Jinx menu on the Add-Ins Excel toolbar. If the Add-Ins toolbar isn’t visible it can be added by right clicking on the ribbon and going to Customize.

The developer tools include reloading the Jinx add-in for testing and developing without restarting Excel, and opening the log file.

When deploying to end users who do not need this functionality developer_mode can be set to 0.

external_config

This setting may be used to reference another config file (or files) located elsewhere.

For example, if you want to have the main jinx.ini installed on users’ local PCs but want to control the configuration via a shared file on the network or URL you can use this to reference that external config file.

Multiple external config files can be used by setting this value to a list of file names (comma or newline separated) or file patterns.

Values in external config files override what’s in the parent config file, apart from pythonpath, modules and external_config which get appended to.

In addition to setting this in the config file, the environment variable JINX_EXTERNAL_CONFIG_FILE can be used. Any external configs set by this environment variable will be added to those specified in the config.

startup_script

Path or URL of a batch or Powershell script to run when Excel starts.

This script will be run when Excel starts, but before Java is initialized. This is so that the script can install anything required by the add-in on demand when Excel runs.

See startup script for more details.

ribbon_xml_file

Filename of a ribbon XML file to load. This may be an absolute path, or a path relative to the config file.

See Ribbon Toolbars for more details.

ribbon_xml_resource

Resource name of a ribbon XML file to load. The JAR containing the resource must be on the class path.

See Ribbon Toolbars for more details.

shadow_path

If set, anything on the class_path will be copied to a unique folder under this path before loading any classes. These copies will be cleaned up when no longer needed automatically.

This is useful as when classes are loaded the class loader keeps the jar file open, which prevents other applications from overwriting or deleting them. While developing it is common to recompile code while keeping Excel open and then using Jinx’s reload feature to load the updated classes, and so by copying the jars before loading this ensures that the originals can be overwritten.

If deploying code to a network drive this can also be helpful so that those files can be updated while users still have Excel open.

reload_exclude

When reloading Jinx, the class loader that was used previously to load all the classes is replaced with a new class loader. This means that all the classes will be loaded again into the new class loader and this is how Jinx is able to reload user code without restarting Excel.

Some classes do not work if loaded twice. This can be because some part of their implementation is written as a native library and that part does not get re-initialized when the Java classes are reloaded.

The reload_exlcude setting is a comma (or new-line) separated list of classes (or wildcards, e.g. com.microsoft.sqlserver.jdbc.*) that will never be reloaded. Instead, these classes are loaded by a different class loader that is not replaced until Excel restarts.

reload_include

Instead of including certain classes from being reloaded, if reload_include is set only those classes listed will be reloaded when reloading Jinx.

The reload_include setting is a comma (or new-line) separated list of classes (or wildcards, e.g. com.yourcompany.*) that will be included when reloading.

reload_include and reload_exclude can be combined. In the case a class matches both reload_exclude and reload_include, the one that more specifically matches the class will be used. For example, if com.a.* was excluded and com.a.b.* was included, then all classes in the package com.a would be excluded except for any classes in the package com.a.b.