mathquill/mathquill — pull request #336 by laughinghan (2014-09-06 01:18:41+00:00)
Title: Add config options architecture to API

Config options architecture:
- API changes:
The big change here is a config options architecture. There are now no longer separate "Global Behavior Options" and options for individual math fields, instead:
- any option can be set globally with `MathQuill.config({ ... })`, e.g. `MathQuill.addAutoCommands('sin cos log')` is now `MathQuill.config({ autoCommands: 'sin cos log' })`
- any option can be set on an individual field to override the global default by passing in an options object to the `MathQuill.MathField()` constructor, e.g. `MathQuill.MathField(mathFieldSpan, { autoCommands: 'sin cos log' })`
- the configuration of a field can even be changed dynamically by calling the `.config({ ... })` method on the math field at any time

This happens in a slightly roundabout way, I first toyed with a global `MathQuill.options` object, on which you could set page-wide defaults for options, but then special processing can only be done when initializing a math field, whereas we'd prefer error handling for invalid `leftRightIntoCmdGoes` or `autoCommands` values to happen as early as possible. More advantages of the `.config({ ... })` methods-based architecture are described in [the commit they're introduced](c60fa6cbe4c43a3ed8ef5bfdcee1cfb1d953648f) and [its comment](https://github.com/mathquill/mathquill/commit/c60fa6cbe4c43a3ed8ef5bfdcee1cfb1d953648f#commitcomment-7394156).

(Normally I'd rebase, but I try to keep commit-gardening to within a few days of work, not several weeks.)

The other important change is access to the `options` object:
- as described in [the commit comment I just mentioned](https://github.com/mathquill/mathquill/commit/c60fa6cbe4c43a3ed8ef5bfdcee1cfb1d953648f#commitcomment-7394156), it's no longer on the controller object but is on the API object as `.__options`, so controller methods now access it as `ctrlr.API.__options` (which is kinda nice 'cos it reads like "the controller's API options")
- Problem: the controller isn't accessible to methods on commands, like `createBefore`, and many options affect specific commands and currently have to be global, like `MathQuill.addAutoCommands()` and `MathQuill.addCharsThatBreakOutOfSupSub()`.
+ Solution for now: add `.options` to the cursor, which is passed to all those methods. Maybe we should actually be passing in a "context" object with the cursor, selection, and options as properties, or something. Oh well.

The "Global Behavior Options" are each replaced by the following options in the new config options architecture:
- `MathQuill.disableCharsWithoutOperand()` is replaced by the more specific `supSubsRequireOperand`, superscripts and subscripts are the only postfix commands that is visually imprecise
- `MathQuill.addCharsThatBreakOutOfSupSub()` is now `charsThatBreakOutOfSupSub`
- `MathQuill.addAutoCommands()` is now `autoCommands`
+ plus fix an error handling edge case
- `MathQuill.overrideAutoUnitalicized()` is now `autoOperatorNames`
+ first, little fixes: a cosmetic flaw in a test case, and an error handling edge case
+ and a big renaming, to reduce the "unitalicize"/"un-italicize" inconsistency:
- instead the names themselves are now "operator names", the adjective to describe their formatting is "non-italicized" (most common relevant term, see 78ede751196f197dae3db8f569bad19fd0a178dc), and the verb is "un-italicize" always with a dash
- also, `UnItalicizedCmds`, `OperatorNames`, and `TwoWordOps` are now `AutoOpNames`, `BuiltInOpNames`, and `TwoWordOpNames`, respectively
+ finally, there are methods on `Letter` needed to implement this option (`finalizeTree`, `sibling{Created,Deleted}`) that of course have no access to the controller, but also have no access to the cursor and so can't do `cursor.option`. In order for those methods to use the option object of the relevant math field rather than a global variable, they now take an options object as their first argument (9d8fa6b1955779910b7af451ac962f57721e6513)

Other little API-related fixes:
- (cosmetic fix to API summary)
- document and add error-checking for `substituteTextarea`
- `statelessClipboard` isn't ready to be public, add a TODO comment
- add visual tests for the public API options that had none yet

Misc. code quality improvements:
- refactor away opaque `setMathQuillDot()` (what does it set MathQuill dot to?) in favor of more descriptive `APIFnFor(APIClass)`
- re-org math field initialization:
+ move `root.setHandlers()` call from `MathQuill.MathField` in `commands/math.js` to `EditableField::initRootAndEvents` in `publicapi.js`
+ factor out `Controller`/API object linking-up-to-each-other code from `AbstractMathQuill::initRoot` in `publicapi.js` and `InnerMathField::init` in `commands/math/commands.js` into `Controller::init` in `controller.js`
- fix that the unit test page can show 100% pass even if an exception is thrown by MathQuill, if it's not in a test case
- comment opaque contract on `MathElement::finalizeInsert`'s 2nd arg