[Developers] mjt

[Nick Thompson]

Dae Park wrote:
 > I am trying to do a generic topic viewer using mjt but using a
 > specialized web service other than the mjt.mqlread. This web service I
 > am writing myself and will support the callback= paramater. My question
 > is how do I then invoke that web service using the <div mjt.task=... />
 > framework?

good question.  long answer =).

there's an example of doing this for one of the yahoo apis,
but i now see it's out of date, eek!
   http://mjtemplate.org/examples/yahoo/imagesearch.html
i'll fix this in the next push to the website, but for now the best
code to start from is probably these three functions in mjt.js:
  mjt.BlobGetTask(...)
  mjt.BlobGetTask.prototype.enqueue()
  mjt.parse_metaweb_script_response(task, envelope)


general doc:

i'm not that happy with the api for extending tasks, i'd
appreciate any comments or suggestions.  generally you
need to implement three functions for each task:

1. MyTask(...) is the constructor.  it should start with
     mjt.Task.apply(this);
    and it can be invoked with <div mjt.task="tsk">new MyTask(...)</div>

2. MyTask.prototype.enqueue() invokes the web service
    mjt will call this when it needs to run the
    task: this should invoke your web service by whatever means needed.
    mjt has some convenience functions that you'll probably want to use
    for a json/callback= service, you can copy much of mjt.BlobGetTask.

    the enqueue() function must also set up a callback for when the
    request completes or times out.

3. when the service responds, the callback must translate the response into
    the mjt task format.  in mjt.BlobGetTask this is done with an auxillary
    function, mjt.parse_metaweb_script_response(task, envelope).  this function
    distinguishes between timeout, error, and successful responses.

the response handler is definitely the complicated part, because it has
to fold several kinds of responses together:
    1. successful service response (service-specific format)
    2. service errors (service-specific format)
    3. mjt or network layer errors like timeouts or http errors

number 3 is not very well-defined unfortunately - the mjt task
format started as a variation on the mqlread envelope, but things
have drifted a bit and need to be rationalized.  here are the current
rules:

  task.state MUST be a string, one of 'init', 'wait', 'ready' or 'error'.
     the response handler should set it to either 'ready' or 'error'

  if task.state == 'ready', task.result should contain the result or
     results from the web service.

  if task.state == 'error',  task.messages should be an
     array of message objects:
         task = {
             state: 'error',
             messages: [{
                 type: '...',
                 text: '...'
             }]
         }

for some services it makes sense to have an empty result trigger
state 'error', in other cases this might be considered 'ready'.

the message object format will definitely evolve.  you can use
a service-specific error format if you want, but you'll have to
translate mjt level errors into that format.  or, you can translate
the service-specific errors into something more like the existing
freebase mjt services, which might be nicer if you want to enable
mash-ups with your service but would require more code in your
response handler.

settling on a format for results and messages would simplify this
description, but i haven't had enough experience with it yet.
hopefully i can re-use some of the design that's been done on
defining the envelopes for the freebase service.

     nick