IITC plugin migration guide

This guide provides step-by-step instructions on migrating existing IITC plugins to the new IITC API, introduced to replace previous internal window.* namespace functions with a more powerful and user-friendly IITC.* namespace.

Best Practices

1. Checking for API Availability: Instead of checking the IITC build date or version to determine if a certain API is available, check for the existence of the method itself.

   Bad Practice:

   if (iitcBuildDate <= '2023-11-20-071719') { /* ... */ }

   Good Practice:

   if (typeof IITC !== 'undefined' && typeof IITC.toolbox !== 'undefined') { /* ... */ }

2. Avoid Overwriting or Modifying API Methods: If the existing API does not meet your requirements, instead of modifying or overwriting the API methods, submit an issue requesting the needed functionality. This ensures the future compatibility of your plugin with API updates and improves compatibility with other plugins.

IITC API Overview

Filters API

Introduced in IITC-CE v0.38.0

The Filters API allows hiding intel entities based on their properties (e.g., faction, health, timestamp). It provides a two-level API: a set of named filters that apply globally and a low-level API for generic purposes.

Example Usage:

{ portal: true, data:  ['not', { history: { scoutControlled: false }, ornaments: ['some', 'sc5_p'] }] }

This filter configuration hides all portals except those never scout controlled and having a scout volatile ornament.

Documentation: Filters API Documentation

Toolbox API

Introduced in IITC-CE v0.38.0

The Toolbox API facilitates the management of plugin buttons in the toolbox, allowing for the addition, editing, deletion of buttons, and sorting order modification.

Example Replacement: Instead of directly manipulating the DOM to add buttons:

$('#toolbox').append('<a onclick="window.plugin.myplugin.openDialog(); return false;">Test Button</a>');

Use the Toolbox API like this:

IITC.toolbox.addButton({
  id: 'mybtn',
  label: 'Test Button',
  action: window.plugin.myplugin.openDialog
});

Documentation: Toolbox API Documentation