yesod-core-1.6.26.0: Creation of type-safe, RESTful web applications.

Safe Haskell | None
Language | Haskell2010

Yesod.Core.Widget

Contents

- Datatype
- Special Hamlet quasiquoter/TH for Widgets
- Convert to Widget
- Creating
  - Head of page
  - CSS
  - Javascript
- Subsites
- Internal

Description

Widgets combine HTML with JS and CSS dependencies with a unique identifier generator, allowing you to create truly modular HTML components.

Synopsis

- type WidgetT site (m :: Type -> Type) = WidgetFor site
- data WidgetFor site a
- data PageContent url = PageContent {
  - pageTitle :: !Html
  - pageDescription :: !(Maybe Text)
  - pageHead :: !(HtmlUrl url)
  - pageBody :: !(HtmlUrl url)
  }
- whamlet :: QuasiQuoter
- whamletFile :: FilePath -> Q Exp
- ihamletToRepHtml :: (MonadHandler m, RenderMessage (HandlerSite m) message) => HtmlUrlI18n message (Route (HandlerSite m)) -> m Html
- ihamletToHtml :: (MonadHandler m, RenderMessage (HandlerSite m) message) => HtmlUrlI18n message (Route (HandlerSite m)) -> m Html
- class ToWidget site a where
  - toWidget :: (MonadWidget m, HandlerSite m ~ site) => a -> m ()
- class ToWidgetHead site a where
  - toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => a -> m ()
- class ToWidgetBody site a where
  - toWidgetBody :: (MonadWidget m, HandlerSite m ~ site) => a -> m ()
- class ToWidgetMedia site a where
  - toWidgetMedia :: (MonadWidget m, HandlerSite m ~ site) => Text -> a -> m ()
- setTitle :: MonadWidget m => Html -> m ()
- setTitleI :: (MonadWidget m, RenderMessage (HandlerSite m) msg) => msg -> m ()
- setDescription :: MonadWidget m => Text -> m ()
- setDescriptionI :: (MonadWidget m, RenderMessage (HandlerSite m) msg) => msg -> m ()
- setDescriptionIdemp :: MonadWidget m => Text -> m ()
- setDescriptionIdempI :: (MonadWidget m, RenderMessage (HandlerSite m) msg) => msg -> m ()
- setOGType :: MonadWidget m => Text -> m ()
- setOGImage :: MonadWidget m => Text -> m ()
- addStylesheet :: MonadWidget m => Route (HandlerSite m) -> m ()
- addStylesheetAttrs :: MonadWidget m => Route (HandlerSite m) -> [(Text, Text)] -> m ()
- addStylesheetRemote :: MonadWidget m => Text -> m ()
- addStylesheetRemoteAttrs :: MonadWidget m => Text -> [(Text, Text)] -> m ()
- addStylesheetEither :: MonadWidget m => Either (Route (HandlerSite m)) Text -> m ()
- newtype CssBuilder = CssBuilder {
  - unCssBuilder :: Builder
  }
- addScript :: MonadWidget m => Route (HandlerSite m) -> m ()
- addScriptAttrs :: MonadWidget m => Route (HandlerSite m) -> [(Text, Text)] -> m ()
- addScriptRemote :: MonadWidget m => Text -> m ()
- addScriptRemoteAttrs :: MonadWidget m => Text -> [(Text, Text)] -> m ()
- addScriptEither :: MonadWidget m => Either (Route (HandlerSite m)) Text -> m ()
- handlerToWidget :: HandlerFor site a -> WidgetFor site a
- whamletFileWithSettings :: HamletSettings -> FilePath -> Q Exp
- asWidgetT :: forall site (m :: Type -> Type). WidgetT site m () -> WidgetT site m ()

# Datatype

type WidgetT site (m :: Type -> Type) = WidgetFor site #

Deprecated: Use WidgetFor directly

data WidgetFor site a #

A generic widget, allowing specification of both the subsite and master site datatypes. While this is simply a `WriterT`, we define a newtype for better error messages.

