WashNGo-2.12.0.1: WASH is a family of EDSLs for programming Web applications in Haskell.

WASH.CGI.CGIXX

Contents

Description

One stop shop for the WASH/CGI library. All high-level scripts should get along with importing just this module. Low-level scripts may have to import RawCGI. This version requires features beyond Haskell98, in particular multi parameter type classes and existential types.

Synopsis

Basics

data CGI a Source

Instances

ask :: CGIMonad cgi => WithHTML x cgi a -> cgi ()Source

Takes a monadic value that constructs a HTML page and delivers this page to the browser. This page may contain forms and input widgets.

tell :: (CGIMonad cgi, CGIOutput a) => a -> cgi ()Source

Terminates script by sending its argument to the browser.

io :: (Read a, Show a) => IO a -> CGI aSource

Safe embedding of an IO action into the CGI monad. Intentionally not parameterized ver its monad to avoid its use inside of transactions.

run :: CGI () -> IO ()Source

Turns a CGI action into an IO action. Used to turn the main CGI action into the main function of the program. Typical use:

 main = run mainCGI

once :: (CGIMonad cgi, Read a, Show a) => cgi a -> cgi aSource

Brackets a CGI action so that only its result is visible. Improves efficiency by not executing the bracketed action after it has been performed once. Use this for avoiding the inefficient buildup of long interaction logs.

forever :: CGIMonad cgi => cgi () -> cgi ()Source

Repeats a CGI action without saving its state so that the size of the interaction log remains constant.

htell :: CGIMonad cgi => WithHTML x IO () -> cgi aSource

Terminate script by sending a HTML page constructed by monadic argument.

askOffline :: CGIMonad cgi => WithHTML x cgi a -> (Element -> IO ()) -> cgi ()Source

Like ask, but passes the constructed HTML page to the elementAction parameter. This function may send the page via Email or store it into a file. Anyone loading this page in a browser can resume the interaction.

Links and Images

internalImageSource

Arguments

:: CGIMonad cgi 
=> FreeForm

the raw image

-> String

alternative text

-> WithHTML x cgi Image 

Reference to internal image.

externalImageSource

Arguments

:: CGIMonad cgi 
=> URL

URL of image

-> String

alternative text

-> WithHTML x cgi Image 

Reference to image by URL.

makeImg :: Monad cgi => Image -> HTMLField cgi x y ()Source

Create an inline image.

makeRefSource

Arguments

:: (CGIMonad cgi, Monad m) 
=> String

internal name of entity

-> WithHTML x m ()

body of the reference

-> cgi (WithHTML y m ()) 

Create a hyperlink to internal entity.

makeA :: CGIMonad cgi => String -> String -> HTMLField cgi x y ()Source

Create hyperlink to internal entity /path?name.

backLink :: Monad m => HTMLCons x y m ()Source

Link to previous page in browser's history. Uses JavaScript.

hlink :: Monad m => URL -> HTMLCons x y m ()Source

Plain Hyperlink from an URL string.

Forms and Widgets

type HTMLField cgi x y a = WithHTML x cgi () -> WithHTML y cgi aSource

Every input widget maps the content generator for the widget (which may produce HTML elements or attributes) to the content generator of the widget.

Form Creation

makeForm :: CGIMonad cgi => WithHTML x cgi a -> WithHTML y cgi ()Source

Wraps an HTML form around its arguments. All standard attributes are computed and need not be supplied explicitly.

standardQuery :: CGIMonad cgi => String -> WithHTML x cgi a -> cgi ()Source

Convenient workhorse. Takes the title of a page and a monadic HTML value for the contents of the page. Wraps the contents in a form so that input fields and buttons may be used inside.

Form Submission

submit :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> cgi ()) -> HTMLField cgi x y ()Source

submit0 :: CGIMonad cgi => cgi () -> HTMLField cgi x y ()Source

create a continuation button with parameters

defaultSubmit :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> cgi ()) -> HTMLField cgi x y ()Source

create a submission button with attached action

resetField :: CGIMonad cgi => HTMLField cgi x y (InputField () INVALID)Source

Creates a reset button that clears all fields of a form.

activeInputFieldSource

Arguments

:: (CGIMonad cgi, Reason a, Read a) 
=> (a -> cgi ())

