| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Yesod.Static
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
- 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
Type used for the subsite with static contents.
Constructors
| Static StaticSettings |
Instances
| RenderRoute Static Source # | |
| ParseRoute Static Source # | |
Defined in Yesod.Static | |
| YesodSubDispatch Static master Source # | |
Defined in Yesod.Static Methods yesodSubDispatch :: YesodSubRunnerEnv Static master -> Application # | |
| Eq (Route Static) Source # | |
| Read (Route Static) Source # | |
| Show (Route Static) Source # | |
| data Route Static Source # | |
Defined in Yesod.Static | |
The type-safe URLs associated with a site argument.
Instances
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.
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
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
| Default CombineSettings Source # | |
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.