Library for constructing static and dynamic HTML pages. The PADL 2001 paper contains a description of the basic ideas behind an old version of this library. The structure and ideas of the current library are described in the PADL 2021 paper.
An application written with this library can be transformed into a cgi script by the command
curry2cgi -m mainPage -o /home/joe/cgi-bin/prog.cgi Prog
where Prog
is the name of the Curry program with
the cgi script, /home/joe/cgi-bin/prog.cgi
is
the desired location of the
compiled cgi script, and mainPage
is the Curry expression
(of type IO HtmlPage
) computing the HTML page (where cypm
is the command calling the Curry Package Manager).
Exported Datatypes: Attrs, BaseHtml, CookieParam, FormReader, HtmlEnv, HtmlExp, HtmlFormDef, HtmlHandler, HtmlPage, HtmlRef, PageParam, StaticHtml
Exported Functions: addAttr, addAttrs, addClass, addCookies, addHttpHeader, addPageBody, addPageParam, address, anchor, answerEncText, answerText, blink, block, blockstyle, bold, breakline, button, center, checkBox, checkedBox, code, coordinates, defaultEncoding, dlist, emphasize, expires, footer, formatCookie, formDef, formDefId, formDefRead, formDefView, formDefWithID, formElem, formElemWithAttrs, fromFormReader, fromHtmlExp, fromStaticHtml, getCookies, getUrlParameter, h1, h2, h3, h4, h5, h6, headedTable, header, headerPage, hempty, hiddenField, href, hrule, hStruct, htmlIsoUmlauts, htmlPrelude, htmlQuote, htmlTagAttrs, htxt, htxts, idOfHtmlRef, image, imageButton, inline, instHtmlRefs, italic, litem, multipleSelection, nav, nbsp, olist, olistWithClass, olistWithItemClass, page, pageBodyAttr, pageCookie, pageCSS, pageEnc, pageLinkInfo, pageMetaInfo, par, password, pre, radioMain, radioMainOff, radioOther, redirectPage, resetButton, section, selection, selectionInitial, setFormDefId, showBaseHtmls, showHtml, showHtmlPage, showHtmls, showStaticHtmls, simpleFormDef, simpleFormDefWithID, strong, style, styleSheet, table, tableWithClass, teletype, textArea, textField, textOf, textstyle, toFormReader, toHtmlExp, toStaticHtml, ulist, ulistWithClass, ulistWithItemClass, verbatim
Exported Classes: HTML
type Attrs
= [(String, String)]
The attributes for HTML structures consists of a list of name/value pairs.
data BaseHtml
The data type to represent static HTML expressions in web scripts.
Constructors:
BaseText
:: String -> BaseHtml
s - a text string without any further structure
BaseStruct
:: String -> Attrs -> [BaseHtml] -> BaseHtml
t as hs - a structure with a tag, attributes, and HTML expressions inside the structure
BaseAction
:: (IO HtmlExp) -> BaseHtml
act - an action that computes a general HTML expression which will be inserted when the HTML document is shown (used to implement form expressions)
Known instances:
data StaticHtml
The data type to represent static HTML expressions which can be
persistently stored, e.g., read from or written into files.
It is similar to type BaseHtml
except that there
is no constructor BaseAction
so this type has instances
for standard classes like Eq
, Data
, Read
, and Show
.
Constructors:
HText
:: String -> StaticHtml
s - a text string without any further structure
HStruct
:: String -> Attrs -> [StaticHtml] -> StaticHtml
t as hs - a structure with a tag, attributes, and HTML expressions inside the structure
Known instances:
data HtmlRef
The (abstract) data type for representing references to input elements in HTML forms.
type HtmlEnv
= HtmlRef -> String
The type for representing cgi environments, i.e., mappings from cgi references to the corresponding values of the input elements.
type HtmlHandler
= HtmlEnv -> IO HtmlPage
The type of event handlers occurring in HTML forms.
data HtmlExp
The data type for representing HTML expressions with input elements, i.e., all elements which might occur inside a form.
Constructors:
HtmlText
:: String -> HtmlExp
s - a text string without any further structure
HtmlStruct
:: String -> Attrs -> [HtmlExp] -> HtmlExp
t as hs - a structure with a tag, attributes, and HTML expressions inside the structure
HtmlAction
:: (IO HtmlExp) -> HtmlExp
act - an action that computes an HTML expression which will be inserted when the HTML document is shown (used to implement form expressions)
HtmlInput
:: HtmlRef -> HtmlExp -> HtmlExp
ref h - an input element (described by the second argument) with a cgi reference
HtmlEvent
:: HtmlRef -> HtmlHandler -> HtmlExp -> HtmlExp
h ref hdlr - an input element (first arg) identified by a cgi reference with an associated event handler (typically, a submit button)
Known instances:
data FormReader a
The type FormReader
is a monad with operations to read data
to invoke an HTML form.
It is assumed that a FormReader
action reads only data and does not
change the environment, since the action is applied twice
when executing a form.
A typical action of this kind is HTML.Session.getSessionData
.
The FormReader
type encapsulates IO actions in order to enforce
the correct use of forms.
Known instances:
data HtmlFormDef a
The data type for representing HTML forms embedded into HTML pages.
A form definition consists of a unique identifier of form (usually,
the qualified name of the operation defining the form),
a FormReader
action and a mapping from data
into an HTML expression (which usually contains event handlers
to produce the form answers).
data HtmlPage
The data type for representing HTML pages. Since the HTML document shown in this page is a base HTML expression, it is ensured that input elements and event handlers occur only in embedded forms.
Constructors:
HtmlPage
:: String -> [PageParam] -> [BaseHtml] -> HtmlPage
t ps hs - an HTML page with title t, optional parameters (e.g., cookies) ps, and contents hs
HtmlAnswer
:: String -> String -> HtmlPage
t c - an answer in an arbitrary format where t is the content type (e.g., "text/plain") and c is the contents
data PageParam
The possible parameters of an HTML page.
The parameters of a cookie (PageCookie
) are its name and value and
optional parameters (expiration date, domain, path (e.g., the path "/"
makes the cookie valid for all documents on the server), security) which
are collected in a list.
Constructors:
PageEnc
:: String -> PageParam
the encoding scheme of this page
PageCookie
:: String -> String -> [CookieParam] -> PageParam
name value params - a cookie to be sent to the client's browser
PageCSS
:: String -> PageParam
s - a URL for a CSS file for this page
HttpHeader
:: String -> String -> PageParam
key value - additional HTTP header included in this page
PageJScript
:: String -> PageParam
s - a URL for a Javascript file for this page
PageMeta
:: [(String, String)] -> PageParam
as - meta information (in form of attributes) for this page
PageLink
:: [(String, String)] -> PageParam
as - link information (in form of attributes) for this page
PageHeadInclude
:: BaseHtml -> PageParam
he - HTML expression to be included in page header
PageBodyAttr
:: (String, String) -> PageParam
attr - optional attribute for the body element of the page (more than one occurrence is allowed)
data CookieParam
The possible parameters of a cookie.
Constructors:
CookieExpire
:: ClockTime -> CookieParam
CookieDomain
:: String -> CookieParam
CookiePath
:: String -> CookieParam
CookieSecure
:: CookieParam
The default encoding used in generated HTML documents.
Basic text as an HTML expression. The text may contain special HTML chars (like <,>,&,") which will be quoted so that they appear as in the parameter string.
htxts
:: HTML a => [String] -> [a]
A list of strings represented as a list of HTML expressions. The strings may contain special HTML chars that will be quoted.
hStruct
:: HTML a => String -> [a] -> a
An HTML structure with a given tag and no attributes.
fromStaticHtml
:: HTML a => StaticHtml -> a
Transforms a StaticHtml
expression into a generic HTML expression.
toStaticHtml
:: BaseHtml -> StaticHtml
Transforms a BaseHtml
expression into a StaticHtml
expression
provided that BaseAction
constructors do not occur (otherwise,
an error is raised).
idOfHtmlRef
:: HtmlRef -> String
Internal identifier of a HtmlRef (intended only for internal use in other libraries!).
toHtmlExp
:: BaseHtml -> HtmlExp
Transforms a static into a dynamic HTML document.
fromHtmlExp
:: HtmlExp -> BaseHtml
Transforms a dynamic HTML into a static one by dropping references and event handlers.
textOf
:: HTML a => [a] -> String
Extracts the textual contents of a list of HTML expressions. For instance,
textOf [BaseText "xy", BaseStruct "a" [] [BaseText "bc"]] == "xy bc"
fromFormReader
:: FormReader a -> IO a
Transforms a FormReader
action into a standard IO action.
toFormReader
:: IO a -> FormReader a
Transforms an IO action into a FormReader
action.
This operation should be used with care since it must be
ensured that the action only reads data and does not
change the environment, since the action is applied twice
when executing a form.
simpleFormDef
:: [HtmlExp] -> HtmlFormDef ()
A definition of a simple form which does not require session data.
The unique identifier required for the implementation of forms
is added by the curry2cgi
translator.
simpleFormDefWithID
:: String -> [HtmlExp] -> HtmlFormDef ()
A definition of a simple form, which does not require session data, with a unique identifier (usually, the qualified name of the operation defining the form).
formDef
:: FormReader a -> (a -> [HtmlExp]) -> HtmlFormDef a
A definition of a form which consists of a FormReader
action
and a mapping from data into an HTML expression
(which usually contains event handlers to produce the form answers).
It is assumed that the FormReader
action reads only data and does not
change it, since it is applied twice when executing a form.
The unique identifier required for the implementation of forms
is added by the curry2cgi
translator.
formDefWithID
:: String -> FormReader a -> (a -> [HtmlExp]) -> HtmlFormDef a
A definition of a form with a unique identifier (usually,
the qualified name of the operation defining the form).
A form contains a FormReader
action and a mapping from data
into an HTML expression (which usually contains event handlers
to produce the form answers).
It is assumed that the FormReader
action reads only data and does not
change it, since it is applied twice when executing a form.
formDefId
:: HtmlFormDef a -> String
Returns the identifier of a form definition.
setFormDefId
:: String -> HtmlFormDef a -> HtmlFormDef a
Sets the identifier of a form definition.
Only intended for internal use in the curry2cgi
translator.
formDefRead
:: HtmlFormDef a -> IO a
Returns the FormReader
action of a form definition.
formDefView
:: HtmlFormDef a -> a -> [HtmlExp]
Returns the view operation of a form definition.
instHtmlRefs
:: [HtmlExp] -> Int -> ([HtmlExp], Int)
Instantiates all HtmlRefs with a unique tag in HTML expressions. Only internally used. Parameters: HTML expressions, number for cgi-refs Result: translated HTML expressions, new number for cgi-refs
pageEnc
:: String -> PageParam
An encoding scheme for a HTML page.
pageCookie
:: (String, String) -> PageParam
A cookie to be sent to the client's browser when a HTML page is requested.
pageCSS
:: String -> PageParam
A URL for a CSS file for a HTML page.
pageMetaInfo
:: [(String, String)] -> PageParam
Meta information for a HTML page. The argument is a list of
attributes included in the meta
-tag in the header for this page.
pageLinkInfo
:: [(String, String)] -> PageParam
Link information for a HTML page. The argument is a list of
attributes included in the link
-tag in the header for this page.
pageBodyAttr
:: (String, String) -> PageParam
Optional attribute for the body element of the web page. More than one occurrence is allowed, i.e., all such attributes are collected.
page
:: String -> [BaseHtml] -> HtmlPage
A basic HTML web page with the default encoding.
:: String
|
the title of the page |
-> [BaseHtml]
|
the page's body (list of HTML expressions) |
-> HtmlPage
|
an HTML page |
headerPage
:: String -> [BaseHtml] -> HtmlPage
A standard HTML web page where the title is included in the body as the first header.
:: String
|
the title of the page |
-> [BaseHtml]
|
the page's body (list of HTML expressions) |
-> HtmlPage
|
an HTML page with the title as the first header |
addPageParam
:: HtmlPage -> PageParam -> HtmlPage
Adds a parameter to an HTML page.
:: HtmlPage
|
a page |
-> PageParam
|
a page's parameter |
-> HtmlPage
|
an HTML page |
addPageBody
:: HtmlPage -> [BaseHtml] -> HtmlPage
Adds a list of HTML expressions to the body of an HTML page.
:: HtmlPage
|
a page |
-> [BaseHtml]
|
HTML expressions added at the end of the page's body |
-> HtmlPage
|
an HTML page |
addCookies
:: [(String, String)] -> HtmlPage -> HtmlPage
Adds simple cookie to an HTML page. The cookies are sent to the client's browser together with this page.
:: [(String, String)]
|
the cookies as a list of name/value pairs |
-> HtmlPage
|
the form to add cookies to |
-> HtmlPage
|
a new HTML page |
addHttpHeader
:: String -> String -> HtmlPage -> HtmlPage
Adds a HTTP header to a HTML page. Headers are sent to the client's browser together with the page.
:: String
|
the name of the HTTP header field |
-> String
|
the value of the HTTP header field |
-> HtmlPage
|
the page to which the header is added |
-> HtmlPage
|
a new HTML page |
formatCookie
:: (String, String, [CookieParam]) -> String
answerText
:: String -> HtmlPage
A textual result instead of an HTML page as a result for active web pages.
:: String
|
the contents of the result page |
-> HtmlPage
|
an HTML answer page |
answerEncText
:: String -> String -> HtmlPage
A textual result instead of an HTML page as a result for active web pages where the encoding is given as the first parameter.
:: String
|
the encoding of the text(e.g., "utf-8" or "iso-8859-1") |
-> String
|
the contents of the result page |
-> HtmlPage
|
an HTML answer page |
redirectPage
:: String -> HtmlPage
Generates a redirection page to a given URL.
This is implemented via the HTTP response header Location
(see also
https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location
).
:: String
|
The URL target of the redirection |
-> HtmlPage
|
The redirection page |
expires
:: Int -> HtmlPage -> HtmlPage
Adds expire time to given HTML page.
:: Int
|
Number of seconds before document expires |
-> HtmlPage
|
The page to add the header information to |
-> HtmlPage
|
An empty HTML expression.
Non breaking Space
Header 1
Header 2
Header 3
Header 4
Header 5
Header 6
Paragraph
Section
Header
Footer
emphasize
:: HTML a => [a] -> a
Emphasize
Strong (more emphasized) text.
Boldface
Italic
Navigation
Program code
Centered text
Blinking text
teletype
:: HTML a => [a] -> a
Teletype font
Unformatted input, i.e., keep spaces and line breaks and don't quote special characters.
verbatim
:: HTML a => String -> a
Verbatim (unformatted), special characters (<,>,&,") are quoted.
Address
href
:: HTML a => String -> [a] -> a
Hypertext reference
anchor
:: HTML a => String -> [a] -> a
An anchored text with a hypertext reference inside a document.
Unordered list.
:: HTML a
|
|
=> [[h]]
|
the list items where each item is a list of HTML expressions |
-> h
|
ulistWithClass
:: HTML a => String -> String -> [[a]] -> a
An unordered list with classes for the entire list and the list elements. The class annotation will be ignored if it is empty.
:: HTML a
|
|
=> String
|
the class for the entire list structure |
-> String
|
the class for the list items |
-> [[h]]
|
the list items where each item is a list of HTML expressions |
-> h
|
ulistWithItemClass
:: HTML a => String -> [(String, [a])] -> a
An unordered list with classes for the entire list individual classes for the list elements. The class annotation will be ignored if it is empty.
:: HTML a
|
|
=> String
|
the class for the entire list structure |
-> [(String, [h])]
|
the list items together with their classes |
-> h
|
Ordered list.
:: HTML a
|
|
=> [[h]]
|
the list items where each item is a list of HTML expressions |
-> h
|
olistWithClass
:: HTML a => String -> String -> [[a]] -> a
An ordered list with classes for the entire list and the list elements. The class annotation will be ignored if it is empty.
:: HTML a
|
|
=> String
|
the class for the entire list structure |
-> String
|
the class for the list items |
-> [[h]]
|
the list items where each item is a list of HTML expressions |
-> h
|
olistWithItemClass
:: HTML a => String -> [(String, [a])] -> a
An ordered list with classes for the entire list individual classes for the list elements. The class annotation will be ignored if it is empty.
:: HTML a
|
|
=> String
|
the class for the entire list structure |
-> [(String, [h])]
|
the list items together with their classes |
-> h
|
A single list item (usually not explicitly used)
dlist
:: HTML a => [([a], [a])] -> a
Description list
:: HTML a
|
|
=> [([h], [h])]
|
a list of (title/description) pairs (of HTML expressions) |
-> h
|
table
:: HTML a => [[[a]]] -> a
Table with a matrix of items where each item is a list of HTML expressions.
tableWithClass
:: HTML a => String -> String -> String -> [[[a]]] -> a
Table with a matrix of items (each item is a list of HTML expressions) with classes for the entire table, each row, and each data element. The class annotation will be ignored if it is empty.
:: HTML a
|
|
=> String
|
the class for the entire table structure |
-> String
|
the class for the table rows |
-> String
|
the class for the table data items |
-> [[[h]]]
|
the matrix of table items where each item is a list of HTML expressions |
-> h
|
headedTable
:: HTML a => [[[a]]] -> a
Similar to table
but introduces header tags for the first row.
Horizontal rule
Break a line
image
:: HTML a => String -> String -> a
Image
:: HTML a
|
|
=> String
|
the URL of the image |
-> String
|
the alternative text shown instead of the image |
-> h
|
styleSheet
:: HTML a => String -> a
Defines a style sheet to be used in this HTML document.
:: HTML a
|
|
=> String
|
a string in CSS format |
-> h
|
style
:: HTML a => String -> [a] -> a
Provides a style for HTML elements.
The style argument is the name of a style class defined in a
style definition (see styleSheet
) or in an external
style sheet (see form and page parameters FormCSS
and PageCSS
).
:: HTML a
|
|
=> String
|
name of a style class |
-> [h]
|
list of HTML expressions |
-> h
|
textstyle
:: HTML a => String -> String -> a
Provides a style for a basic text. The style argument is the name of a style class defined in an external style sheet.
:: HTML a
|
|
=> String
|
name of a style class |
-> String
|
a string (special characters will be quoted) |
-> h
|
blockstyle
:: HTML a => String -> [a] -> a
Provides a style for a block of HTML elements. The style argument is the name of a style class defined in an external style sheet. This element is used (in contrast to "style") for larger blocks of HTML elements since a line break is placed before and after these elements.
:: HTML a
|
|
=> String
|
name of a style class |
-> [h]
|
list of HTML expressions |
-> h
|
Joins a list of HTML elements into a single HTML element. Although this construction has no rendering, it is sometimes useful for programming when several HTML elements must be put together.
:: HTML a
|
|
=> [h]
|
list of HTML expressions |
-> h
|
Joins a list of HTML elements into a block. A line break is placed before and after these elements.
:: HTML a
|
|
=> [h]
|
list of HTML expressions |
-> h
|
A hidden field to pass a value referenced by a fixed name. This function should be used with care since it may cause conflicts with the CGI-based implementation of this library.
formElem
:: HtmlFormDef a -> BaseHtml
A form embedded in an HTML expression.
The parameter is a form defined as an exported top-level operation
in the CGI program so that it can be accessed by the main program.
The URL of the generated form is the same as the main page, i.e.,
the current URL parameter is passed to the form (which is
useful for REST-based programming with URL parameters).
The form uses a hidden field named FORMID
to identify the form
in the submitted form controller.
Since form elements can not be nested, see HTML, the form element itself is a static HTML expression.
formElemWithAttrs
:: HtmlFormDef a -> [(String, String)] -> BaseHtml
A form element (see formElem) where some attributes are added
to the resulting HTML form
structure.
The attributes must be different from the standard form
attributes method
and action
.
button
:: String -> ((HtmlRef -> String) -> IO HtmlPage) -> HtmlExp
A button to submit a form with a label string and an event handler.
resetButton
:: String -> HtmlExp
Reset button with a label string
imageButton
:: String -> ((HtmlRef -> String) -> IO HtmlPage) -> HtmlExp
Submit button in form of an imag.
:: String
|
url of the image |
-> HtmlHandler
|
event handler |
-> HtmlExp
|
textField
:: HtmlRef -> String -> HtmlExp
Input text field with a reference and an initial contents
password
:: HtmlRef -> HtmlExp
Input text field (where the entered text is obscured) with a reference
textArea
:: HtmlRef -> (Int, Int) -> String -> HtmlExp
Input text area with a reference, height/width, and initial contents
checkBox
:: HtmlRef -> String -> HtmlExp
A checkbox with a reference and a value. The value is returned if checkbox is on, otherwise "" is returned.
checkedBox
:: HtmlRef -> String -> HtmlExp
A checkbox that is initially checked with a reference and a value. The value is returned if checkbox is on, otherwise "" is returned.
radioMain
:: HtmlRef -> String -> HtmlExp
A main button of a radio (initially "on") with a reference and a value. The value is returned of this button is on. A complete radio button suite always consists of a main button (radiomain) and some further buttons (radioothers) with the same reference. Initially, the main button is selected (or nothing is selected if one uses radiomainoff instead of radio_main). The user can select another button but always at most one button of the radio can be selected. The value corresponding to the selected button is returned in the environment for this radio reference.
radioMainOff
:: HtmlRef -> String -> HtmlExp
A main button of a radio (initially "off") with a reference and a value. The value is returned of this button is on.
radioOther
:: HtmlRef -> String -> HtmlExp
A further button of a radio (initially "off") with a reference (identical to the main button of this radio) and a value. The value is returned of this button is on.
selection
:: HtmlRef -> [(String, String)] -> HtmlExp
A selection button with a reference and a list of name/value pairs. The names are shown in the selection and the value is returned for the selected name.
selectionInitial
:: HtmlRef -> [(String, String)] -> Int -> HtmlExp
A selection button with a reference, a list of name/value pairs, and a preselected item in this list. The names are shown in the selection and the value is returned for the selected name.
:: HtmlRef
|
a CGI reference |
-> [(String, String)]
|
list of name/value pairs |
-> Int
|
the index of the initially selected item in the list nvs |
-> HtmlExp
|
an HTML expression representing the selection button |
multipleSelection
:: HtmlRef -> [(String, String, Bool)] -> HtmlExp
A selection button with a reference and a list of name/value/flag pairs.
The names are shown in the selection and the value is returned
if the corresponding name is selected. If flag is True, the
corresonding name is initially selected. If more than one name
has been selected, all values are returned in one string
where the values are separated by newline ([\n](#\n)
) characters.
Quotes special characters (<
,>
,&
,"
, umlauts) in a string
as HTML special characters.
htmlIsoUmlauts
:: String -> String
Translates umlauts in iso-8859-1 encoding into HTML special characters.
addAttr
:: HTML a => a -> (String, String) -> a
Adds an attribute (name/value pair) to an HTML element.
addAttrs
:: HTML a => a -> [(String, String)] -> a
Adds a list of attributes (name/value pair) to an HTML element.
addClass
:: HTML a => a -> String -> a
Adds a class attribute to an HTML element (if the class attribute is not empty).
showStaticHtmls
:: [StaticHtml] -> String
Transforms a list of static HTML expressions into its string representation (in the standard HTML syntax). Only included for compatibility.
showBaseHtmls
:: [BaseHtml] -> String
Transforms a list of basic HTML expressions into its string representation (in the standard HTML syntax). Only included for compatibility.
showHtmls
:: HTML a => [a] -> String
Transforms a list of HTML expressions into its string representation (in the standard HTML syntax).
showHtml
:: HTML a => a -> String
Transforms a single HTML expression into string representation.
showHtmlPage
:: HtmlPage -> String
Transforms HTML page into string representation.
:: HtmlPage
|
the HTML page |
-> String
|
string representation of the HTML document |
Standard header for generated HTML pages.
htmlTagAttrs
:: [(String, String)]
Standard attributes for element "html".
Gets the parameter attached to the URL of the script.
For instance, if the script is called with URL
"http://.../script.cgi?parameter", then "parameter" is
returned by this I/O action.
Note that an URL parameter should be "URL encoded" to avoid
the appearance of characters with a special meaning.
Use urlencoded2string
and string2urlencoded
from Network.URL
to decode and encode such parameters, respectively.
getCookies
:: IO [(String, String)]
Gets the cookies sent from the browser for the current CGI script. The cookies are represented in the form of name/value pairs since no other components are important here.
coordinates
:: (HtmlRef -> String) -> Maybe (Int, Int)
For image buttons: retrieve the coordinates where the user clicked within the image.
class HTML
a
A type is an instance of class HTML
if it has operations to construct
HTML documents, i.e., constructors for basic text strings and
structures with tags and attributes, update the attributes in structures,
and selectors for basic text and structures which returns the contents
of these elements (or Nothing
for different elements).
Methods:
|
|
|