Being able to interact with the MindTouch API without forcing users to use the WYSIWYG editor is something that comes up frequently. It’s the Holy Grail of MindTouch developers everywhere who want to make their applications built in MindTouch easy to use and professional in appearance. Questions like:

• “How can I write to a page property without having to wade through page submenus?”
• “How did that gauge update without reloading the whole page?”
• “How the heck did you DO that?!?” (my perennial favorite)

all come up in the forums and in the MindTouch IRC channel. Previously we’ve seen some skillful jQuery ajax work from our frontend wizard Damien H to find ways to talk to the API. It’s a little granular and requires some knowledge as to what’s needed in order to direct the call, but it’s certainly the most customizable.

But what if you didn’t need to do things like check the xhr.status, and instead just wanted to do something like update a page property through the API?

Aspiring Dekiscripters, meet DekiAPI().

MindTouch has developed a very quick and easy way to accomplish many of the calls that coders have been asking how to do (or have been begging for an easier way to do!). The new javascript API extension allows Dekiscripters to do a number of API-related functions simply, including (but not limited to):

• Read/update page contents
• Create/read/update/delete page properties
• Post messages to the API (which is used in the SendMessage template, discussed at the Developer site)
• Reload individual DOM elements
• Make sense of the health-care debate in America

Well, ok, not the last one. Not yet, anyways.

Previously if you wanted to say, update an existing page property, you’d have to slog about 50-60 lines of code and ajax calls to do it safely (if you wanted to do it unsafely, you could probably do it in about 10). Using the DekiAPI() functionality, it can be done in about 4 lines, 6 if you want pretty error messages should your update fail for some reason.

Let’s check out one of the more visually-appealing components of the DekiAPI script: the MindTouch.Deki.Reload() function. You can see the Reload in action here (part of the Down With Stagnant Corporate Intranets webinar):

(high-quality version can be seen here)

When a task is added or completed, the Task List automatically reloads, and the Progress Meter gauge is updated. This element-specific reload provides a much more fluid and seamless user experience, and projects a “polished” image for your application. Although there’s obviously a lot more going on behind the scenes as far as the task management and progress calculation in this example, the actual reload itself is quite simple.

No, really, how did you do that??

Step 1: Install and call DekiAPI().

Swing by the Deki AJAX API extension page to learn how to install it (you must have administrative privileges to access the control panel). After it’s successfully been installed and started, make sure you call it at the top of the page you want to reload by entering

{{ dekiapi() }}

or, if you’re using the Dekiscript <pre> formatting (which I highly recommend!),

dekiapi();

Bear in mind that you will need UNSAFECONTENT enabled for your user, group, or site to create pages that use this. If you’re creating a template, the scripting can still be maintained and used by users without UNSAFECONTENT so long as the template is being invoked (as opposed to inserted into) the page.

Step 2: Know what you want to reload.

This may seem obvious, but it’s about as fundamentally important as you can get. For example, take the following block:

<div id="outsideDiv">
    feed.list("foo");
    <div id="insideDiv">
        feed.list("bar");
    </div>
</div>

If you reload outsideDiv, both the foo and the bar RSS feeds will reload. Clearly that’s the desired result in this simple example, but  that can have some visually unappealing effects when you are reloading a div that contains, say, a table. If you have data within a table that you want to refresh, you’ll want to reload specific rows in that table, instead of forcing the entire table to redraw. It looks a lot more polished and less jarring to watch a single row/div/span/etc. reload instead of seeing the whole table disappear and reappear (causing the other elements around it to be affected as well).

Step 3: RELOAD!

Chances are, some event will be triggering an element reload. Whether it be an ONCLICK event, a JEM call from within a CTOR attribute, or a Javascript timer trigger, the invocation looks like this:

Photo by Photo Plod (flickr)

MindTouch.Deki.Reload(DOM_id, params, callback);

where DOM_id is the ID of the element you want to reload, params are any additional parameters you wish to include (this is generally null,the script inserts a dummy parameter to prevent certain browsers from presenting a cached version of the reloaded element), and callback is any additional function or activity you want to execute on complete. The last two arguments are optional; I often leave them out when using this particular function.

To reload the insideDiv from the example block above, let’s pretend that we’ve published a message on the “reload_Element” channel saying to reload. The complete script (assuming the use of the Dekiscript <pre> formatting) would be:

<script type="text/jem">"
    when(@reload_Element){
        MindTouch.Deki.Reload(#insideDiv);
    }
"</script>

Complex, huh? Seriously, that’s all there is to it.

For those not used to working inside the Dekiscript <pre> formatted blocks, those additional double-quotes are necessary, whereas they are not in plain source mode. This applies to <style type=”text/css”> blocks as well, and gave me some grief in the beginning until I got it figured out.

To see Reload in action, I built a simple example here: Reload Example

Additional Considerations

There are a few other things to consider when using the Reload function:

• CTORs (JEM connectors inside of elements) lose functionality when reloaded. It’s an important thing to be aware of.  There are some ways around it, but that’s a little outside the scope of this post.
• Images that have to be fetched will cause the elements around them to shift while the image is being retrieved. You can see that happening in the example above.
• Reloading is still a page load. Or at least, a GET. If you’re reloading something big and complex every second, it can end up being expensive.

The Bottom Line

Simply put, the Reload function (as well as the other functions contained in the MindTouch.Deki.js file) is an easy way to make your MindTouch-developed applications look and behave in a polished and professional manner. Used in the right way, it is a fast and powerful tool that helps to bring your web app to life.