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/:

• ops/bossa_example4_make_jobs.php: a script that creates jobs.
• inc/bossa_example4.inc: the application's callback functions.
• 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  ?>