IITC plugin migration guide - IITC-CE/ingress-intel-total-conversion GitHub Wiki

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

Comm API

Introduced in IITC-CE v0.39.0

The introduction of the IITC.comm API primarily aims at enhancing support and simplifying the codebase. The previous window.chat namespace has been divided into two segments: the chat interface and tab management remains under window.chat, while functionalities related to in-chat messages have been migrated to the IITC.comm API.

To ensure backward compatibility, a proxy has been implemented that redirects calls from the deprecated window.chat functions to the new IITC.comm. Note that if a plugin overrides a deprecated window.chat function, it is automatically overridden in IITC.comm as well. This ensures that plugins work in most cases but may introduce issues due to the use of outdated code.

Changes to window.chat functions and variables

  • Removed:

    • window.chat._oldBBox
    • window.chat.handlePublic, window.chat.handleFaction, window.chat.handleAlerts
    • window.chat._requestPublicRunning, window.chat._requestFactionRunning, window.chat._requestAlertsRunning

  • Deprecated:

    • window.chat.tabToChannel
    • Use IITC.comm.renderMsgRow instead of window.chat.renderMsg
    • Use IITC.comm._channelsData.all, IITC.comm._channelsData.faction, and IITC.comm._channelsData.alerts instead of window.chat._public, window.chat._faction, and window.chat._alerts

  • Replacements and recommendations:

    • Use IITC.comm.requestChannel instead of window.chat.requestPublic, window.chat.requestFaction, window.chat.requestAlerts
    • Use IITC.comm.renderChannel instead of window.chat.renderPublic, window.chat.renderFaction, window.chat.renderAlerts
    • Internal methods like window.chat.genPostData and window.chat.writeDataToHash moved to IITC.comm and are available for backward compatibility only

  • Moved functions

    • window.chat.parseMsgData - moved to IITC.comm.parseMsgData
    • window.chat.renderText - moved to IITC.comm.renderText
    • window.chat.getChatPortalName - moved to IITC.comm.getChatPortalName
    • window.chat.renderFactionEnt - moved to IITC.comm.renderFactionEnt
    • window.chat.renderPlayer - moved to IITC.comm.renderPlayer
    • window.chat.renderMarkupEntity - moved to IITC.comm.renderMarkupEntity
    • window.chat.renderMarkup - moved to IITC.comm.renderMarkup
    • window.chat.renderData - moved to IITC.comm.renderData
    • window.chat.renderPortal - moved to IITC.comm.renderPortal, with customizable string template
    • window.chat.renderTimeCell - moved to IITC.comm.renderTimeCell, with customizable string template
    • window.chat.renderNickCell - moved to IITC.comm.renderNickCell, with customizable string template
    • window.chat.renderMsgCell - moved to IITC.comm.renderMsgCell, with customizable string template
    • window.chat.renderMsgRow - moved to IITC.comm.renderMsgRow, with customizable string template
    • window.chat.renderDivider - moved to IITC.comm.renderDivider, with customizable string template

Changed channel names

Channel names now start with a capital letter (e.g. All instead of all). If your plugin adds new chat tabs after some tab (e.g. after all), it is recommended to use data-channel key instead of searching by name.

For example, instead of

[...document.querySelectorAll('#chatcontrols a')].filter(el=>el.textContent == 'all')

use

[...document.querySelectorAll('#chatcontrols a')].filter(el=>el.dataset.channel == 'all')

IITC.comm.requestChannel replaces specific channel requests

The IITC.comm.requestChannel function has been introduced to replace separate functions for each channel. For instance, instead of using window.chat.requestPublic(getOlderMsgs, isRetry), use IITC.comm.requestChannel('all', getOlderMsgs, isRetry)

IITC.comm.renderChannel replaces specific channel renders

Similarly, the IITC.comm.renderChannel function is introduced to replace separate rendering functions. For example, instead of window.chat.renderPublic(oldMsgsWereAdded), use IITC.comm.renderChannel('all', oldMsgsWereAdded)

Customizable string templates

