yesod-static-1.6.1.0: Static file serving subsite for Yesod Web Framework.

Safe Haskell | Safe-Inferred
Language | Haskell2010

Yesod.Static

Contents

- Subsite
- Smart constructor
- Combining CSS/JS
  - Settings
- Template Haskell helpers
- Hashing
- Embed

Description

Serve static files from a Yesod app.

This is great for developing your application, but also for a dead-simple deployment. Caching headers are automatically taken care of.

If you are running a proxy server (like Apache or Nginx), you may want to have that server do the static serving instead.

In fact, in an ideal setup you'll serve your static files from a separate domain name to save time on transmitting cookies. In that case, you may wish to use `urlParamRenderOverride` to redirect requests to this subsite to a separate domain name.

Note that this module's static subsite ignores all files and directories that are hidden by Unix conventions (i.e. start with a dot, such as `".ssh"`) and the directory "tmp" on the root of the directory with static files.

Synopsis

- newtype Static = Static StaticSettings
- data family Route a
- type StaticRoute = Route Static
- static :: FilePath -> IO Static
- staticDevel :: FilePath -> IO Static
- combineStylesheets' :: Bool -> CombineSettings -> Name -> [Route Static] -> Q Exp
- combineScripts' :: Bool -> CombineSettings -> Name -> [Route Static] -> Q Exp
- data CombineSettings
- csStaticDir :: CombineSettings -> FilePath
- csCssPostProcess :: CombineSettings -> [FilePath] -> ByteString -> IO ByteString
- csJsPostProcess :: CombineSettings -> [FilePath] -> ByteString -> IO ByteString
- csCssPreProcess :: CombineSettings -> Text -> IO Text
- csJsPreProcess :: CombineSettings -> Text -> IO Text
- csCombinedFolder :: CombineSettings -> FilePath
- staticFiles :: FilePath -> Q [Dec]
- staticFilesList :: FilePath -> [FilePath] -> Q [Dec]
- staticFilesMap :: FilePath -> Map FilePath FilePath -> Q [Dec]
- staticFilesMergeMap :: FilePath -> Map FilePath FilePath -> Q [Dec]
- publicFiles :: FilePath -> Q [Dec]
- base64md5 :: ByteString -> String
- embed :: FilePath -> Q Exp

# Subsite

newtype Static Source #

Type used for the subsite with static contents.

Constructors

Static StaticSettings |

#### Instances

Instances details

ParseRoute Static Source # |
Instance details Defined in Yesod.Static Methods parseRoute :: ([Text], [(Text, Text)]) -> Maybe (Route Static) Source #
RenderRoute Static Source # |
Instance details Defined in Yesod.Static Associated Types data Route Static Source # Methods renderRoute :: Route Static -> ([Text], [(Text, Text)]) Source #
YesodSubDispatch Static master Source # |
Instance details Defined in Yesod.Static Methods yesodSubDispatch :: YesodSubRunnerEnv Static master -> Application Source #
Read (Route Static) Source # |
Instance details Defined in Yesod.Static Methods readsPrec :: Int -> ReadS (Route Static) Source # readList :: ReadS [Route Static] Source # readPrec :: ReadPrec (Route Static) Source # readListPrec :: ReadPrec [Route Static] Source #
Show (Route Static) Source # |
Instance details Defined in Yesod.Static Methods showsPrec :: Int -> Route Static -> ShowS Source # show :: Route Static -> String Source # showList :: [Route Static] -> ShowS Source #
Eq (Route Static) Source # |
Instance details Defined in Yesod.Static Methods (==) :: Route Static -> Route Static -> Bool Source # (/=) :: Route Static -> Route Static -> Bool Source #
data Route Static Source # |
Instance details Defined in Yesod.Static data Route Static = StaticRoute [Text] [(Text, Text)]

data family Route a Source #

The type-safe URLs associated with a site argument.

#### Instances

Instances details

