Tag Archives: JavaScript

Handling LaTeX in WordPress and React.js

I’m in the midst of building a WordPress plugin that interfaces with WeBWorK, a web application for math and science homework. The plugin features a JavaScript app powered by React and Redux, which lives inside of a WordPress page template and communicates with WP via custom API endpoints. The project is for City Tech OpenLab and it’s pretty cool. I’ll write up some more general details when it’s closer to release.

The tool is designed for use in undergraduate math courses, so LaTeX-formatted content features heavily. LaTeX is beautiful when used on its own, but it’s hard to handle in the context of web applications. A few lessons and strategies are described below.

Delimiters

I’m dealing with “mixed” content: plain text that is interspersed with LaTeX. Some of this content is coming directly from WeBWorK, which formats LaTeX to be rendered with MathJax. WeBWorK is sending markup that, when simplified, looks like this:

[code language=”html”]
This is plain text.
Here is an inline equation:
And here is the same equation as a standalone block:

[/code]

It’s also possible for users to enter LaTeX from the front-end of the WP application. In this case, we’ve settled on the verbose delimiters \begin{math} and \end{math}, but we also support a shorthand delimiter borrowed from Jetpack’s LaTeX renderer:

[code]
This is plain text.
Here is an inline equation: \begin{math}E = mc^2\end{math}
And here is the same equation as a standalone block:
$latex E = mc^2$
[/code]

Some of these delimiter formats are more fragile than others, for various reasons – script tags that cannot be escaped, false positives due to use of literal dollar signs, etc – so I standardized on some invented delimiters for data storage. Before saving any LaTeX content to the database, I’m converting all delimiters to the following formats (of my own invention, which explains their Great Beauty):

[code]
This is plain text.
Here is an inline equation: {{{LATEX_DELIM_INLINE_OPEN}}}E = mc^2{{{LATEX_DELIM_INLINE_CLOSE}}}
And here is the same equation as a standalone block:
{{{LATEX_DELIM_DISPLAY_OPEN}}}E = mc^2{{{LATEX_DELIM_DISPLAY_CLOSE}}}
[/code]

This way, the delimiters are unique and easy to process on display.

Slashes

I’m using WordPress custom post types to store data. The lowest-level function available for saving post data is wp_insert_post(). Thanks to a glorious accident of history, this function expects data to be “slashed”, as in addslashes() and magic quotes. If you’re looking for a fun way to spend a few hours, read through this WordPress ticket and figure out a solution, please.

LaTeX uses \ as its escape character, which makes LaTeX-formatted content look “slashed” to WordPress. As such, attempting to save chunks of LaTeX using wp_insert_post() will result in slashes being removed and formatting being lost. So I had two choices: don’t use wp_insert_post(), or don’t use slashes.

I chose the latter. Before saving any content to the database, I identify text that appears between LaTeX delimiters, and I replace all slashes with a custom character. In all its glory:

[code language=”php”]
public function swap_latex_escape_characters( $text ) {
$regex = ‘;(\{\{\{LATEX_DELIM_((?:DISPLAY)|(?:INLINE))_OPEN\}\}\})(.*?)(\{\{\{LATEX_DELIM_\2_CLOSE\}\}\});s’;
$text = preg_replace_callback( $regex, function( $matches ) {
$tex = str_replace( ‘\\’, ‘{{{LATEX_ESCAPE_CHARACTER}}}’, $matches[3] );
return $matches[1] . $tex . $matches[4];
}, $text );

return $text;
}
[/code]

So a chunk of LaTeX like E = \frac{mc^2}{\sqrt{1-\frac{v^2}{c^2}}} goes into the database as

E = {{{LATEX_ESCAPE_CHARACTER}}}frac{mc^2}{{{{LATEX_ESCAPE_CHARACTER}}}sqrt{1-{{{LATEX_ESCAPE_CHARACTER}}}frac{v^2}{c^2}}}

They get converted back to slashes before being served via the API endpoints.

Rendering in a React component

