yesod-fay-0.4.0: Utilities for using the Fay Haskell-to-JS compiler with Yesod.

Safe HaskellNone




Utility functions for using Fay from a Yesod application.

This module is intended to be used from your Yesod application, not from your Fay programs.

We assume a specific file structure, namely that there is a fay folder containing client-side code, and fay-shared containing code to be used by both the client and server.

The Language.Fay.Yesod module (part of this package) is required by both client and server code. However, since Fay does not currently have package management support, we use a bit of a hack: the TH calls in this package will automatically create the necessary fay/Language/Fay/Yesod.hs file. Ultimately, we will use a more elegant solution.

In the future, if this package proves popular enough, Fay support will likely be built into the scaffolding. In the meantime, you must manually integrate it. In order to take advantage of this module, you should modify your Yesod application as follows:

  • Modify your cabal file to include the fay-shared folder when compiling. This can be done by adding a hs-source-dirs: ., fay-shared line to your library section.
  • Create the module SharedTypes in fay-shared and create a Command datatype. For an example of what this file should look like, see
  • Add the function fayFile to your Import module. See for an example.
  • Add a new route at for the Fay subsite. Generally, it will look like /fay-command FaySiteR FaySite getFaySite.
  • Import the SharedTypes and Yesod.Fay modules into your Foundation.hs module. Add an instance of YesodFay for your application. You should set the YesodFayCommand associated type to the Command datatype you created. (You may also need to add a YesodJquery instance.) Note that this instance must appear after your parseRoutes. Set the method fayRoute to FaySiteR (or whatever you called the subsite route), and implement yesodFayCommand. It will generally look something like yesodFayCommand render command = case command of { ... }.
  • In order to use Fay, add $(fayFile "MyModule") to a widget, and then write the corresponding fay/MyModule.hs file. For an example, see



class YesodJquery master => YesodFay master whereSource

Type class for applications using Fay.

We depend on YesodJquery since the generated client-side code uses jQuery for making Ajax calls. We have an associated type stating the command datatype. Since this datatype must be used by both the client and server, you should place its definition in the fay-shared folder.


yesodFayCommand :: CommandHandler masterSource

User-defined function specifying how to respond to commands. Using the above datatype, this might look like:

 yesodFayCommand render command =
     case command of
         GetFib index r = render r $ fibs !! index

fayRoute :: Route FaySite -> Route masterSource

Where in the routing tree our Fay subsite is located. This is generally named FaySiteR, e.g.:

 mkYesod "YourSite" [parseRoutes
 /fay-command FaySiteR FaySite getFaySite

 instance YesodFay YourSite where
     fayRoute = FaySiteR

data YesodFaySettings Source

A setttings data type for indicating whether the generated Javascript should contain a copy of the Fay runtime or not.




yfsModuleName :: String
yfsSeparateRuntime :: Maybe (FilePath, Exp)
yfsPostProcess :: String -> IO String
yfsExternal :: Maybe (FilePath, Exp)
yfsRequireJQuery :: Bool

Note that the server call functions provided for your Fay code require jQuery to be present. If you disable this option and still use the provided server call functions, your code will break.

Include Fay programs

fayFileProd :: YesodFaySettings -> Q ExpSource

Does a full compile of the Fay code via GHC for type checking, and then embeds the Fay-generated Javascript as a static string. File changes during runtime will not be reflected.

fayFileReload :: YesodFaySettings -> Q ExpSource

Performs no type checking on the Fay code. Each time the widget is requested, the Fay code will be compiled from scratch to Javascript.

type FayFile = String -> Q ExpSource

A function that takes a String giving the Fay module name, and returns an TH splice that generates a Widget.


type CommandHandler master = forall s. (forall a. Show a => Returns a -> a -> HandlerT master IO s) -> Value -> HandlerT master IO sSource

A function provided by the developer describing how to answer individual commands from client-side code.

Due to restrictions of the type system in Fay, we use a relatively simple approach for encoding the return type. In order to specify this, an extra parameter- Returns- is passed around, with a phantom type variable stating the expected return type.

The first argument to your function is the "respond" function: it takes the extra Returns parameter as well as the actual value to be returned, and produces the expected result.

data Returns a Source

A proxy type for specifying what type a command should return. The final field for each data constructor in a command datatype should be Returns.



getFaySite :: a -> FaySiteSource

To be used from your routing declarations.

data family Route a1

The type-safe URLs associated with a site argument.


class YesodJquery a where


urlJqueryJs :: a -> Either (Route a) Text

The jQuery Javascript file. Note that in upgrades to this library, the version of jQuery referenced, or where it is downloaded from, may be changed without warning. If you are relying on a specific version of jQuery, you should give an explicit URL instead of relying on the default value.

Currently, the default value is jQuery 1.7 from Google's CDN.

urlJqueryUiJs :: a -> Either (Route a) Text

The jQuery UI 1.8 Javascript file.

urlJqueryUiCss :: a -> Either (Route a) Text

The jQuery UI 1.8 CSS file; defaults to cupertino theme.

urlJqueryUiDateTimePicker :: a -> Either (Route a) Text

jQuery UI time picker add-on.