RedirectUrl master (Route master) |
Instance details Defined in Yesod.Core.Handler Methods toTextUrl :: (MonadHandler m, HandlerSite m ~ master) => Route master -> m Text Source #
(key ~ Text, val ~ Text) => RedirectUrl master (Route master, Map key val) |
Instance details Defined in Yesod.Core.Handler Methods toTextUrl :: (MonadHandler m, HandlerSite m ~ master) => (Route master, Map key val) -> m Text Source #
(key ~ Text, val ~ Text) => RedirectUrl master (Route master, [(key, val)]) |
Instance details Defined in Yesod.Core.Handler Methods toTextUrl :: (MonadHandler m, HandlerSite m ~ master) => (Route master, [(key, val)]) -> m Text Source #
Read (Route LiteApp) |
Instance details Defined in Yesod.Core.Internal.LiteApp Methods readsPrec :: Int -> ReadS (Route LiteApp) Source # readList :: ReadS [Route LiteApp] Source # readPrec :: ReadPrec (Route LiteApp) Source # readListPrec :: ReadPrec [Route LiteApp] Source #
Read (Route WaiSubsite) |
Instance details Defined in Yesod.Core.Types Methods readsPrec :: Int -> ReadS (Route WaiSubsite) Source # readList :: ReadS [Route WaiSubsite] Source # readPrec :: ReadPrec (Route WaiSubsite) Source # readListPrec :: ReadPrec [Route WaiSubsite] Source #
Read (Route WaiSubsiteWithAuth) |
Instance details Defined in Yesod.Core.Types Methods readsPrec :: Int -> ReadS (Route WaiSubsiteWithAuth) Source # readList :: ReadS [Route WaiSubsiteWithAuth] Source # readPrec :: ReadPrec (Route WaiSubsiteWithAuth) Source # readListPrec :: ReadPrec [Route WaiSubsiteWithAuth] Source #
Read (Route EmbeddedStatic) Source # |
Instance details Defined in Yesod.EmbeddedStatic.Internal Methods readsPrec :: Int -> ReadS (Route EmbeddedStatic) Source # readList :: ReadS [Route EmbeddedStatic] Source # readPrec :: ReadPrec (Route EmbeddedStatic) Source # readListPrec :: ReadPrec [Route EmbeddedStatic] Source #
Read (Route Static) Source # |
Instance details Defined in Yesod.Static Methods readsPrec :: Int -> ReadS (Route Static) Source # readList :: ReadS [Route Static] Source # readPrec :: ReadPrec (Route Static) Source # readListPrec :: ReadPrec [Route Static] Source #
Show (Route LiteApp) |
Instance details Defined in Yesod.Core.Internal.LiteApp Methods showsPrec :: Int -> Route LiteApp -> ShowS Source # show :: Route LiteApp -> String Source # showList :: [Route LiteApp] -> ShowS Source #
Show (Route WaiSubsite) |
Instance details Defined in Yesod.Core.Types Methods showsPrec :: Int -> Route WaiSubsite -> ShowS Source # show :: Route WaiSubsite -> String Source # showList :: [Route WaiSubsite] -> ShowS Source #
Show (Route WaiSubsiteWithAuth) |
Instance details Defined in Yesod.Core.Types Methods showsPrec :: Int -> Route WaiSubsiteWithAuth -> ShowS Source # show :: Route WaiSubsiteWithAuth -> String Source # showList :: [Route WaiSubsiteWithAuth] -> ShowS Source #
Show (Route EmbeddedStatic) Source # |
Instance details Defined in Yesod.EmbeddedStatic.Internal Methods showsPrec :: Int -> Route EmbeddedStatic -> ShowS Source # show :: Route EmbeddedStatic -> String Source # showList :: [Route EmbeddedStatic] -> ShowS Source #
Show (Route Static) Source # |
Instance details Defined in Yesod.Static Methods showsPrec :: Int -> Route Static -> ShowS Source # show :: Route Static -> String Source # showList :: [Route Static] -> ShowS Source #
Eq (Route LiteApp) |
Instance details Defined in Yesod.Core.Internal.LiteApp Methods (==) :: Route LiteApp -> Route LiteApp -> Bool Source # (/=) :: Route LiteApp -> Route LiteApp -> Bool Source #
Eq (Route WaiSubsite) |
Instance details Defined in Yesod.Core.Types Methods (==) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source # (/=) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #
Eq (Route WaiSubsiteWithAuth) |
Instance details Defined in Yesod.Core.Types Methods (==) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source # (/=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #
Eq (Route EmbeddedStatic) Source # |
Instance details Defined in Yesod.EmbeddedStatic.Internal Methods (==) :: Route EmbeddedStatic -> Route EmbeddedStatic -> Bool Source # (/=) :: Route EmbeddedStatic -> Route EmbeddedStatic -> Bool Source #
Eq (Route Static) Source # |
Instance details Defined in Yesod.Static Methods (==) :: Route Static -> Route Static -> Bool Source # (/=) :: Route Static -> Route Static -> Bool Source #
Ord (Route LiteApp) |