I decided to stick with MathJax for rendering the LaTeX. MathJax has some preprocessors that allow you to configure custom delimiters, but I had a hard time making them work inside of my larger JavaScript framework. So I decided to skip the preprocessors and generate the <script type="math/tex"> tags myself.

React escapes output pretty aggressively. This is generally a good thing. But it makes it hard to print script tags and unescaped LaTeX characters. To make it work, I needed to live dangerously. But I didn’t want to print any more raw content than necessary. So I have two components for rendering text that may contain LaTeX. Click the links for the full source code; here’s a summary of what’s going on:

  1. FormattedProblem performs a regular expression to find pieces of text that are set off by my custom delimiters. Text within delimiters gets passed to a LaTeX component. Text between LaTeX chunks becomes a span.
  2. LaTeX puts content to be formatted as LaTeX into a script tag, as expected by MathJax. Once the component is rendered by React, I then tell MathJax to queue it for (re)processing. See how updateTex() is called both in componentDidMount() and componentDidUpdate(). Getting the MathJax queue logic correct here was hard: I spent a lot of time dealing with unrendered or double-rendered TeX, as well as slow performance when a page contains dozens of LaTeX chunks.

A reminder that React’s dangerouslySetInnerHTML is dangerous. I’m running LaTeX content through WP’s esc_html() before delivering it to the endpoint. And because I control both the endpoint and the client, I can trust that the proper escaping is happening somewhere in the chain.

I use a very slightly modified technique to provide a live preview of formatted LaTeX. Here it is in action:

output

Pretty cool TeXnology, huh? ROFLMAO

Improved ‘equalto’ validation for Parsley.js

I’ve been playing with Parsely.js for form validation on a client project. It’s pretty nice, but I was unhappy with the ‘equalto’ implementation. ‘equalto’ allows you to link two fields whose entries should always match, such as when you have password or email confirmation fields during account registration. parsley-equalto is not symmetrical. If you enter some text into A, and enter non-matching text into B, B will not validate. If you correct B so that it matches A, then B will validate. So far, so good. But if you correct A so that it matches B, it won’t change the validation.

So I wrote a custom implementation that triggers validation on the paired field, making the link between the fields symmetrical. It’s pretty ugly (to avoid recursion) and doesn’t have any error handling, but it should point you in the right direction. (I’ve called it iff, which you can look up.)

The markup:

[code language=”html”]


[/code]

The validator:
[code language=”javascript”]
var iffRecursion = false;
window.Parsley.addValidator( ‘iff’, {
validateString: function( value, requirement, instance ) {
var $partner = $( requirement );
var isValid = $partner.val() == value;
if ( iffRecursion ) {
iffRecursion = false;
} else {
iffRecursion = true;
$partner.parsley().validate();
}
return isValid;
}
} );
[/code]

Make Github issue numbers appear in browser tabs

#70. Yippee!

#70. Yippee!

I use Github Issues as a bugtracker for a number of my projects. My workflow usually includes having the ticket open in one browser tab, and a local WordPress installation open in another browser tab (to test the bugfixes themselves). When I write commit messages, I want to reference the issue number, but by default, it’s buried deep in the <title> element, and thus not visible on a smallish browser tab.

So I wrote a short userscript that reproduces the issue number at the beginning of the <title>, so I can see it at a glance. It’s structured as a userscript for Greasemonkey/Firefox, though I imagine you could easily repackage it for Chrome or whatever.

[code language=javascript]
// ==UserScript==
// @name github issue number in tab
// @namespace https://boone.gorg.es
// @description github issue number in tab
// @include https://github.com/*/*/issues/*
// @version 1
// @grant none
// ==/UserScript==

var t, ttext, issueno;

