snap-extras-0.12.3.0: A collection of useful helpers and utilities for Snap web applications.

Safe HaskellNone
LanguageHaskell2010

Snap.Extras.PollStatus

Contents

Description

This module provides infrastructure for polling the status of processes that run longer than a single request-response lifecycle. To do this, we issue AJAX calls at regular intervals to a route that updates the status on the page. There are two main components necessary to use this library: splices and a handler.

The handler is a simple jobStatusHandler function. Typically you'll add it to your site's list of routes like this:

route [ ...
      , ("myJobStatus", jobStatusHandler "statusTemplate" ".statusDiv")
      , ...
      ]

The first argument to jobsHandler is the template that will be rendered for status update requests. It will typically be not much more than a <myJobStatus> tag enclosing the custom markup for displaying your job status. Here's an example using a bootstrap progress bar:

<myJobStatus interval="300">
  <ifRunning>
    <elapsedSeconds/> seconds elapsed

    <div class="progress">
      <div class="progress-bar progress-bar-striped active"  role="progressbar"
           aria-valuenow="${amountCompleted}" aria-valuemin="0"
           aria-valuemax="${amountTotal}" style="width: ${percentCompleted}%">
        <percentCompleted/>%
      </div>
    </div>

  </ifRunning>
  <ifFinished>
    <div class="progress">
      <div class="progress-bar progress-bar-striped"  role="progressbar"
           aria-valuenow="${amountCompleted}" aria-valuemin="0"
           aria-valuemax="${amountTotal}" style="width: ${percentCompleted}%">
        <percentCompleted/>%
      </div>
    </div>
  </ifFinished>
</myJobStatus>

This will poll for updates every 300 milliseconds. See the documentation for statusSplice for more details.

To get the above code working, you would have the myJobStatusPage handler return markup that contains something like this:

<h1>Status</h1>
<div class="statusdiv col-md-4">
  <apply template="statusTemplate"/>
</div>

You will also need to bind the main splice provided by this module.

splices = do
    ...
    "myJobStatus" MS.## statusSplice splices getUrl getMyJobStatus isFinished

You need to bind this splice once for each type of action that you are polling, each with its own splice name and function for getting the job status.

Synopsis

Documentation

jobStatusHandler Source #

Arguments

:: HasHeist b 
=> ByteString

Name of the template to use for the updateStatus endpoint.

-> Text

A CSS selector string used to substitute the contents of the AJAX template into the status page.

-> Handler b v () 

Top-level handler that handles the job polling infrastructure.

statusSplice Source #

Arguments

:: Monad n 
=> Splices (RuntimeSplice n status -> Splice n)

Splices defined for your job status type status.

-> n (Maybe Text)

Handler to get the URL that should be used for requesting AJAX status updates. This must be a handler because it will usually contain some form of job ID that is only obtainable at runtime.

-> n (Maybe status)

Handler that knows how to get the status of the job in question. This typically will require it to know how to get some sort of job ID from the request.

-> (status -> Bool)

A function to tell whether the status is finished

-> Splice n 

Function to generate a status splice. This splice makes the following splices available to its children:

Conditional splices: ifPending, ifRunning, ifNotFinished, ifFinished, ifFinishedSuccess, ifFinishedFailure

Data splices: elapsedSeconds, startTime, endTime, jobState, messages, percentCompleted, amountCompleted, amountTotal

Generic Status Type

jobFinished :: JobState -> Bool Source #

Returns a bool indicating whether the job is finished.

statusFinished :: Status -> Bool Source #

Returns a bool indicating whether the job is finished.

data Status Source #

The complete status of a job.

Instances
Eq Status Source # 
Instance details

Defined in Snap.Extras.PollStatus

Methods

(==) :: Status -> Status -> Bool #

(/=) :: Status -> Status -> Bool #

Show Status Source # 
Instance details

Defined in Snap.Extras.PollStatus

statusPercentCompleted :: Status -> Int Source #

Calculates the percent completed as an Int.

statusSplices :: Monad n => Splices (RuntimeSplice n Status -> Splice n) Source #

The status splices