= Example 4: a more complex application =

In this application, volunteers locate fossils in images of desert terrain.
They can locate several (zero or more) fossils in the same image,
and can associate a type and a comment with each annotation.
They can remove existing annotations.
When they're all done, they click a "Done" button.

This is implemented as a sequence of web pages;
each addition or deletion of an annotation goes to a new web page.
Hence, in addition to the '''job_show()''' callback function,
the application uses a separate web page, '''user/bossa_example4.php''',
that handles the edit operations.

The application is implemented by three scripts in ~/projects/test/html/:

 * [source:/trunk/boinc/html/ops/bossa_example4_make_jobs.php ops/bossa_example4_make_jobs.php]: a script that creates jobs.
 * [source:/trunk/boinc/html/inc/bossa_example4.inc inc/bossa_example4.inc]: the application's callback functions.
 * [source:/trunk/boinc/html/user/bossa_example4.php user/bossa_example4.php]: the handler for editing operations.

== Creating jobs ==

Using the administrative interface, create an application named "bossa_example4".
Create a directory '''~/projects/test/html/user/example4_images'''.
Put some images (.png or .jpg) there; some sample images are in
http://isaac.ssl.berkeley.edu/test/example4_images/

Now go to the project's ops/ directory and type

{{{
php bossa_example4_make_jobs.php --dir example4_images
}}}

== Opaque data ==

The application uses the following opaque data:

 * Jobs
{{{
path: the name of image file
}}}
 * Instances
{{{
features: an array of structures, each containing:

x: the X coordinate of the center
y: the Y coordinate of the center
type: the feature type (Tooth, Skull, Other)
comment: the user-supplied comment
}}}

== Callback functions ==

The '''job_show()''' function displays the image and overlays
existing annotations.
Each one is shown as a box with an "info" button
(which pops up the type and comment)
and a "delete" button linked to the edit page.

The image is an input item in a form linked to the edit page,
so that clicks on the image produce a new annotation.
Javascript is used to require that a feature type be selected
in order for the annotation to be accepted.

The "Done" button is linked to '''bossa_job_finished.php'''.

== The edit handler ==

The edit handler is invoked with the following GET arguments:

 * '''bji''': the ID of the instance
 * '''action''': "add", "delete", or "" (to display the image)
 * '''pic_x''' and '''pic_y''' (if action is "add")

The code is as follows.
The first two functions add and delete annotations;
each one ends by redirecting to the same page with no "action" argument;
this will redisplay the image with the new set of annotations.
{{{
     7  function handle_add($job, $inst) {
     8      $f = null;
     9      $f->x = get_int('pic_x');
    10      $f->y = get_int('pic_y');
    11      $f->type = get_str('type');
    12      $c = get_str('comment', true);
    13      if (strstr($c, "(optional)")) $c = "";
    14      $f->comment = $c;
    15      $output = $inst->get_opaque_data();
    16      $output->features[] = $f;
    17      $inst->set_opaque_data($output);
    18      header("location: bossa_example4.php?bji=$inst->id");
    19  }
    20
    21  function handle_delete($job, $inst, $index) {
    22      $output = $inst->get_opaque_data();
    23      $features = $output->features;
    24      array_splice($features, $index, 1);
    25      $output->features = $features;
    26      $inst->set_opaque_data($output);
    27      header("location: bossa_example4.php?bji=$inst->id");
    28  }
}}}

The main part of the script is as follows.
First, we get the instance ID and call a Bossa API function
to get the job, instance, and user:
{{{
    30  $bji = get_int("bji");
    31  if (!bossa_lookup_job($bji, $job, $inst, $u)) {
    32      error_page("No such instance");
    33  }
}}}
Then we verify that this instance belongs to the logged-in user:
{{{
    34  $user = get_logged_in_user();
    35  if ($u->id != $user->id) {
    36      error_page("Not your job");
    37  }
}}}
Then we perform the operation (or show the image with existing annotations):
{{{
    39  $action = get_str("action", true);
    40  switch ($action) {
    41  case "add":
    42      handle_add($job, $inst);
    43      break;
    44  case "delete":
    45      $index = get_int("index");
    46      handle_delete($job, $inst, $index);
    47      break;
    48  default:
    49      job_show($job, $inst, $user);
    50      break;
    51  }
    52
    53  ?>
}}}