1,007
edits
Changes
→A Better Preview
The other thing I've done is to do some string formatting using the <code>renderTemplate()</code> function. This takes a template string and performs the appropriate substitution given the passed-in JSON object. Templates can handle a wide range of functionality, as we are currently using TrimPath's [http://code.google.com/p/trimpath/wiki/JavaScriptTemplates JavascriptTemplates]. You should read their site for more documentation. Although JavascriptTemplates has some nice properties, we are contemplating moving to [http://mjtemplate.org/ MJT] sometime soon.
=== A shortcut for localization and rendering templates ===
Note how in the code above, we used the localization wrapper <code>_()</code> before passing the string to renderTemplate. Because this is such a very common combination when displaying strings, we have a shortcut for it. Calling _() with a JSON object as the second argument will automatically trigger <code>CmdUtils.renderTemplate()</code> on the post-localization string. So the above preview method could be rewritten more simply as:
<pre>
preview: function( pblock ) {
var msg = 'Inserts todays date: "<i>${date}</i>"';
pblock.innerHTML = _( msg, {date: this._date()} );
},
</pre>
=== Networking calls and placeholder previews ===
Previews display something meaningful to the user immediately. If you have a preview that requires an AJAX request—say, to fetch some search results—that call might take a while to return. In the meantime, your command should display a placeholder preview giving the user feedback.
<pre>
preview: function( pblock ) {
pblock.innerHTML = _("This will show until the AJAX request returns");
// AJAX request
pblock.innerHTML = getFromServer();