Instance details

Defined in Yesod.Core.Internal.LiteApp

Methods

compare :: Route LiteApp -> Route LiteApp -> Ordering Source #

(<) :: Route LiteApp -> Route LiteApp -> Bool Source #

(<=) :: Route LiteApp -> Route LiteApp -> Bool Source #

(>) :: Route LiteApp -> Route LiteApp -> Bool Source #

(>=) :: Route LiteApp -> Route LiteApp -> Bool Source #

max :: Route LiteApp -> Route LiteApp -> Route LiteApp Source #

min :: Route LiteApp -> Route LiteApp -> Route LiteApp Source #

Ord (Route WaiSubsite) |

Instance details

Defined in Yesod.Core.Types

Methods

compare :: Route WaiSubsite -> Route WaiSubsite -> Ordering Source #

(<) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

(<=) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

(>) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

(>=) :: Route WaiSubsite -> Route WaiSubsite -> Bool Source #

max :: Route WaiSubsite -> Route WaiSubsite -> Route WaiSubsite Source #

min :: Route WaiSubsite -> Route WaiSubsite -> Route WaiSubsite Source #

Ord (Route WaiSubsiteWithAuth) |

Instance details

Defined in Yesod.Core.Types

Methods

compare :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Ordering Source #

(<) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

(<=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

(>) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

(>=) :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Bool Source #

max :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth Source #

min :: Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth -> Route WaiSubsiteWithAuth Source #

data Route LiteApp |
Instance details Defined in Yesod.Core.Internal.LiteApp data Route LiteApp = LiteAppRoute [Text]
data Route WaiSubsite |
Instance details Defined in Yesod.Core.Types data Route WaiSubsite = WaiSubsiteRoute [Text] [(Text, Text)]
data Route WaiSubsiteWithAuth |
Instance details Defined in Yesod.Core.Types data Route WaiSubsiteWithAuth = WaiSubsiteWithAuthRoute [Text] [(Text, Text)]
data Route EmbeddedStatic Source # |

Instance details

Defined in Yesod.EmbeddedStatic.Internal

data Route EmbeddedStatic

- = EmbeddedResourceR [Text] [(Text, Text)]
- | EmbeddedWidgetR Text

data Route Static Source # |
Instance details Defined in Yesod.Static data Route Static = StaticRoute [Text] [(Text, Text)]

type StaticRoute = Route Static Source #

# Smart constructor

static :: FilePath -> IO Static Source #

Produce a default value of `Static` for a given file folder.

Does not have index files or directory listings. The static files' contents must not change, however new files can be added.

staticDevel :: FilePath -> IO Static Source #

Same as `static`, but does not assumes that the files do not change and checks their modification time whenever a request is made.

# Combining CSS/JS

A common scenario on a site is the desire to include many external CSS and Javascript files on every page. Doing so via the Widget functionality in Yesod will work, but would also mean that the same content will be downloaded many times. A better approach would be to combine all of these files together into a single static file and serve that as a static resource for every page. That resource can be cached on the client, and bandwidth usage reduced.

This could be done as a manual process, but that becomes tedious. Instead, you can use some Template Haskell code which will combine these files into a single static file at compile time.

combineStylesheets' Source #

Arguments

:: Bool | development? if so, perform no combining
-> CombineSettings |
-> Name | Static route constructor name, e.g. 'StaticR
-> [Route Static] | files to combine
-> Q Exp |

Combine multiple CSS files together. Common usage would be:

    >>> combineStylesheets' development def 'StaticR [style1_css, style2_css]

Where `development` is a variable in your site indicated whether you are in development or production mode.

Since 1.2.0

combineScripts' Source #

Arguments

:: Bool | development? if so, perform no combining
-> CombineSettings |
-> Name | Static route constructor name, e.g. 'StaticR
-> [Route Static] | files to combine
-> Q Exp |

Combine multiple JS files together. Common usage would be:

    >>> combineScripts' development def 'StaticR [script1_js, script2_js]

Where `development` is a variable in your site indicated whether you are in development or production mode.

Since 1.2.0

## Settings

data CombineSettings Source #

Data type for holding all settings for combining files.

This data type is a settings type. For more information, see:

http://www.yesodweb.com/book/settings-types

Since 1.2.0

#### Instances

Instances details

Default CombineSettings Source # |
Instance details Defined in Yesod.Static Methods def :: CombineSettings #

csStaticDir :: CombineSettings -> FilePath Source #

File path containing static files.

Default: static

Since 1.2.0

csCssPostProcess :: CombineSettings -> [FilePath] -> ByteString -> IO ByteString Source #

Post processing to be performed on CSS files.

Default: Pass-through.

Since 1.2.0

csJsPostProcess :: CombineSettings -> [FilePath] -> ByteString -> IO ByteString Source #

Post processing to be performed on Javascript files.

Default: Pass-through.

Since 1.2.0

csCssPreProcess :: CombineSettings -> Text -> IO Text Source #

Pre-processing to be performed on CSS files.

Default: convert all occurences of static to ../

Since 1.2.0

csJsPreProcess :: CombineSettings -> Text -> IO Text Source #

Pre-processing to be performed on Javascript files.

Default: Pass-through.

Since 1.2.0

csCombinedFolder :: CombineSettings -> FilePath Source #

Subfolder to put combined files into.

Default: combined

Since 1.2.0

# Template Haskell helpers

staticFiles :: FilePath -> Q [Dec] Source #

Template Haskell function that automatically creates routes for all of your static files.

For example, if you used

    staticFiles "static/"

and you had files `"static/style.css"` and `"static/js/script.js"`, then the following top-level definitions would be created:

    style_css    = StaticRoute ["style.css"]    []
    js_script_js = StaticRoute ["js", "script.js"] []

Note that dots (`.`), dashes (`-`) and slashes (`/`) are replaced by underscores (`_`) to create valid Haskell identifiers.

staticFilesList :: FilePath -> [FilePath] -> Q [Dec] Source #

Same as `staticFiles`, but takes an explicit list of files to create identifiers for. The files path given are relative to the static folder. For example, to create routes for the files `"static/js/jquery.js"` and `"static/css/normalize.css"`, you would use:

    staticFilesList "static" ["js/jquery.js", "css/normalize.css"]

This can be useful when you have a very large number of static files, but only need to refer to a few of them from Haskell.

staticFilesMap :: FilePath -> Map FilePath FilePath -> Q [Dec] Source #

Similar to `staticFilesList`, but takes a mapping of unmunged names to fingerprinted file names.

Since: 1.5.3

staticFilesMergeMap :: FilePath -> Map FilePath FilePath -> Q [Dec] Source #

Similar to `staticFilesMergeMap`, but also generates identifiers for all files in the specified directory that don't have a fingerprinted version.

Since: 1.5.3

publicFiles :: FilePath -> Q [Dec] Source #

Same as `staticFiles`, but doesn't append an ETag to the query string.

Using `publicFiles` will speed up the compilation, since there won't be any need for hashing files during compile-time. However, since the ETag ceases to be part of the URL, the `Static` subsite won't be able to set the expire date too far on the future. Browsers still will be able to cache the contents, however they'll need send a request to the server to see if their copy is up-to-date.

# Hashing

base64md5 :: ByteString -> String Source #

# Embed

embed :: FilePath -> Q Exp Source #

Produce a `Static` based on embedding all of the static files' contents in the executable at compile time.

You should use Yesod.EmbeddedStatic instead, it is much more powerful.

Nota Bene: if you replace the scaffolded `static` call in Settings/StaticFiles.hs you will need to change the scaffolded addStaticContent. Otherwise, some of your assets will be 404'ed. This is because by default yesod will generate compile those assets to `static/tmp` which for `static` is fine since they are served out of the directory itself. With embedded static, that will not work. You can easily change `addStaticContent` to `_ _ _ -> return Nothing` as a workaround. This will cause yesod to embed those assets into the generated HTML file itself.