A FormLet instance

Minimal interface for defining the basic form combinators in a concrete rendering. defined in this module. see MFlow.Forms.XHtml for the instance for Text.XHtml and MFlow.Forms.HSP for an instance form Haskell Server Pages.

Register an user/password

Authentication against userRegistered users. to be used with validate

Wether the user is logged or is anonymous

If not logged, perform login. otherwise return the user

getUserSimple= getUser Nothing userFormLine

Very basic user authentication. The user is stored in a cookie. it looks for the cookie. If no cookie, it ask to the user for a userRegistered user-password combination. The user-password combination is only asked if the user has not logged already otherwise, the stored username is returned.

getUser mu form= ask $ userWidget mu form

Is an example of login/register validation form needed by userWidget. In this case the form field appears in a single line. it shows, in sequence, entries for the username, password, a button for loging, a entry to repeat password necesary for registering and a button for registering. The user can build its own user login/validation forms by modifying this example

 userFormLine=
     (User <$> getString (Just "enter user") <*> getPassword <+> submitButton "login")
     <+> fromString "  password again" +> getPassword <* submitButton "register"

Example of user/password form (no validation) to be used with userWidget

It creates a widget for user login/registering. If a user name is specified in the first parameter, it is forced to login/password as this specific user. Otherwise, if the user is already logged, the widget does not appear If the user press the register button, the user/password is registered and the user

It is the way to interact with the user. It takes a widget and return the user result If the environment has the result, ask don't ask to the user. To force asking in any case, put an clearEnv statement before in the FlowM monad

Clears the environment

display a text box and return a String

display a text box and return a Int (if the value entered is not an Int, fails the validation)

display a text box and return an Integer (if the value entered is not an Integer, fails the validation)

display a multiline text box and return its content

display a dropdown box with the two values (second (true) and third parameter(false)) . With the value of the first parameter selected.

display a dropdown box with the options in the first parameter is optionally selected . It returns the selected option.

set the option for getSelect. Options are concatenated with <|>

set the selected option for getSelect. Options are concatenated with <|>

display a password box

implement a radio button the parameter is the name of the radio group

implement a radio button that perform a submit when pressed. the parameter is the name of the radio group

display a text box and return the value entered if it is readable( Otherwise, fail the validation)

creates a link wiget. A link can be composed with other widget elements,

wrap a widget of form element within a form-action element.

Validates a form or widget result against a validating procedure

getOdd= getInt Nothing validate (x -> return $ if mod x 2==0 then  Nothing else Just only odd numbers, please)

empty widget that return Nothing. May be used as "empty boxes" inside larger widgets

render the Show instance of the parameter and return it. It is useful for displaying information

Actions are callbacks that are executed when a widget is validated. It is useful when the widget is inside widget containers that know nothing about his content. It returns a result that can be significative or, else, be ignored with <** and **>. An action may or may not initiate his own dialog with the user via ask

A modifier get the result and the rendering of a widget and change them.

This modifier, when logged, changes a login-password-register widget with a display username.

userFormOrName= userWidget Nothing userFormLine `wmodify` f
   where
   f _ justu@(Just u)  =  return ([fromString u], justu) -- user validated, display and return user
   f felem Nothing = do
     us <-  getCurrentUser
     if us == anonymous
           then return (felem, Nothing)                    -- user not logged, present the form
           else return([fromString us],  Just us)        -- already logged, display and return user

Cached widgets operate with widgets in the Identity monad, but they may perform IO using the execute instance of the monad m, which is usually the IO monad. execute basically "sanctifies" the use of unsafePerformIO for a transient purpose such is caching. This is defined in Data.TCache.Memoization. The user can create his own instance for his monad.

With cachedWidget it is possible to cache the rendering of a widget as a ByteString (maintaining type safety) , permanently or for a certain time. this is very useful for complex widgets that present information. Specially it they must access to databases.

 import MFlow.Wai.XHtm.All
 import Some.Time.Library
 addMessageFlows [(noscript, time)]
 main= run 80 waiMessageFlow
 time=do  ask $ cachedWidget "time" 5
            $ wlink () bold << "the time is " ++ show (execute giveTheTime) ++ " click here"
          time

this pseudocode would update the time every 5 seconds. The execution of the IO computation giveTheTime must be executed inside the cached widget to avoid unnecesary IO executions.

Join two widgets in the same page the resulting widget, when asked with it, returns a either one or the other

 r <- ask widget widget1 <+> widget widget2
 case r of (Just x, Nothing) -> ..

intersperse a widget in a list of widgets. the results is a 2-tuple of both types

Put a widget above and below other. Useful for navigation links in a page.

The first elem result (even if it is not validated) is discarded, and the secod is returned . This contrast with the applicative operator *> which fails the whole validation if the validation of the first elem fails. . The first element is displayed however, as in the case of *>

The second elem result (even if it is not validated) is discarded, and the first is returned . This contrast with the applicative operator <* which fails the whole validation if the validation of the second elem fails. . The first element is displayed however, as in the case of <*

Concat a list of widgets of the same type, to return a single result

An associative binary operation

Sequence actions, discarding the value of the second argument.

An infix synonym for fmap.

