UI HTML Extraction

Purpose

This project externalizes a number of items in the PCGen UI into something that is outside the code.

This WILL require some discussion with members of the team (code, data, and output, release).

Reasoning

We are moving this out of the code because they are closely tied to the data. By moving them out, we can accomplish a number of things:

1. Have different display in different game modes, depending on the content of an item
2. Have the display be able to be updated when data changes are made, rather than requiring code/data co-dependence
3. Leverage a common system for output
4. Prepare for a future UI change by extracting behavior that will be needed regardless of the presentation location

Process

Right now the vast majority of our items that are text descriptions in the UI (info about an object that is clicked on) are done from an InfoFactory, specifically Gui2InfoFactory. This will replace the behavior in those methods.

These items should be converted one at a time, so code reviews can be done in between each item, so that we know certain automation (macros, etc) are being appropriately produced. (This isn't to say we won't discover things later, but let's catch what we can by inspection).

Success

This includes:

1. The HTML elements are externalized from Gui2InfoFactory
2. The HTML is processed through FreeMarker before it is written into the UI
   1. Place the Freemarker processing into pcgen.io for now - probably into a new class.
   2. Please reuse your freemarker.template.Configuration.
   3. Consider reusing the freemarker.template.Template objects - if you don't, have a reasoning for why not.
3. All of the getHTMLInfo methods that build HTML are modified and have the source HTML extraced to external files.
   1. Note: After those methods are complete, it can be evaluated what other methods it is valuable to extract as a "Phase 2".
   2. Note: Communication with the release team will be necessary to make sure these files are included in the release
4. For purposes of this project the *Facade objects should not be used during export. If you look at how the wrappers in pcgen.output work, the UI Facades are not used, so pass in a "real" object to the output system when building the Map (or whatever style you use).
5. You SHOULD be writing Freemarker macros, and it's okay to require importing of some macro files at the top of the HTML files.
   1. Formatting PI strings should not be done brute force every time, but SHOULD be done in Freemarker (not the code).
   2. Handling Yes/No for boolean objects should also be a macro handled in Freemarker.
   3. Other items like gathering Facts may also be useful to have macros. Don't go crazy, but make the info files easy to write as well. Yes, in certain points of view, this means the project has imprecise requirements. Get opinions and justify the decision.
6. The Gui2InfoFactory knowledge is limited to a specific file name.
   1. For now, this file name can be hardcoded, and one file can exist for all of PCGen. It will be a follow-on project to make that file specific to a game mode and copied into the game mode directories. I would rather do that all at once across a number of files, so that the imposition on the system directory is in one PR.
   2. Share the actual export process and only have the file name determination be part of the Gui2InfoFactory.

Implicit Design

In addition to the macros pointed out above, there are a number of items that must implicitly be designed to be successful here. This includes (but may not be limited to):

1. Determining how to communicate the SourceFormat preferences to the output. Note that today this is a SourceFormat object returned by Globals
   1. There should probably be multiple formatting macros in Freemarker that can be selected?
   2. This also needs consideration of how to keep this reasonable both short and long term, with the understanding that use of Globals strategically isn't a preferred practice.
2. Dealing with prerequisites and Freemarker output.
   1. You should be aware Prerequisites in their current form are NOT strategic. Therefore, you should probably just leverage the existing HTML that they produce and figure out a way to get that to the Freemarker output without worrying about any clever redesign.
3. How will you pull an internationalized string from the core code (assuming the HTML knows the internatinoalization key)?

Documentation Required

You will need to document at least:

1. What is the active object is called in the HTML? It should be self-consistent across the files. Note that this does not mean it always has to be "active" or some such, it could be "race" and "template" for different object types. Both are self-consistent under this definition. Feedback from the wider team (especially data/output) is encouaged.
2. Where are the files placed?
3. What are the files called?
4. What files need to be included in the release (if not obvious from the above)

Other Notes

You WILL run into items which are not currently exported in the Freemarker output system. We WILL need to talk about these.

Pointers

You should read pcgen.io.ExportHandler.exportCharacterUsingFreemarker to see what is done there since you will need a simpler version of that process.