Function that maps input data to a CGI action.

-> HTMLField cgi x y () 

Creates an input field that submits the field to the browser when data is entered into this field.

activate :: (CGIMonad cgi, StripHandle ha a) => (a -> cgi ()) -> HTMLField cgi x y ha -> HTMLField cgi x y haSource

Attach a CGI action to the value returned by the input field. Activation means that data is submitted as soon as it is entered.

submitx :: DTree cgi x y -> HTMLField cgi x y ()Source

submission with staged validation

data DTree cgi x y Source

dtleaf :: CGIMonad cgi => cgi () -> DTree cgi x ySource

dtnode :: (CGIMonad cgi, StripHandle handle_a a) => handle_a -> (a -> DTree cgi x y) -> DTree cgi x ySource

Textual Input

inputField :: (CGIMonad cgi, Reason a, Read a) => HTMLField cgi x y (InputField a INVALID)Source

Create a textual input field. Return type can be *anything* in class Reason and Read.

textInputField :: CGIMonad cgi => HTMLField cgi x y (InputField String INVALID)Source

Create a textual input field that returns the string entered. (Avoids having to put quotes around a string.)

checkedTextInputField :: CGIMonad cgi => (Maybe String -> Maybe String) -> HTMLField cgi x y (InputField String INVALID)Source

Creates a textual input field that takes a custom validation function.

passwordInputField :: (CGIMonad cgi, Reason a, Read a) => HTMLField cgi x y (InputField a INVALID)Source

Like inputField but the characters are not echoed on the screen.

makeTextarea :: CGIMonad cgi => String -> HTMLField cgi x y (InputField String INVALID)Source

Create a text area with a preset string.

Checkbox

checkboxInputField :: CGIMonad cgi => HTMLField cgi x y (InputField Bool INVALID)Source

Creates a checkbox. Returns True if box was checked.

Button

makeButton :: CGIMonad cgi => HTMLField cgi x y (InputField Bool INVALID)Source

Create a single button.

radioGroup :: (CGIMonad cgi, Read a) => WithHTML x cgi (RadioGroup a INVALID)Source

Create a handle for a new radio group. This handle is invisible on the screen!

radioButton :: (Show a, Monad cgi) => RadioGroup a INVALID -> a -> HTMLField cgi x y ()Source

Create a new radio button and attach it to an existing RadioGroup.

radioError :: CGIMonad cgi => RadioGroup a INVALID -> WithHTML x cgi ()Source

Create and place the error indicator for an existing RadioGroup. Becomes visible only if no button of a radio group is pressed.

Image

imageField :: CGIMonad cgi => Image -> HTMLField cgi x y (InputField (Int, Int) INVALID)Source

Create an input field from an image. Returns (x,y) position clicked in the image.

Selection Box

selectMultipleSource

Arguments

:: (CGIMonad cgi, Eq a) 
=> (a -> String)

function to display values of type a

-> [a]

list of preselected entries

-> [a]

list of all possible entries

-> (Int, Int)

(min, max) number of fields that must be selected

-> HTMLField cgi x y (InputField [a] INVALID) 

Create a selection box where multiple entries can be selected.

selectSingleSource

Arguments

:: (CGIMonad cgi, Eq a) 
=> (a -> String)

function to display values of type a

-> Maybe a

optional preselected value

-> [a]

list of all possible values

-> HTMLField cgi x y (InputField a INVALID) 

Create a selection box where exactly one entry can be selected.

selectBounded :: (CGIMonad cgi, Enum a, Bounded a, Read a, Show a, Eq a) => Maybe a -> HTMLField cgi x y (InputField a INVALID)Source

Selection box for elements of a Bounded type. Argument is the optional preselected value.

File

fileInputField :: CGIMonad cgi => HTMLField cgi x y (InputField FileReference INVALID)Source

Creates a file input field. Returns a temporary FileReference. The fileReferenceName of the result is *not* guaranteed to be persistent. The application is responsible for filing it away at a safe place.

checkedFileInputField :: CGIMonad cgi => (Maybe FileReference -> Maybe FileReference) -> HTMLField cgi x y (InputField FileReference INVALID)Source

Creates a file input field. Like fileInputField but has an additional parameter for additional validation of the input.

Handle Manipulation