Sequential application.

 (.<+>.) x y = normalize x <+> normalize y

 (.|*>.) x y = normalize x |*> map normalize y

 (.|+|.) x y = normalize x |+| normalize y

 (.**>.) x y = normalize x **> normalize y

 (.<**.) x y = normalize x <** normalize y

 (.<|>.) x y= normalize x <|> normalize y

Enclose Widgets in some formating. view is intended to be instantiated to a particular format

This is a widget, which is table with some links. it returns an Int

 import MFlow.Forms.XHtml

 tableLinks :: View Html Int
 tableLinks= table ! [border 1,thestyle "width:20%;margin-left:auto;margin-right:auto"]
              <<< caption << "choose an item"
              ++> thead << tr << concatHtml[ th << bold << "item", th << bold << "times chosen"]
              ++> (tbody
                   <<< (tr <<< td <<< wlink  0 (bold <<"iphone") <++  td << ( bold << "One")
                   <|>  tr <<< td <<< wlink  1 (bold <<"ipad")   <++  td << ( bold << "Two")
                   <|>  tr <<< td <<< wlink  2 (bold <<"ipod")   <++  td << ( bold << "Three"))
                   )

Append formatting code to a widget

 getString hi <++ H1 << hi there

Prepend formatting code to a widget

bold "enter name" ++ getString Nothing

add attributes to the form element if the view has more than one element, it is applied to the first

 (.<<.) w x = w $ toByteString x

 (.<++.) x v= normalize x <++ toByteString v

 (.++>.) v x= toByteString v ++> normalize x

Writes a XML tag in a ByteString. It is the most basic form of formatting. For more sophisticated formatting , use MFlow.Forms.XHtml or MFlow.Forms.HSP.

 bhtml ats v= btag "html" ats v

 bbody ats v= btag "body" ats v

Flatten a binary tree of tuples of Maybe results produced by the <+> operator into a single tuple with the same elements in the same order. This is useful for easing matching. For example:

 res <- ask $ wlink1 <+> wlink2 wform <+> wlink3 <+> wlink4

res has type:

Maybe (Maybe (Maybe (Maybe (Maybe a,Maybe b),Maybe c),Maybe d),Maybe e)

but flatten res has type:

 (Maybe a, Maybe b, Maybe c, Maybe d, Maybe e)

Useful for the creation of pages using two or more views. For example HSP and Html. Because both have ConvertTo instances to ByteString, then it is possible to mix them via normalize:

 normalize widget  <+> normalize widget'

is equivalent to

 widget .<+>. widget'

Execute the FlowM view m monad. It is used as parameter of hackMessageFlow waiMessageFlow or addMessageFlows

main= do
   addMessageFlows [("noscript",transient $ runFlow mainf)]
   forkIO . run 80 $ waiMessageFlow
   adminLoop

True if the flow is going back (as a result of the back button pressed in the web browser). Usually this chech is nos necessary unless conditional code make it necessary

menu= do
       mop <- getGoStraighTo
       case mop of
        Just goop -> goop
        Nothing -> do
               r <- ask option1 <|> option2
               case r of
                op1 -> setGoStraighTo (Just goop1) >> goop1
                op2 -> setGoStraighTo (Just goop2) >> goop2

This pseudocode would execute the ask of the menu once. But if the user press the back button he will see again the menu. To let him choose other option, the code has to be change to

menu= do
       mop <- getGoStraighTo
       back <- goingBack
       case (mop,back) of
        (Just goop,False) -> goop
        _ -> do
               r <- ask option1 <|> option2
               case r of
                op1 -> setGoStraighTo (Just goop1) >> goop1
                op2 -> setGoStraighTo (Just goop2) >> goop2

Use this instead of return to return from a computation with an ask statement

This way when the user press the back button, the computation will execute back, to the returned code, according with the user navigation.

Set the header-footer that will enclose the widgets. It must be provided in the same formatting than them, altrough with normalization to byteStrings can be used any formatting

This header uses XML trough Haskell Server Pages (http://hackage.haskell.org/package/hsp)

 setHeader $ c ->
            <html>
                 <head>
                      <title>  my title </title>
                      <meta name= "Keywords" content= "sci-fi" />)
                 </head>
                  <body style= "margin-left:5%;margin-right:5%">
                       <% c %>
                  </body>
            </html>

This header uses Text.XHtml

 setHeader $ c ->
           thehtml
               << (header
                   << (thetitle << title +++
                       meta ! [name "Keywords",content "sci-fi"])) +++
                  body ! [style "margin-left:5%;margin-right:5%"] c

This header uses both. It uses byteString tags

 setHeader $ c ->
          bhtml [] $
               btag head [] $
                     (toByteString (thetitle << title) append
                     toByteString name= \"Keywords\" content= \"sci-fi\" /) append
                  bbody [("style", "margin-left:5%;margin-right:5%")] c

return the current header

Set 1) the timeout of the flow execution since the last user interaction. Once passed, the flow executes from the begining. 2). In persistent flows it set the session state timeout for the flow, that is persistent. If the flow is not persistent, it has no effect.

transient flows restart anew. persistent flows (that use step) restart at the las saved execution point, unless the session time has expired for the user.

Set an HTTP cookie