Home

Marshall

Marshall is a javascript library based on Toomas Römer's jsPgnViewer library which he licensed under the apache 2.0 license. For the sake of consistency, this is also licensed under the apache license.

There are a lot of misinterpretations of the PGN standard out there (for example, this page insists that semi-colons are not allowed inside comment braces, when the standard clearly says they are) so if you're having problems converting a PGN file for use with Marshall, it may not be a bug, it may be because the person/program that generated the file doesn't really understand PGN. Or, it could be a bug.

Let me know about it by filing an issue, anyway. I'm a firm believer in Postel's Law and we may be able to make an adjustment to the parser to allow that particular piece of bad PGN to be parsed anyway, without breaking parsing for "real" PGN files. As evidence of that idea, note Marshall will accept castling with zeros (0-0-0) as well as uppercase o's (O-O-O) even though the standard expressly forbids the zeros. (Marshall also doesn't insist on the tag order specified in the standard, and will fill in required tags that are not in the file, given them the unknown value.) The idea behind Marshall is not to poke holes in your PGN, it's to let you play over a game.

##Why a fork?

Basically, because I wanted a different approach to the output. I wanted semantically proper markup, and I wanted to control the appearance of everything with css, rather than inline styles written (and controlled) by javascript. I recognize this is a different goal from the original. It was too much to ask that the original author accept changes that would quite probably break the Wordpress plugin he also offered with the library, so a fork was the kindest option for all. I let him know he's free to take whatever he finds here and merge in back into his original work, if he likes.

I wanted a "design-friendly" pgn viewer, one based on good semantic HTML markup and leaves the styling to you, so I could fit it into the design of whatever site I wanted to use it on without having to wrestle with it. That's also why this version doesn't rely on the presence of any other javascript libraries, no dependencies means no conflicts. We may end up making several versions of Marshall that will leverage the existence of various libraries; let me know which ones you want to see, if any.

##What's the status?

Version 1.0.0

Milestones in the repo will be tagged as they happen, so if you want something with an official version label you can pull one of those, but versioning will be a little "soft" for this. The master branch of the repo should always be stable, and will usually include tested bug fixes and features that are not yet in a tagged version, so pulling the master branch rather than a tag should get you the current "best" version of the code; the tags are placed there more for historical interest than utility. Major work will be done in a feature branch, and brought over into master only after testing. Feel free to browse and use any of the branches, but the current master branch is the one bug reports should be made on and suggestions should be logged for.

This started because I was scratching an itch of my own, but I've almost finished doing that. Let me know what they are and maybe I can scratch some of yours, as well. Or better yet, feel free to scratch your own itch and submit a pull request. I should warn you, though, that I'm a bit of a bugger on testing, so you should check out Jasmine if you plan on submitting many pull requests for this. (See Testing Marshall for further notes on testing this code.)

Configuring Marshall

Marshall is a "some assembly required" product. I don't know what your site looks like, so I can't pre-design Marshall to fit in. But I can give you good semantic markup and let you apply the right CSS to it to make that happen. Marshall uses some basic classes and markup that will let you style it the way you want it.

Marshall produces good semantic markup and functional javascript interaction by default, but there may be changes in action/appearance that are desired under some circumstances that are difficult or impossible to achieve just with CSS, so Marshall supports some configuration options.

You configure Marshall by sending in a set of key/value pairs, like:

{"flipped": true, "showMovesPane": false}

which it reads and responds to. In the above case, it will start out with the moves hidden from view and the board upside down (black at the bottom). There's a full list of configuration options in the wiki to help you put Marshall to work for you fully.

Next Step: Get Started using Marshall