Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 234 lines (194 sloc) 8.556 kB
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored
1 ------------------------------------------------------------------------------
2 -- | The Heist snaplet makes it easy to add Heist to your application and use
3 -- it in other snaplets.
4 --
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
5
6 module Snap.Snaplet.Heist
7 (
8 -- * Heist and its type class
9 Heist
10 , HasHeist(..)
11
12 -- * Initializer Functions
13 -- $initializerSection
14 , heistInit
29e9992 @mightybyte Fix issue mentioned in
mightybyte authored
15 , heistInit'
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
16 , addTemplates
17 , addTemplatesAt
a35696c @mightybyte Style nazi strikes again.
mightybyte authored
18 , modifyHeistTS
19 , withHeistTS
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
20 , addSplices
21
22 -- * Handler Functions
23 -- $handlerSection
24 , render
25 , renderAs
26 , heistServe
27 , heistServeSingle
28 , heistLocal
29 , withSplices
30 , renderWithSplices
31
32 -- * Writing Splices
33 -- $spliceSection
34 , Unclassed.SnapletHeist
35 , Unclassed.SnapletSplice
36 , Unclassed.liftHeist
37 , Unclassed.liftHandler
e88b397 @mightybyte Restructured auth snaplet to improve haddock structure. Other misc w…
mightybyte authored
38 , Unclassed.liftAppHandler
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
39 , Unclassed.liftWith
40 , Unclassed.bindSnapletSplices
41
42 , clearHeistCache
43 ) where
44
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored
45 ------------------------------------------------------------------------------
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
46 import Prelude hiding (id, (.))
47 import Data.ByteString (ByteString)
c28c4b4 @mightybyte Switched from fclabels to data-lens.
mightybyte authored
48 import Data.Lens.Lazy
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
49 import Data.Text (Text)
50 import Text.Templating.Heist
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored
51 ------------------------------------------------------------------------------
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
52 import Snap.Snaplet
53 import qualified Snap.Snaplet.HeistNoClass as Unclassed
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored
54 import Snap.Snaplet.HeistNoClass ( Heist
55 , heistInit
56 , heistInit'
57 , clearHeistCache
58 )
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
59
60
61 ------------------------------------------------------------------------------
62 -- | A single snaplet should never need more than one instance of Heist as a
63 -- subsnaplet. This type class allows you to make it easy for other snaplets
64 -- to get the lens that identifies the heist snaplet. Here's an example of
65 -- how the heist snaplet might be declared:
66 --
67 -- > data App = App { _heist :: Snaplet (Heist App) }
68 -- > mkLabels [''App]
69 -- >
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
70 -- > instance HasHeist App where heistLens = subSnaplet heist
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
71 -- >
72 -- > appInit = makeSnaplet "app" "" Nothing $ do
b2df047 @mightybyte Fixed stale haddock comment.
mightybyte authored
73 -- > h <- nestSnaplet "heist" heist $ heistInit "templates"
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
74 -- > addSplices myAppSplices
75 -- > return $ App h
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
76 class HasHeist b where
77 -- | A lens to the Heist snaplet. The b parameter to Heist will
78 -- typically be the base state of your application.
c28c4b4 @mightybyte Switched from fclabels to data-lens.
mightybyte authored
79 heistLens :: Lens (Snaplet b) (Snaplet (Heist b))
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
80
81
82 -- $initializerSection
83 -- This section contains functions for use in setting up your Heist state
84 -- during initialization.
85
86
87 ------------------------------------------------------------------------------
88 -- | Adds templates to the Heist TemplateState. Other snaplets should use
89 -- this function to add their own templates. The templates are automatically
90 -- read from the templates directory in the current snaplet's filesystem root.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
91 addTemplates :: HasHeist b
92 => ByteString
93 -- ^ Path to templates (also the url prefix for their routes)
94 -> Initializer b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
95 addTemplates pfx = withTop' heistLens (Unclassed.addTemplates pfx)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
96
97
98 ------------------------------------------------------------------------------
99 -- | Adds templates to the Heist TemplateState, and lets you specify where
e88b397 @mightybyte Restructured auth snaplet to improve haddock structure. Other misc w…
mightybyte authored
100 -- they are found in the filesystem.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
101 addTemplatesAt :: HasHeist b
102 => ByteString
103 -- ^ URL prefix for template routes
104 -> FilePath
105 -- ^ Path to templates
106 -> Initializer b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
107 addTemplatesAt pfx p = withTop' heistLens (Unclassed.addTemplatesAt pfx p)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
108
109
110 ------------------------------------------------------------------------------
111 -- | Allows snaplets to add splices.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
112 addSplices :: (HasHeist b)
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
113 => [(Text, Unclassed.SnapletSplice b v)]
114 -- ^ Splices to bind
115 -> Initializer b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
116 addSplices = Unclassed.addSplices' heistLens
117
118
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored
119 ------------------------------------------------------------------------------
120 -- | More general function allowing arbitrary TemplateState modification.
121 -- Without this function you wouldn't be able to bind more complicated splices
122 -- like the cache tag.
123 modifyHeistTS :: (HasHeist b)
124 => (TemplateState (Handler b b) -> TemplateState (Handler b b))
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
125 -- ^ TemplateState modifying function
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored
126 -> Initializer b v ()
127 modifyHeistTS = Unclassed.modifyHeistTS' heistLens
128
129
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored
130 ------------------------------------------------------------------------------
131 -- | Runs a function on with the Heist snaplet's 'TemplateState'.
132 withHeistTS :: (HasHeist b)
133 => (TemplateState (Handler b b) -> a)
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
134 -- ^ TemplateState function to run
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored
135 -> Handler b v a
136 withHeistTS = Unclassed.withHeistTS' heistLens
137
138
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
139 -- $handlerSection
140 -- This section contains functions in the 'Handler' monad that you'll use in
141 -- processing requests.
142
143
144 ------------------------------------------------------------------------------
145 -- | Renders a template as text\/html. If the given template is not found,
146 -- this returns 'empty'.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
147 render :: HasHeist b
148 => ByteString
149 -- ^ Template name
150 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
151 render t = withTop' heistLens (Unclassed.render t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
152
153
154 ------------------------------------------------------------------------------
155 -- | Renders a template as the given content type. If the given template
156 -- is not found, this returns 'empty'.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
157 renderAs :: HasHeist b
158 => ByteString
159 -- ^ Content type to render with
160 -> ByteString
161 -- ^ Template name
162 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
163 renderAs ct t = withTop' heistLens (Unclassed.renderAs ct t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
164
165
166 ------------------------------------------------------------------------------
167 -- | Analogous to 'fileServe'. If the template specified in the request path
168 -- is not found, it returns 'empty'.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
169 heistServe :: HasHeist b => Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
170 heistServe = withTop' heistLens Unclassed.heistServe
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
171
172
173 ------------------------------------------------------------------------------
174 -- | Analogous to 'fileServeSingle'. If the given template is not found,
175 -- this throws an error.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
176 heistServeSingle :: HasHeist b
177 => ByteString
178 -- ^ Template name
179 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
180 heistServeSingle t = withTop' heistLens (Unclassed.heistServeSingle t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
181
182
183 ------------------------------------------------------------------------------
184 -- | Renders a template with a given set of splices. This is syntax sugar for
185 -- a common combination of heistLocal, bindSplices, and render.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
186 renderWithSplices :: HasHeist b
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
187 => ByteString
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
188 -- ^ Template name
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
189 -> [(Text, Unclassed.SnapletSplice b v)]
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
190 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
191 -> Handler b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
192 renderWithSplices = Unclassed.renderWithSplices' heistLens
193
194
195 ------------------------------------------------------------------------------
196 -- | Runs an action with additional splices bound into the Heist
197 -- 'TemplateState'.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
198 withSplices :: HasHeist b
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
199 => [(Text, Unclassed.SnapletSplice b v)]
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
200 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
201 -> Handler b v a
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
202 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
203 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
204 withSplices = Unclassed.withSplices' heistLens
205
206
207 ------------------------------------------------------------------------------
208 -- | Runs a handler with a modified 'TemplateState'. You might want to use
209 -- this if you had a set of splices which were customised for a specific
210 -- action. To do that you would do:
211 --
212 -- > heistLocal (bindSplices mySplices) handlerThatNeedsSplices
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
213 heistLocal :: HasHeist b
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
214 => (TemplateState (Handler b b) -> TemplateState (Handler b b))
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
215 -- ^ TemplateState modifying function
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
216 -> Handler b v a
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
217 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
218 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
219 heistLocal = Unclassed.heistLocal' heistLens
220
221
222 -- $spliceSection
223 -- As can be seen in the type signature of heistLocal, the internal
224 -- TemplateState used by the heist snaplet is parameterized by (Handler b b).
225 -- The reasons for this are beyond the scope of this discussion, but the
226 -- result is that 'lift' inside a splice only works with @Handler b b@
227 -- actions. When you're writing your own snaplets you obviously would rather
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
228 -- work with @Handler b v@ so your local snaplet's state is available. We
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
229 -- provide the SnapletHeist monad to make this possible. The general rule is
230 -- that when you're using Snaplets and Heist, use SnapletHeist instead of
231 -- HeistT (previously called TemplateMonad) and use SnapletSplice instead of
232 -- Splice.
233
Something went wrong with that request. Please try again.