# [MathQuill](http://mathquill.github.com) by [Han][], [Jeanine][], and [Mary][] (maintainers@mathquill.com) [Han]: http://github.com/laughinghan [Jeanine]: http://github.com/jneen [Mary]: http://github.com/stufflebear Good news! We've resumed active development and we're committed to getting things running smoothly. Find a dusty corner? Let us know! [slackin.mathquill.com](http://slackin.mathquill.com) [freenode irc: #mathquill](http://webchat.freenode.net/?channels=mathquill) ## Usage Just load MathQuill and call our constructors on some HTML element DOM objects, for example: ```html

Solve ax^2 + bx + c = 0: x=

``` To load MathQuill, - [jQuery 1.4.3+](http://jquery.com) has to be loaded before `mathquill.js` ([Google CDN-hosted copy][] recommended) - the fonts should be served from the `font/` directory relative to `mathquill.css` (unless you'd rather change where your copy of `mathquill.css` includes them from), which is already the case if you just: - download and serve [the latest release][]. [Google CDN-hosted copy]: http://code.google.com/apis/libraries/devguide.html#jquery [the latest release]: https://github.com/mathquill/mathquill/releases/latest To use the MathQuill API, first get the latest version of the interface: ```js var MQ = MathQuill.getInterface(2); ``` Now you can call `MQ.StaticMath()` or `MQ.MathField()`, which MathQuill-ify an HTML element and return an API object. If the element had already been MathQuill-ified into the same kind, return that kind of API object (if different kind or not an HTML element, `null`). Note that it always returns either an instance of itself, or `null`. ```js var staticMath = MQ.StaticMath(staticMathSpan); mathField instanceof MQ.StaticMath // => true mathField instanceof MQ // => true mathField instanceof MathQuill // => true var mathField = MQ.MathField(mathFieldSpan); mathField instanceof MQ.MathField // => true mathField instanceof MQ.EditableField // => true mathField instanceof MQ // => true mathField instanceof MathQuill // => true ``` `MQ` itself is a function that takes an HTML element and, if it's the root HTML element of a static math or math field, returns an API object for it (if not, `null`): ```js MQ(mathFieldSpan) instanceof MQ.MathField // => true MQ(otherSpan) // => null ``` API objects for the same MathQuill instance have the same `.id`, which will always be a unique truthy primitive value that can be used as an object key (like an ad hoc [`Map`][] or [`Set`][]): ```js MQ(mathFieldSpan).id === mathField.id // => true var setOfMathFields = {}; setOfMathFields[mathField.id] = mathField; MQ(mathFieldSpan).id in setOfMathFields // => true staticMath.id in setOfMathFields // => false ``` [`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map [`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set Similarly, API objects for the same MathQuill instance share a `.data` object (which can be used like an ad hoc [`WeakMap`][] or [`WeakSet`][]): ```js MQ(mathFieldSpan).data === mathField.data // => true mathField.data.foo = 'bar'; MQ(mathFieldSpan).data.foo // => 'bar' ``` [`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap [`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet Any element that has been MathQuill-ified can be reverted: ```html some HTML ``` ```js MQ($('#revert-me')[0]).revert().html(); // => 'some HTML' ``` MathQuill uses computed dimensions, so if they change (because an element was mathquill-ified before it was in the visible HTML DOM, or the font size changed), then you'll need to tell MathQuill to recompute: ```js var mathFieldSpan = $('\\sqrt{2}'); var mathField = MQ.MathField(mathFieldSpan[0]); mathFieldSpan.appendTo(document.body); mathField.reflow(); ``` MathQuill API objects further expose the following public methods: * `.el()` returns the root HTML element * `.html()` returns the contents as static HTML * `.latex()` returns the contents as LaTeX * `.latex('a_n x^n')` will render the argument as LaTeX Additionally, descendants of `MQ.EditableField` (currently only `MQ.MathField`) expose: * `.focus()`, `.blur()` focuses or defocuses the editable field * `.write(' - 1')` will write some LaTeX at the current cursor position * `.cmd('\\sqrt')` will enter a LaTeX command at the current cursor position or with the current selection * `.select()` selects the contents (just like [on `textarea`s][] and [on `input`s][]) * `.clearSelection()` clears the current selection * `.moveTo{Left,Right,Dir}End()` move the cursor to the left/right end of the editable field, respectively. (The first two are implemented in terms of `.moveToDirEnd(dir)` where `dir` is one of `MQ.L` or `MQ.R`, constants that obey the contract that `MQ.L === -MQ.R` and vice versa.) * `.keystroke(keys)` simulates keystrokes given a string like `"Ctrl-Home Del"`, a whitespace-delimited list of [key values][] with optional prefixes * `.typedText(text)` simulates typing text, one character at a time * `ᴇxᴘᴇʀɪᴍᴇɴᴛᴀʟ` `.dropEmbedded(pageX, pageY, options)` insert a custom embedded element at the given coordinates, where `options` is an object like: ```js { htmlString: '', text: function() { return 'custom_embed'; }, latex: function() { return '\customEmbed'; } } ``` * `ᴇxᴘᴇʀɪᴍᴇɴᴛᴀʟ` `.registerEmbed('name', function(id){return options})` allows MathQuill to parse custom embedded objects from latex, where `options` is an object like the one defined above in `.dropEmbedded`. This will parse the following latex into the embedded object you defined: `\embed{name}[id]}` [on `textarea`s]: http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-48880622 [on `input`s]: http://www.w3.org/TR/DOM-Level-2-HTML/html.html#ID-34677168 [key values]: http://www.w3.org/TR/2012/WD-DOM-Level-3-Events-20120614/#fixed-virtual-key-codes MathQuill overwrites the global `MathQuill` variable when loaded. You can undo that with `.noConflict()` (similar to [`jQuery.noConflict()`] (http://api.jquery.com/jQuery.noConflict)): ```html ``` (Warning: This lets different copies of MathQuill each power their own math fields, but using different copies on the same DOM element won't work. Anyway, .noConflict() is primarily to help you reduce globals.) #### Configuration Options `MQ.MathField()` can also take an options object: ```js var el = $('x^2').appendTo('body'); var mathField = MQ.MathField(el[0], { spaceBehavesLikeTab: true, leftRightIntoCmdGoes: 'up', restrictMismatchedBrackets: true, sumStartsWithNEquals: true, supSubsRequireOperand: true, charsThatBreakOutOfSupSub: '+-=<>', autoSubscriptNumerals: true, autoCommands: 'pi theta sqrt sum', autoOperatorNames: 'sin cos etc', substituteTextarea: function() { return document.createElement('textarea'); }, handlers: { edit: function(mathField) { ... }, upOutOf: function(mathField) { ... }, moveOutOf: function(dir, mathField) { if (dir === MQ.L) ... else ... } } }); ``` To change `mathField`'s options, the `.config({ ... })` method takes an options object in the same format. Global defaults for a page may be set with `MQ.config({ ... })`. If `spaceBehavesLikeTab` is true the keystrokes {Shift-,}Spacebar will behave like {Shift-,}Tab escaping from the current block (as opposed to the default behavior of inserting a Space character). By default, the Left and Right keys move the cursor through all possible cursor positions in a particular order: right into a fraction puts the cursor at the left end of the numerator, right out of the numerator puts the cursor at the left end of the denominator, right out of the denominator puts the cursor to the right of the fraction; symmetrically, left into a fraction puts the cursor at the right end of the denominator, etc. Note that right out of the numerator to the left end of the denominator is actually leftwards (and downwards, it's basically wrapped). If instead you want right to always go right, and left to always go left, you can set `leftRightIntoCmdGoes` to `'up'` or `'down'` so that left and right go up or down (respectively) into commands, e.g. `'up'` means that left into a fraction goes up into the numerator, skipping the denominator; symmetrically, right out of the numerator skips the denominator and puts the cursor to the right of the fraction, which unlike the default behavior is actually rightwards (the drawback is the denominator is always skipped, you can't get to it with just Left and Right, you have to press Down); which is the same behavior as the Desmos calculator. `'down'` instead means it is the numerator that is always skipped, which is the same behavior as the Mac OS X built-in app Grapher. If `restrictMismatchedBrackets` is true then you can type [a,b) and [a,b), but if you try typing `[x}` or `\langle x|`, you'll get `[{x}]` or `\langle|x|\rangle` instead. This lets you type `(|x|+1)` normally; otherwise, you'd get `\left( \right| x \left| + 1 \right)`. If `sumStartsWithNEquals` is true then when you type `\sum`, `\prod`, or `\coprod`, the lower limit starts out with `n=`, e.g. you get the LaTeX `\sum_{n=}^{ }`, rather than empty by default. `supSubsRequireOperand` disables typing of superscripts and subscripts when there's nothing to the left of the cursor to be exponentiated or subscripted. Averts the especially confusing typo `x^^2`, which looks much like `x^2`. `charsThatBreakOutOfSupSub` sets the chars that when typed, "break out" of superscripts and subscripts: for example, typing `x^2n+y` normally results in the LaTeX `x^{2n+y}`, you have to hit Down or Tab (or Space if `spaceBehavesLikeTab` is true) to move the cursor out of the exponent and get the LaTeX `x^{2n}+y`; this option makes `+` "break out" of the exponent and type what you expect. Problem is, now you can't just type `x^n+m` to get the LaTeX `x^{n+m}`, you have to type `x^(n+m` and delete the paren or something. (Doesn't apply to the first character in a superscript or subscript, so typing `x^-6` still results in `x^{-6}`.) `autoCommands`, a space-delimited list of LaTeX control words (no backslash, letters only, min length 2), defines the (default empty) set of "auto-commands", commands automatically rendered by just typing the letters without typing a backslash first. `autoOperatorNames`, a list of the same form (space-delimited letters-only each length>=2), and overrides the set of operator names that automatically become non-italicized when typing the letters without typing a backslash first, like `sin`, `log`, etc. Defaults to the LaTeX built-in operator names ([Section 3.17 of the Short Math Guide][3.17]) plus some missing trig operators like `sech`, `arcsec`, `arsinh`, etc. [3.17]: http://tinyurl.com/jm9okjc `substituteTextarea`, a function that creates a focusable DOM element, called when setting up a math field. It defaults to `