Attribute Shortcuts

fieldSIZE :: Monad m => Int -> WithHTML x m ()Source

Create a SIZE attribute from an Int.

fieldMAXLENGTH :: Monad m => Int -> WithHTML x m ()Source

Create a MAXLENGTH attribute from an Int.

fieldVALUE :: (Monad m, Show a) => a -> WithHTML x m ()Source

Create a VALUE attribute from any Showable.

Advanced

Installing Translators

runWithHook :: CGIOptions -> ([String] -> CGI ()) -> CGI () -> IO ()Source

Variant of run where an additional argument cgigen specifies an action taken when the script is invoked with a non-empty query string as in script-name?query-string

docTranslator :: [FreeForm] -> ([String] -> CGI ()) -> [String] -> CGI ()Source

A translator is a function [String] -> CGI (). It takes the query string of the URL (of type [String]) and translates it into a CGI action. docTranslator docs next takes a list of FreeForm documents and a next translator. It tries to select a document by its ffName and falls through to the next translator if no document matches.

lastTranslator :: [String] -> CGI ()Source

Terminates a sequence of translators.

Outputable Stuff

data Status Source

Constructors

Status 

Fields

statusCode :: Int

status code

statusReason :: String

reason phrase

statusContent :: Maybe (WithHTML () IO ())

more explanation

Instances

newtype Location Source

Constructors

Location URL

redirection

Instances

data FreeForm Source

Constructors

FreeForm 

Fields

ffName :: String

internal name

ffContentType :: String

MIME type

ffRawContents :: String

contents as octet stream

Instances

Predefined Types for Input Fields

newtype Text Source

Arbitrary string data. No quotes required.

Constructors

Text 

Fields

unText :: String
 

Instances

newtype NonEmpty Source

Non-empty strings.

Constructors

NonEmpty 

Fields

unNonEmpty :: String
 

newtype AllDigits Source

Non-empty strings of digits.

Constructors

AllDigits 

Fields

unAllDigits :: String
 

newtype EmailAddress Source

Reads an email address according to RFC 2822

Constructors

EmailAddress 

newtype CreditCardNumber Source

Reads a credit card number and performs Luhn check on it.

data CreditCardExp Source

Reads credit card expiration dates in format /.

Constructors

CreditCardExp 

Fields

cceMonth :: Int
 
cceYear :: Int
 

Lowlevel Options

data CGIOption Source

Constructors

NoPort

do not include port number in generated URLs

AutoPort

include automatically generated port number in generated URLs (default)

Port Int

use this port number in generated URLs

NoHttps

do not attempt to detect Https

AutoHttps

autodetect Https by checking for port number 443 and env var HTTPS (default)

FullURL

generate full URL including scheme, host, and port

PartialURL

generate absolute path URL, only (default)

SessionMode 

Servlets

makeServlet :: CGI () -> CGIProgramSource

Transform a CGI action into a servlet suitable for running from Marlow's web server.

makeServletWithHook :: ([String] -> CGI ()) -> CGI () -> CGIProgramSource

Like makeServlet with additional CGI generator as in runWithHook.

HTML and Style

Experimental Stuff

data FrameSet Source

Abstract data type of frame set generators.

data FrameLayout Source

Overall layout of a frame set: row-wise or column-wise.

Constructors

ROWS 
COLS 

Instances

data FrameSpacing Source

Division of space between elements of a frameset. See http://wp.netscape.com/assist/net_sites/frame_syntax.html

Constructors

FrameAbsolute Int

in pixels

FrameRelative Int

the * format

FramePercent Int

the % format

Instances

makeFrameSource

Arguments

:: CGIMonad cgi 
=> WithHTML x IO ()

additional attributes to frame

-> cgi ()

contents of the frame

-> cgi FrameSet

returns HTML generator for the frame

Create a single frame. Returns the assigned name of the frame.

makeFrameset :: CGIMonad cgi => FrameLayout -> [(FrameSpacing, cgi FrameSet)] -> cgi FrameSetSource

Create a frameset, given a layout, its spacing, and its subframe(set)s.

framesetPage :: CGIMonad cgi => String -> cgi FrameSet -> cgi ()Source

Required wrapper for pages with frames. Takes a title and a FrameSet generator and displays the page.