--[[ File
NAME: DocTitanPlugin.lua
DESC: This file contains documentation of Titan to assist a developer.
:DESC
--]]
--[[ API
NAME: Titan API overview for developers
DESC: Updated Feb 2024

This documentation is intended for addon developers that wish to create a Titan plugin.

Terms:
Throughout the documentation and naming of routines and variables there are some terms that are used interchangably.
- Plugin / button which are frames using TitanTemplates.xml
- Character / player / toon
- Plugin ID / plugin name
Over time we desire to consolidate terms but it may take time.

Plugin Types:
Titan allows two types of plugins:
- Titan native
- LDB enabled addons
Titan release has an example of each : TitanExamplePlugin and TitanExampleLDB.

Titan Plugin Creation:
Titan native plugins must use one of the Titan templates found in TitanPanelTemplates.xml.
On the creation of a Titan plugin frame the Onload places the plugin in a holding table until the "Player Entering World" (PEW) event is fired.

LDB Plugin Creation:
LDB enabled addons only need to adhere to the LDB (Lib Data Broker) 1.1 spec.
Titan uses the callback feature ("LibDataBroker_DataObjectCreated") to recognize LDB addons.
Titan creates a Titan plugin using the LDB plugin data.
At player_login Titan registers the call back.
It then loops through the LDB objects using :DataObjectIterator().
When any LDB object is found Titan will attempt to create a Titan native plugin for display.

Registration Steps:
On PLAYER_LOGIN event, Titan loops through the holding LDB plugins creating Titan plugins. It will sync the saved variables.
On PLAYER_ENTERING_WORLD (PEW) event, Titan loops through the holding table registering plugins. It will sync the saved variables.
Titan attempts to register each plugin ensuring:
- Each attempt is protected (pcall) so Titan does not crash (hopefully!)
- The .registry has required values and is reasonable.
- Sync of control and saved variables.
- All attempts are recorded. These can be seen in Titan Config > Attempts

Registration Attempts:
Each attempt can be seen in Titan Config > Attempts with the results of the registration. The developer can see what happened and users can report issues using that data.

Registry Table of Each Plugin:
Each plugin must contain a table called "registry".
   self.registry = {}

The registry table must have a unique id across all Titan plugins that are loaded.
   self.registry = {id = "MyPlugin"}
This is all that is required for successful registration. It will register but will be a rather dull plugin.
It is strongly recommended that you utilize the Titan plugin example. The example is based on TitanBags so you can play with the code and compare it to a supported plugin.

Titan API:
Within the Titan files you can recognize an API routine by the comment just before the function declaration. The comment block will have "API" as part of the starting block.
:DESC
--]]