NAME

Dancer2::Plugin::ProgressStatus

DESCRIPTION

Records and fetches progress entries.

This module allows your route to start a progress status meter and update it whilst your long running task is in progress. How you break up the running task is up to you.

Whilst the long running task is in progress, an AJAX GET request can be made to /_progress_status/:name to fetch JSON serialized data representing the progress status that matches :name

WebServer Dependencies:

This progress module does not depend on an event loop based webserver such as Twiggy as the long running request and the query to fetch the progress can be issued entirely separately.

It does currently depend on: 1. More than one worker process running to enable the handling of multiple requests at the same time

2. The webserver being hosted on one machine and uses local file storage for the progress data and as such is probably not suitable for a production environment at this time.

SYNOPSIS

get '/route' => sub {
  my $progress = start_progress_status({ name => 'progress1', total => 100 });
  while($some_condition) {
      # .. do some slow running stuff
      $progress++; # add's one to the progress
      $progress->add_message('an update message');
  }

  // $progress goes out of scope here and automatically ends the progress meter
};

Then with some javascript on the front end, something like this:

function checkProgress() {
    $.getJSON('/_progress_status/progress1', function(data) {
       if ( !data.in_progress ) {
          console.log("Finished progress1");
          return;
       }
       setTimeout(function() {
          checkProgress,
          3000
       });
    })
}

CONFIG

plugins:
  ProgressStatus:
    dir: "/tmp/dancer_progress"

The only plugin setting currently understood is where to store the progress data. This is required. If the directory does not exist, it will be created.

SEE ALSO

Dancer2

METHODS

start_progress_status

my $prog = set_progress_status({ name => "MyProgressStatus" });

Registers a new progress status for this session and automatically creates a route for returning data about the progress status.

Returns a progress object that you can use to set the progress. e.g.

$prog++;
$prog->add_message();
$prog->increment(10);

If an existing progress status with this name already exists and is currently in progress this call will die without affecting the original status. Either wrap this in an eval, use "is_progress_running" in Dancer2::Plugin::ProgressStatus or ensure by some other means that two progress meters don't start at the same time.

The route for querying the progress status is defined as:

GET /_progress_status/:name

It returns a JSON serialized structure something like:

{
  total: 100,
  count: 20,
  messages: [ "array of messages" ],
  in_progress: true
  status: 'some status message'
}

When the progress object goes out of scope in_progress is automatically set to false.

set_progress_status takes a name (required), a total (defaults to 100) a count (defaults to 0), and messages an optional arrayref of message strings.

is_progress_running

my $bool = is_progress_running($name);

Returns true if there is a running progress by this name. "start_progess_status" in Dancer2::Plugin::ProgressStatus dies if two progress meters with the same name start at the same time so this can be used to confirm without catching the start call in an eval.