XML option browser

Cernel

@redrum I think PoS2 is better if you know about everything already, and just need copy-pasting and refreshing your memory.

Just be sure to, like, clarifying in PoS2 itself that it is not necessarily updated, to avoip people assuming it is (I mean a clear notice about that at the start of the xml).

theredbaron

I thought I should offer some encouragement here. This looks phenomenal, and is close to what I had envisioned in the past could be added to the TripleA website. I would suggest that we offload POS2 XML to this new format, while keeping a bare-bones POS2 XML file that would need very little updating.

POS2 is still needed to provide an example implementation for many of these options, as well as sample code, but I think this solution will fill a different role, maybe replacing POS2's reference function. If we do it right, we might even be able to deep link to this reference from within the code comments in POS2 XML. However, as Cernel is, I'm wary of change, as I've gotten used to working with POS2 XML. So we'll have to be sure to get this right.

LaFayette

@redrum

@LaFayette I don't want to put the comments in the engine source code as then no one but developers would ever maintain it. Its better in a place that map makers can also contribute to.

I don't think that is the right concern, but I would want it to be so that developers would keep the source data up to date when adding new attachments, but open for anyone to modify and improve the documentation at the same time.

We essentially have this model with triplea_maps.yml. While not perfect, it has worked out that more than just developers can update the file.

I checked out the source code further, it's not in good shape to accept more information as either additional javadocs or java annotations, so keeping this info in java source files I would agree is not a good one.

@mahks said in XML option browser:

The HTML page is pretty straight forward. Could be maintained by anyone with HTML. I could do it for now.
But I think the most important thing is getting the data in a portable format.

I generally agree, but I do think there are a some additional important questions to decide/answer:

how to integrate this as an official tool so we can keep it up to date now and for the long term?
will the web server hosting technology integrate with the rest of the TripleA infrastructure, will it add another server to be managed and maintained?
will there be overhead or delays in deploying any data updates to the web server?

I like the tool as presented and I think it would make sense for it to be part of the official project. I think two really good options to do that would be either:

Similar to the maps yaml file, host a yml file that is updated when we update source, on updates the yml data would be transformed to JSON and uploaded to website (we do this about exactly for the maps.yml data today).
Host the HTML file independently from the source code but on the github website directly. Github.io uses a jekyll, it can render HTML natively.

The first option has greater one-time setup cost, but data is pure from presentation layer and can be updated at same time as source, so lowest maintenance cost over the long term compared to the second option (which is also completely viable too).

Any third option (is very welcome), but would have some challenges to solve for the concern of server maintenance overhead in addition to keeping the data well maintained over time.

Mahks

@lafayette

"how to integrate this as an official tool so we can keep it up to date now and for the long term?"

Currently the data is embedded in the html page. I did that so it would not need server access (the page can be used off-line). The data could be split off into a second file and just loaded by the html page. If you go with the yml to JSON idea, this would be the way to go.

"will the web server hosting technology integrate with the rest of the TripleA infrastructure, will it add another server to be managed and maintained?"

I see no reason why the page would need its own server. No security is needed, just drop the html file and the JSON file (if separate) on an existing server.

"will there be overhead or delays in deploying any data updates to the web server?"

I have no experience working with files that are editable by a group, so I don't know how you would manage version control. On my own projects I just upload the new file to the server.

"Similar to the maps yaml file, host a yml file that is updated when we update source, on updates the yml data would be transformed to JSON and uploaded to website (we do this about exactly for the maps.yml data today).
Host the HTML file independently from the source code but on the github website directly. Github.io uses a jekyll, it can render HTML natively."

Currently the XOB html page does not need server access. The page uses javascript to re-render the page without requiring server generated pages (like the wiki does). So the html base file would rarely change. It would only be the JSON file that would need to be kept up to date.

I was not familiar with YAML, After a quick peek at the wikipedia page I see that it is the mother of JSON.
So it is possible to import a yml file into javascript, though not as clean as just loading a JSON object.
You could just use JSON rather than the YAML format negating the need to convert.
If you are not familiar with JSON have a look. In fact you could keep the data within the html file (just use it instead of the yml).
To see what I mean download the XOB file (rather than loading the page by left-click) and view it in an editor. I suspect the data format will look much like the YAML you are used to.

One issue that was a pain in JSON, and could be in YAML, was the examples. I wanted the examples (when viewed in XOB) to be indented and formatted as you would see them in the XML. XML elements can be confused with HTML elements when a browser renders a page. The only way I found of formatting the data so the examples look correct (and could also be copied to the clipboard in a usable format) was to place them in a TEXTAREA. And this meant I could not use HTML to do the indenting, I had to use tabs. Tabs are illegal in JSON (and YAML) so they all had to be escaped (along with all double quotes - which the XML uses). ARGHHHH...