It is now possible to edit or replace the template strings used by certain functions:

  • IITC.comm.renderPortal - template string in IITC.comm.portalTemplate
  • IITC.comm.renderTimeCell - template string in IITC.comm.timeCellTemplate
  • IITC.comm.renderNickCell - template string in IITC.comm.nickCellTemplate
  • IITC.comm.renderMsgCell - template string in IITC.comm.msgCellTemplate
  • IITC.comm.renderMsgRow - template string in IITC.comm.msgRowTemplate
  • IITC.comm.renderDivider - template string in IITC.comm.dividerTemplate

Hooks

While the old hooks (publicChatDataAvailable, factionChatDataAvailable, and alertsChatDataAvailable) remain, a new, more general hook, commDataAvailable, has been added. This hook functions similarly but also includes a channel key indicating the channel.

For more details, see the documentation: IITC.comm Documentation

Declarative message filter

The IITC.comm.declarativeMessageFilter allows for message filtering within channels, such as hiding messages from players based on a pattern or displaying only selected actions (e.g., deploying portals, creating fields).

Example Usage: To hide all messages except those from the Resistance team:

IITC.comm.declarativeMessageFilter.addRule({
  id: "hideExceptResistanceTeam",
  conditions: [
    { field: "player.team", value: "Resistance", invert: true },
  ]
});

For more details, see the documentation: IITC.comm Declarative Message Filter

Utils API

Planned to be implemented in IITC-CE v0.40.0

The IITC.utils API, introduced in IITC-CE v0.40.0, centralizes utility functions to improve code organization and simplify API interactions. Previously located in the window. namespace, these helper functions now reside in IITC.utils, with some functions renamed for clarity.

For legacy support, IITC intercepts old window. function calls, redirecting them to the new IITC.utils equivalents. This helps maintain plugin compatibility; however, updating code to use the new references is recommended for clarity and future support.

Changes to window. Functions and Variables

  • Deprecated:

    • Use IITC.utils.getTeamId instead of window.getTeam

  • Moved to IITC.utils without renaming:

    • window.getURLParam - moved to IITC.utils.getURLParam
    • window.zeroPad - moved to IITC.utils.zeroPad
    • window.unixTimeToString - moved to IITC.utils.unixTimeToString
    • window.unixTimeToDateTimeString - moved to IITC.utils.unixTimeToDateTimeString
    • window.unixTimeToHHmm - moved to IITC.utils.unixTimeToHHmm
    • window.formatInterval - moved to IITC.utils.formatInterval
    • window.formatDistance - moved to IITC.utils.formatDistance
    • window.isTouchDevice - moved to IITC.utils.isTouchDevice
    • window.scrollBottom - moved to IITC.utils.scrollBottom
    • window.prettyEnergy - moved to IITC.utils.prettyEnergy
    • window.uniqueArray - moved to IITC.utils.uniqueArray
    • window.genFourColumnTable - moved to IITC.utils.genFourColumnTable
    • window.clamp - moved to IITC.utils.clamp
    • window.clampLatLng - moved to IITC.utils.clampLatLng
    • window.clampLatLngBounds - moved to IITC.utils.clampLatLngBounds

  • Moved to IITC.utils with renaming:

    • window.readCookie - renamed and moved to IITC.utils.getCookie
    • window.writeCookie - renamed and moved to IITC.utils.setCookie
    • window.eraseCookie - renamed and moved to IITC.utils.deleteCookie
    • window.digits - renamed and moved to IITC.utils.formatNumber
    • window.pnpoly - renamed and moved to IITC.utils.isPointInPolygon
    • window.escapeJavascriptString - moved to IITC.utils.escapeJS
    • window.escapeHtmlSpecialChars - moved to IITC.utils.escapeHtml
    • window.convertTextToTableMagic - moved to IITC.utils.textToTable
    • window.teamStringToId - moved to IITC.utils.getTeamId

Search API

Planned to be implemented in IITC-CE v0.40.0

The IITC.search API modernizes IITC's search functionality by moving it from the window.search namespace to IITC.search. This updated API is now modular, separating logic and UI and eliminating jQuery dependencies. Key updates for plugin developers include replacing window.search.addSearchResult with query.addPortalResult and using IITC.search instead of window.search (e.g., IITC.search.lastSearch).

Backward compatibility is maintained, but using the new IITC.search structure is recommended for future support and clarity.

The new API consists of:

  • IITC.search for core search functions,
  • IITC.search.Query for search query handling, and
  • IITC.search.QueryResultsView for displaying results.