t = document.getElementsByTagName( ‘title’ );
ttext = t[0].innerHTML;
ino = ttext.match(/Issue #([0-9]+)/);
console.log(“#” + ino[1] + ” ” + ttext);
t[0].innerHTML = “#” + ino[1] + ” ” + ttext;
[/code]

Using init callbacks with TinyMCE and wp_editor() in WordPress

WordPress 3.3 introduced wp_editor(). It’s a big improvement over the earlier hacks needed to get a TinyMCE instance on the WP front end. But it broke the feature in my BuddyPress Docs that detected idle time. The problem, in short, was two-fold: my idle-detection JavaScript was loading before the editor was initialized, and it wasn’t detecting key presses inside of the TinyMCE iframe. The solution to both parts of the problem required passing callbacks to the TinyMCE initialization array, in the setup array. It took me a long time to figure out how to do this, so for posterity’s sake, here are some takeaways.

First, the code:

[code language=”php”]
function bp_docs_add_idle_function_to_tinymce( $initArray ) {
if ( bp_docs_is_bp_docs_page() ) {

$initArray[‘setup’] = ‘function(ed) {
ed.onInit.add(
function(ed) {
_initJQuery();

// Set up listeners
jQuery(‘#’ + ed.id + ‘_parent’).bind(‘mousemove’,function (evt){
_active(evt);
});

bp_docs_load_idle();

}
);

ed.onKeyDown.add(
function(ed) {
_active();
}
);
}’;
}

return $initArray;
}
add_filter( ‘tiny_mce_before_init’, ‘bp_docs_add_idle_function_to_tinymce’ );
[/code]

Some notes:

  • I’m passing a ‘setup’ parameter to the TinyMCE init array by filtering tiny_mce_before_init
  • Only do this when you’re editing a BuddyPress Doc – that’s the bp_docs_is_bp_docs_page() check. I don’t want to mess with every instance of TinyMCE on the installation.
  • The setup parameter has to be a string. This gets tricky when the string is supposed to define an unnamed JS callback, because you have to be very careful about escaping quotes. As a string, your callback has to be wrapped in quotes. Also, when WP prints the TinyMCE parameters (and when it sees that your paramater begins with the string ‘function’) it’s going to wrap it in double-quotes. After lots of messing around, I was able to get this to work by using escaped single-quotes. (If you need to double-embed quotes – like a chain of callbacks – use escaped double-quotes.)
  • Where possible, use TinyMCE’s native events. ed.onKeyDown is one of them. It allows me to call my _active() function whenever a key is pressed inside the editor.
  • There are some kinds of actions that aren’t really detectable using TinyMCE’s events. For instance, I wanted to be able to detect when someone was moving their mouse around the iframe and especially TinyMCE’s toolbar. You can see this where I’m binding my callback to mousemove in the TinyMCE _parent element.
  • _initJQuery() and bp_docs_load_idle() are my own functions that need to run after the editor has finished setting up. That’s why they, along with the bind, are called in a callback of ed.onInit – that’s the generic place to put things that need to happen once the editor is up and running.

New WordPress plugin: Add User Autocomplete

Add User Autocomplete

Add User Autocomplete

Site admins on a WordPress Network can add existing network members to their site on the Dashboard > Users > Add New panel. But the interface requires that one know either the email address or the username of the user in question. My new plugin, Add User Autocomplete, makes the Add Existing User workflow a bit easier, by adding autocomplete/autosuggest to the Email Address/Username field. Just start typing, and the plugin will return matching users; arrow down or click on the intended user to add her to the Add User list.

A few additional bonuses provided by the plugin, aside from autocomplete:

  • In addition to return email address and username matches, the plugin also checks against the display_name and user_url fields. So if my username is ‘admin’, and my email address is ‘bgorges@boonebgorges.com’, but my display name around the site is ‘Boone Gorges’, you’ll be able to find me by searching on ‘Boone’.
  • You can add many users to a blog at once. Search for one user, select and hit Return, and then search for another.
  • Prettier success messages. When you submit the Add New User page, your success message will give you a list of the users invited, instead of a generic “Invitations have been sent” type message.

Add User Autocomplete requires WP 3.1 and JavaScript. The plugin was developed for the CUNY Academic Commons. Check out the plugin at wordpress.org or follow its development at Github.