So my point with all that was, examples cannot just be dropped into JSON or YAML, there is a bunch of fiddle required.

redrum

@mahks @LaFayette My thought is put a JSON or YAML file at the root of the tripleA project just like the triplea_maps.yaml. Then have the necessary HTML/JS/CSS in the website project that pulls in that file and create a new area in the website to show this map making wiki. Thoughts?

Mahks

I could not load https://triplea-game.org/triplea_maps.yaml, where can I find it?

redrum

@mahks https://github.com/triplea-game/triplea/blob/master/triplea_maps.yaml

Mahks

I like the lack of quotation marks in Yaml.
I don't understand how it knows the difference between a variable name and its contents.

ie;

mapName: Total World War
mapCategory: BEST
url: https://github.com/triplea-maps/total_world_war/archive/master.zip
version: 5

how does it deal with the 2 colons on the url line?

redrum

@mahks Must have colon then space for key: value. I believe you can also use single quotes around a string if it happens to have a colon then space but is part of the string (key: 'part1: part2'. Generally, you only put 1 key/value pair per line.

Mahks

@redrum said in XML option browser:

@mahks @LaFayette My thought is put a JSON or YAML file at the root of the tripleA project just like the triplea_maps.yaml. Then have the necessary HTML/JS/CSS in the website project that pulls in that file and create a new area in the website to show this map making wiki. Thoughts?

I would like to see the tool able to be used off line. Not sure how important that is to others. For that, it would be ideal to have only one file that contains all HTML/JS/CSS & JSON.

Maybe those in the community that normally update the POS2 or YAML, could look at the JSON data in the XOB document and tell us if they would be able to update that data format directly. If so things become very simple. If not we then need at least 2 files and a conversion process.

Having the XOB page within the TA page is neither here nor there as it would most likely be in a separate tab or window if in use. I personally would want a stand alone page just to maximize screen real estate.

redrum

@mahks Probably could just offer a download from the website that either just downloads all the HTML/JS/CSS/JSON in a folder that could run locally or even as say a PDF or something. That should be relatively easy since to get it on the website it would be pulling all of those together anyways.

RoiEX

@Mahks I don't think having an inlined all-in-one page fits the structure of our website.
Of course we could just upload the file and leave everything as-is, but if we want to align the design with a website we'd want to use the existing css that's being kept seperate in its own css file.
So if we want to drop offline support I have a pretty good strategy that'll make everything pretty easy to read.
I'd actually prefer seperate files per entry, the opposite of @redrum's idea.
This way everything is way more structured and easier accessible.
Also when creating a new entry one would just create a new file which is pretty straightforward IMO.
Also we could give "context" a special treatment so that the xml can just get pasted at the end of the file without having to to any escaping.

LaFayette

Thanks for feedback.

To build on how yaml knows about the double colon, it knows based on the first letter after the first colon. There are three choices, 'string', 'list', or 'map', if it sees a [, it's a list, { for a map, and any letter is a string value. You can also do lists in a different syntax, multi-line as:

list_name:
 - a
 - b
 - c
same_list_values: [ 'a' , 'b', c' ]

And for a map:

map_name:
  - property_a: 1
  - property_b: 2 
map_name { 'a': 1, 'b': 2 }

And you can nest these, so hence why we have a superset of JSON.

YAML provides block values with native HTML without any escaping, so it's just a nicer format to work with and avoids the error prone syntax requirements of JSON.

The idea is that we basically structure a YAML to match the needed JSON, work with the YAML by hand, and use software to do the relatively simple conversion to JSON and upload to website (we have an existing pattern for doing that).

All that aside, simply hosting the HTML directly on the triplea website is a good first option! : )

That would be just plopping the file in: https://github.com/triplea-game/triplea-game.github.io; Then it'll be available from http://triplea-game.org/theFileName.html

LaFayette

Sounded to me like offline support was in-lieu of online support. The most brute-force option here is to just host on website as an html.

Overall it seems we are weighing three options:

maintain the data as an html file (post-render) hosted directly on website repo.
create dynamic html page that is hosted on website repo, feed the page a JSON payload that is rendered from a YML file
create dynamic html page that is hosted on website repo, feed the page a JSON payload that is rendered from a set of input files (eg: all files in a given folder)

Let me know @RoiEX if I mischaracterized the recommendation.

RoiEX

@LaFayette Seems right.
However I'd like to point out option 2 and 3 do not work well offline.

Mahks

Update:

Added alpha buttons
Hierarchical index now expands & collapses

XOB Update

Mahks

Update:

Search option added
Navigation to previous object added.
Fixed off-line issues.

XOB Update

General_Zod

@mahks Nice job.

Hepps

@mahks Glad to see this is still alive. Well done fine sir!

butterw

The hierarchical index is great tool for anyone trying to understand what is possible with triplea game scenario .xml. POS2 can be a bit hard to read and take in.