While the design and structure of the addons system in ILLiad, Ares, and Aeon may allow for access to additional private functionality within the application, Atlas Systems limits access to only the public application programming interfaces listed in the Atlas documentation as part of this Addon Technical Details documentation.

Access to other functionality may be added in the future. If you are interested in working on addons that need access to undocumented functionality, please contact addons@atlas-sys.com with the details and requirements.

Creating or using addons that access private functionality may cause problems with existing features and/or future updates. Systems errors created as a result of running these addons may not be supported by Atlas or OCLC staff.

Addon Folder Structure

The Addon system follows a simple one folder per addon structure. Each addon should have a separate folder in the Addons directory. This folder is referred to as the base folder for the addon, and it should have a unique name that is descriptive of the addon it contains. Inside the base folder for each addon should be at the minimum one configuration file named config.xml and one Lua script file. The directory structure inside the addon folder can be designed in whatever way makes management and maintenance of the addon easiest. The only limitation is that the config.xml file be in the addon's base folder. This same folder structure should be used for addons stored on a shared server, substituting the directory defined by the "AddonDirectory" key for the "Addons" directory.

Lua Files

Each addon should have at least one Lua file. Lua files are plain text files with a .lua extension that contain the script text for an addon. The script text for a single addon can be divided into as many Lua files as desired for easier management and maintenance of the addon. Regardless of how many Lua files are used for an addon, all of the files must be included in the files list in the addon's config.xml file in order to be automatically included when the addon is loaded.

Config.xml

The config.xml file required for all addons contains the basic descriptive information required to make the addon run properly. In the config.xml file, a number of values such as Name, author, version, settings, files, and associated forms are defined. The elements allowed in the configuration file and what they do are as follows:

Name: The name of the addon. This should be unique between addons.
Author: The name of the person or organization responsible for the creation and maintenance of the addon.
Version: The current version of the addon. This is vital for allowing automatic downloads of updated scripts from a network share. The only time an existing addon will be replaced on a local machine by a script from a server share is if the version number in the configuration file of the server share version is higher than that of the local version.
Active: This determines whether or not the addon should be loaded into the system. Inactive addons may still be downloaded from server shares.
Description: A description of the addon's purpose.
Forms: A list of Form elements which define the names of the forms in ILLiad that the addon should be loaded on. Currently, the only form supported is FormRequest.
Settings: A list of setting elements that define the name, default value, type, and description of all settings used by the addon. Descriptions of these elements can be found below.
Files: A list of File elements which define the location of each file that should be automatically included when the addon is loaded. There must be at least one file listed for all addons, and one of the files listed must contain a function named Init(), which will be called when the addon loads. The entries may be either rooted (full path) or relative to the config.xml file; for files in the same folder as the config.xml file, only thefile name is necessary.

The following attributes and elements are required for each Setting element in the file:

Name (Attribute): The name that will be used for referencing the setting in the Manage Addons interface and when calling the GetSetting method in the addon's script files.
Value (Attribute): The default value of the setting.
Type (Attribute): The data typefor the setting. Allowed types include string, boolean, and number.
Description (Element): A brief description of the setting's purpose.

Local Settings

In addition to the default settings for an addon, which can be defined in the settings section of the addon's configuration file, users are able to modify the value of each setting in a given addon. These values are then persisted as Local Settings. Once they have been changed, they are saved to a joint Local Settings file (shared by all addons) named LocalSettings.xml, which is independent of the addon's config.xmlfile and is stored in the "Addons" folder on the client machine. This allows addons to be easily updated by simply replacing the entire folder without having to worry about losing your local settings. It also enables users to easily copy the LocalSettings.xml file to other machines in order to easily distribute custom settings.