#### Instances

Instances details

(site' ~ site, a ~ ()) => ToWidget site' (WidgetFor site a) # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site') => WidgetFor site a -> m () #
MonadIO (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods liftIO :: IO a -> WidgetFor site a #
MonadThrow (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods throwM :: (HasCallStack, Exception e) => e -> WidgetFor site a #
Applicative (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods pure :: a -> WidgetFor site a # (<*>) :: WidgetFor site (a -> b) -> WidgetFor site a -> WidgetFor site b # liftA2 :: (a -> b -> c) -> WidgetFor site a -> WidgetFor site b -> WidgetFor site c # (*>) :: WidgetFor site a -> WidgetFor site b -> WidgetFor site b # (<*) :: WidgetFor site a -> WidgetFor site b -> WidgetFor site a #
Functor (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods fmap :: (a -> b) -> WidgetFor site a -> WidgetFor site b # (<$) :: a -> WidgetFor site b -> WidgetFor site a #
Monad (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods (>>=) :: WidgetFor site a -> (a -> WidgetFor site b) -> WidgetFor site b # (>>) :: WidgetFor site a -> WidgetFor site b -> WidgetFor site b # return :: a -> WidgetFor site a #
MonadLogger (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods monadLoggerLog :: ToLogStr msg => Loc -> LogSource -> LogLevel -> msg -> WidgetFor site () #
MonadLoggerIO (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods askLoggerIO :: WidgetFor site (Loc -> LogSource -> LogLevel -> LogStr -> IO ()) #
PrimMonad (WidgetFor site) # | Since: 1.6.7

Instance details

Defined in Yesod.Core.Types

Associated Types

type PrimState (WidgetFor site) |
Instance details Defined in Yesod.Core.Types type PrimState (WidgetFor site) = PrimState IO

Methods

primitive :: (State# (PrimState (WidgetFor site)) -> (# State# (PrimState (WidgetFor site)), a #)) -> WidgetFor site a #

MonadResource (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods liftResourceT :: ResourceT IO a -> WidgetFor site a #
MonadUnliftIO (WidgetFor site) # | Since: 1.4.38
Instance details Defined in Yesod.Core.Types Methods withRunInIO :: ((forall a. WidgetFor site a -> IO a) -> IO b) -> WidgetFor site b #
MonadHandler (WidgetFor site) # |

Instance details

Defined in Yesod.Core.Class.Handler

Associated Types

type HandlerSite (WidgetFor site) |
Instance details Defined in Yesod.Core.Class.Handler type HandlerSite (WidgetFor site) = site
type SubHandlerSite (WidgetFor site) |
Instance details Defined in Yesod.Core.Class.Handler type SubHandlerSite (WidgetFor site) = site

Methods

liftHandler :: HandlerFor (HandlerSite (WidgetFor site)) a -> WidgetFor site a #

liftSubHandler :: SubHandlerFor (SubHandlerSite (WidgetFor site)) (HandlerSite (WidgetFor site)) a -> WidgetFor site a #

MonadWidget (WidgetFor site) # |
Instance details Defined in Yesod.Core.Class.Handler Methods liftWidget :: WidgetFor (HandlerSite (WidgetFor site)) a -> WidgetFor site a #
MonadReader (WidgetData site) (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types Methods ask :: WidgetFor site (WidgetData site) # local :: (WidgetData site -> WidgetData site) -> WidgetFor site a -> WidgetFor site a # reader :: (WidgetData site -> a) -> WidgetFor site a #
a ~ () => Monoid (WidgetFor site a) # |
Instance details Defined in Yesod.Core.Types Methods mempty :: WidgetFor site a # mappend :: WidgetFor site a -> WidgetFor site a -> WidgetFor site a # mconcat :: [WidgetFor site a] -> WidgetFor site a #
a ~ () => Semigroup (WidgetFor site a) # |
Instance details Defined in Yesod.Core.Types Methods (<>) :: WidgetFor site a -> WidgetFor site a -> WidgetFor site a # sconcat :: NonEmpty (WidgetFor site a) -> WidgetFor site a # stimes :: Integral b => b -> WidgetFor site a -> WidgetFor site a #

a ~ () => IsString (WidgetFor site a) #

A `String` can be trivially promoted to a widget.

For example, in a yesod-scaffold site you could use:

    getHomeR = do defaultLayout "Widget text"

Instance details Defined in Yesod.Core.Types Methods fromString :: String -> WidgetFor site a #
type PrimState (WidgetFor site) # |
Instance details Defined in Yesod.Core.Types type PrimState (WidgetFor site) = PrimState IO
type HandlerSite (WidgetFor site) # |
Instance details Defined in Yesod.Core.Class.Handler type HandlerSite (WidgetFor site) = site
type SubHandlerSite (WidgetFor site) # |
Instance details Defined in Yesod.Core.Class.Handler type SubHandlerSite (WidgetFor site) = site

data PageContent url #

Content for a web page. By providing this datatype, we can easily create generic site templates, which would have the type signature:

    PageContent url -> HtmlUrl url

Constructors

PageContent |

Fields

- pageTitle :: !Html
- pageDescription :: !(Maybe Text)
- pageHead :: !(HtmlUrl url)
- pageBody :: !(HtmlUrl url)

# Special Hamlet quasiquoter/TH for Widgets

whamlet :: QuasiQuoter #

whamletFile :: FilePath -> Q Exp #

ihamletToRepHtml :: (MonadHandler m, RenderMessage (HandlerSite m) message) => HtmlUrlI18n message (Route (HandlerSite m)) -> m Html #

Deprecated: Please use ihamletToHtml instead

Wraps the `Content` generated by `hamletToContent` in a `RepHtml`.

ihamletToHtml :: (MonadHandler m, RenderMessage (HandlerSite m) message) => HtmlUrlI18n message (Route (HandlerSite m)) -> m Html #

Wraps the `Content` generated by `hamletToContent` in a `RepHtml`.

Since 1.2.1

# Convert to Widget

class ToWidget site a where #

Methods

toWidget :: (MonadWidget m, HandlerSite m ~ site) => a -> m () #

#### Instances

Instances details

ToWidget site Html # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => Html -> m () #
ToWidget site Css # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => Css -> m () #
ToWidget site Javascript # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => Javascript -> m () #
ToWidget site Text # | Since: 1.4.28
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => Text -> m () #
ToWidget site Builder # | Since: 1.4.28
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => Builder -> m () #
ToWidget site Text # | Since: 1.4.28
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => Text -> m () #
ToWidget site CssBuilder # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => CssBuilder -> m () #
render ~ RY site => ToWidget site (render -> Html) # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => (render -> Html) -> m () #
render ~ RY site => ToWidget site (render -> Css) # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => (render -> Css) -> m () #
render ~ RY site => ToWidget site (render -> Javascript) # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => (render -> Javascript) -> m () #
render ~ RY site => ToWidget site (render -> CssBuilder) # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => (render -> CssBuilder) -> m () #
(site' ~ site, a ~ ()) => ToWidget site' (WidgetFor site a) # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site') => WidgetFor site a -> m () #

class ToWidgetHead site a where #

Methods

toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => a -> m () #

#### Instances

Instances details

ToWidgetHead site Html # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => Html -> m () #
ToWidgetHead site Css # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => Css -> m () #
ToWidgetHead site Javascript # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => Javascript -> m () #
ToWidgetHead site CssBuilder # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => CssBuilder -> m () #
render ~ RY site => ToWidgetHead site (render -> Html) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => (render -> Html) -> m () #
render ~ RY site => ToWidgetHead site (render -> Css) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => (render -> Css) -> m () #
render ~ RY site => ToWidgetHead site (render -> Javascript) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => (render -> Javascript) -> m () #
render ~ RY site => ToWidgetHead site (render -> CssBuilder) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => (render -> CssBuilder) -> m () #

class ToWidgetBody site a where #

Methods

toWidgetBody :: (MonadWidget m, HandlerSite m ~ site) => a -> m () #

#### Instances

Instances details

ToWidgetBody site Html # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetBody :: (MonadWidget m, HandlerSite m ~ site) => Html -> m () #
ToWidgetBody site Javascript # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetBody :: (MonadWidget m, HandlerSite m ~ site) => Javascript -> m () #
render ~ RY site => ToWidgetBody site (render -> Html) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetBody :: (MonadWidget m, HandlerSite m ~ site) => (render -> Html) -> m () #
render ~ RY site => ToWidgetBody site (render -> Javascript) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetBody :: (MonadWidget m, HandlerSite m ~ site) => (render -> Javascript) -> m () #

class ToWidgetMedia site a where #

Allows adding some CSS to the page with a specific media type.

Since 1.2

Methods

toWidgetMedia #

Arguments

:: (MonadWidget m, HandlerSite m ~ site) |
=> Text | media value
-> a |
-> m () |

Add the given content to the page, but only for the given media type.

Since 1.2

#### Instances

Instances details

ToWidgetMedia site Css # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetMedia :: (MonadWidget m, HandlerSite m ~ site) => Text -> Css -> m () #
ToWidgetMedia site CssBuilder # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetMedia :: (MonadWidget m, HandlerSite m ~ site) => Text -> CssBuilder -> m () #
render ~ RY site => ToWidgetMedia site (render -> Css) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetMedia :: (MonadWidget m, HandlerSite m ~ site) => Text -> (render -> Css) -> m () #
render ~ RY site => ToWidgetMedia site (render -> CssBuilder) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetMedia :: (MonadWidget m, HandlerSite m ~ site) => Text -> (render -> CssBuilder) -> m () #

# Creating

## Head of page

setTitle :: MonadWidget m => Html -> m () #

Set the page title.

Calling `setTitle` or `setTitleI` multiple times overrides previously set values.

SEO Notes:

- Title tags are the second most important on-page factor for SEO, after content
- Every page should have a unique title tag
- Start your title tag with your main targeted keyword
- Don't stuff your keywords
- Google typically shows 55-64 characters, so aim to keep your title length under 60 characters

setTitleI :: (MonadWidget m, RenderMessage (HandlerSite m) msg) => msg -> m () #

Set the localised page title.

n.b. See comments for `setTitle`

setDescription :: MonadWidget m => Text -> m () #

Warning: setDescription is not idempotent; we recommend setDescriptionIdemp insteadMultiple calls to setDescription will insert multiple meta tags in the page head.If you want an idempotent function, use setDescriptionIdemp - but if you do, you may need to change your layout to include pageDescription.

Add description meta tag to the head of the page

Google does not use the description tag as a ranking signal, but the contents of this tag will likely affect your click-through rate since it shows up in search results.

The average length of the description shown in Google's search results is about 160 characters on desktop, and about 130 characters on mobile, at time of writing.

Source: https://www.advancedwebranking.com/blog/meta-tags-important-in-seo/

Since: 1.6.18

setDescriptionI :: (MonadWidget m, RenderMessage (HandlerSite m) msg) => msg -> m () #

Warning: setDescriptionI is not idempotent; we recommend setDescriptionIdempI insteadMultiple calls to setDescriptionI will insert multiple meta tags in the page head.If you want an idempotent function, use setDescriptionIdempI - but if you do, you may need to change your layout to include pageDescription.

Add translated description meta tag to the head of the page

n.b. See comments for `setDescription`.

Since: 1.6.18

setDescriptionIdemp :: MonadWidget m => Text -> m () #

Add description meta tag to the head of the page

Google does not use the description tag as a ranking signal, but the contents of this tag will likely affect your click-through rate since it shows up in search results.

The average length of the description shown in Google's search results is about 160 characters on desktop, and about 130 characters on mobile, at time of writing.

Unlike `setDescription`, this version is *idempotent* - calling it multiple times will result in only a single description meta tag in the head.

Source: https://www.advancedwebranking.com/blog/meta-tags-important-in-seo/

Since: 1.6.23

setDescriptionIdempI :: (MonadWidget m, RenderMessage (HandlerSite m) msg) => msg -> m () #

Add translated description meta tag to the head of the page

n.b. See comments for `setDescriptionIdemp`.

Unlike `setDescriptionI`, this version is *idempotent* - calling it multiple times will result in only a single description meta tag in the head.

Since: 1.6.23

setOGType :: MonadWidget m => Text -> m () #

Add OpenGraph type meta tag to the head of the page

See all available OG types here: https://ogp.me/#types

Since: 1.6.18

setOGImage :: MonadWidget m => Text -> m () #

Add OpenGraph image meta tag to the head of the page

Best practices:

- Use custom images for shareable pages, e.g., homepage, articles, etc.
- Use your logo or any other branded image for the rest of your pages.
- Use images with a 1.91:1 ratio and minimum recommended dimensions of 1200x630 for optimal clarity across all devices.

Source: https://ahrefs.com/blog/open-graph-meta-tags/

Since: 1.6.18

## CSS

addStylesheet :: MonadWidget m => Route (HandlerSite m) -> m () #

Link to the specified local stylesheet.

addStylesheetAttrs :: MonadWidget m => Route (HandlerSite m) -> [(Text, Text)] -> m () #

Link to the specified local stylesheet.

addStylesheetRemote :: MonadWidget m => Text -> m () #

Link to the specified remote stylesheet.

addStylesheetRemoteAttrs :: MonadWidget m => Text -> [(Text, Text)] -> m () #

Link to the specified remote stylesheet.

addStylesheetEither :: MonadWidget m => Either (Route (HandlerSite m)) Text -> m () #

newtype CssBuilder #

Newtype wrapper allowing injection of arbitrary content into CSS.

Usage:

    toWidget $ CssBuilder "p { color: red }"

Since: 1.1.3

Constructors

CssBuilder |

Fields

- unCssBuilder :: Builder

#### Instances

Instances details

ToWidget site CssBuilder # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => CssBuilder -> m () #
ToWidgetHead site CssBuilder # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => CssBuilder -> m () #
ToWidgetMedia site CssBuilder # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetMedia :: (MonadWidget m, HandlerSite m ~ site) => Text -> CssBuilder -> m () #
render ~ RY site => ToWidget site (render -> CssBuilder) # |
Instance details Defined in Yesod.Core.Widget Methods toWidget :: (MonadWidget m, HandlerSite m ~ site) => (render -> CssBuilder) -> m () #
render ~ RY site => ToWidgetHead site (render -> CssBuilder) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetHead :: (MonadWidget m, HandlerSite m ~ site) => (render -> CssBuilder) -> m () #
render ~ RY site => ToWidgetMedia site (render -> CssBuilder) # |
Instance details Defined in Yesod.Core.Widget Methods toWidgetMedia :: (MonadWidget m, HandlerSite m ~ site) => Text -> (render -> CssBuilder) -> m () #

## Javascript

addScript :: MonadWidget m => Route (HandlerSite m) -> m () #

Link to the specified local script.

addScriptAttrs :: MonadWidget m => Route (HandlerSite m) -> [(Text, Text)] -> m () #

Link to the specified local script.

addScriptRemote :: MonadWidget m => Text -> m () #

Link to the specified remote script.

addScriptRemoteAttrs :: MonadWidget m => Text -> [(Text, Text)] -> m () #

Link to the specified remote script.

addScriptEither :: MonadWidget m => Either (Route (HandlerSite m)) Text -> m () #

# Subsites

handlerToWidget :: HandlerFor site a -> WidgetFor site a #

# Internal

whamletFileWithSettings :: HamletSettings -> FilePath -> Q Exp #

asWidgetT :: forall site (m :: Type -> Type). WidgetT site m () -> WidgetT site m () #