Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 291 lines (242 sloc) 11.18 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
96eb6a0 @mightybyte Improve haddock docs for the Heist snaplet
mightybyte authored
18 , Unclassed.addConfig
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
19 , modifyHeistState
20 , withHeistState
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
21 , addSplices
22
96eb6a0 @mightybyte Improve haddock docs for the Heist snaplet
mightybyte authored
23 -- * Handler Functions
24 -- $handlerSection
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
25 , cRender
26 , cRenderAs
27 , cHeistServe
28 , cHeistServeSingle
29
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
30 , render
31 , renderAs
32 , heistServe
33 , heistServeSingle
34 , heistLocal
35 , withSplices
36 , renderWithSplices
37
38 -- * Writing Splices
39 -- $spliceSection
40 , Unclassed.SnapletHeist
8b01abb @mightybyte Get rid of SnapletHeist newtype
mightybyte authored
41 , Unclassed.SnapletCSplice
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
42 , Unclassed.SnapletISplice
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
43
44 , clearHeistCache
45 ) where
46
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored
47 ------------------------------------------------------------------------------
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
48 import Prelude hiding (id, (.))
49 import Data.ByteString (ByteString)
50 import Data.Text (Text)
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
51 import Heist
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored
52 ------------------------------------------------------------------------------
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
53 import Snap.Snaplet
54 import qualified Snap.Snaplet.HeistNoClass as Unclassed
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored
55 import Snap.Snaplet.HeistNoClass ( Heist
56 , heistInit
57 , heistInit'
58 , clearHeistCache
59 )
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
60
61
62 ------------------------------------------------------------------------------
63 -- | A single snaplet should never need more than one instance of Heist as a
64 -- subsnaplet. This type class allows you to make it easy for other snaplets
65 -- to get the lens that identifies the heist snaplet. Here's an example of
66 -- how the heist snaplet might be declared:
67 --
68 -- > data App = App { _heist :: Snaplet (Heist App) }
e74cc19 @statusfailed Update src/Snap/Snaplet/Heist.hs
statusfailed authored
69 -- > makeLenses ''App
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
70 -- >
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
71 -- > instance HasHeist App where heistLens = subSnaplet heist
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
72 -- >
73 -- > appInit = makeSnaplet "app" "" Nothing $ do
b2df047 @mightybyte Fixed stale haddock comment.
mightybyte authored
74 -- > h <- nestSnaplet "heist" heist $ heistInit "templates"
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
75 -- > addSplices myAppSplices
76 -- > return $ App h
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
77 class HasHeist b where
78 -- | A lens to the Heist snaplet. The b parameter to Heist will
79 -- typically be the base state of your application.
7a7072e @ekmett Refactored to use Loupes rather than ReifiedLenses
ekmett authored
80 heistLens :: SnapletLens (Snaplet b) (Heist b)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
81
82
83 -- $initializerSection
84 -- This section contains functions for use in setting up your Heist state
85 -- during initialization.
86
87
88 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
89 -- | Adds templates to the Heist HeistState. Other snaplets should use
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
90 -- this function to add their own templates. The templates are automatically
91 -- read from the templates directory in the current snaplet's filesystem root.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
92 addTemplates :: HasHeist b
b50d6c6 @mightybyte Get test suite building
mightybyte authored
93 => Snaplet (Heist b)
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
94 -> ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
95 -- ^ The url prefix for the template routes
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
96 -> Initializer b v ()
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
97 addTemplates h pfx = withTop' heistLens (Unclassed.addTemplates h pfx)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
98
99
100 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
101 -- | Adds templates to the Heist HeistState, and lets you specify where
44e9ddd @mightybyte Improve comments for addTemplates functions
mightybyte authored
102 -- they are found in the filesystem. Note that the path to the template
103 -- directory is an absolute path. This allows you more flexibility in where
104 -- your templates are located, but means that you have to explicitly call
105 -- getSnapletFilePath if you want your snaplet to use templates within its
106 -- normal directory structure.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
107 addTemplatesAt :: HasHeist b
b50d6c6 @mightybyte Get test suite building
mightybyte authored
108 => Snaplet (Heist b)
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
109 -> ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
110 -- ^ URL prefix for template routes
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
111 -> FilePath
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
112 -- ^ Path to templates
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
113 -> Initializer b v ()
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
114 addTemplatesAt h pfx p =
115 withTop' heistLens (Unclassed.addTemplatesAt h pfx p)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
116
117
118 ------------------------------------------------------------------------------
96eb6a0 @mightybyte Improve haddock docs for the Heist snaplet
mightybyte authored
119 -- | Allows snaplets to add interpreted splices.
120 --
121 -- NOTE: The splices added with this function will not work if you render your
122 -- templates with cRender. To add splices that work with cRender, you have to
123 -- use the addConfig function to add compiled splices or load time splices.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
124 addSplices :: (HasHeist b)
8b01abb @mightybyte Get rid of SnapletHeist newtype
mightybyte authored
125 => [(Text, Unclassed.SnapletISplice b)]
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
126 -- ^ Splices to bind
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
127 -> Initializer b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
128 addSplices = Unclassed.addSplices' heistLens
129
130
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored
131 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
132 -- | More general function allowing arbitrary HeistState modification.
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
133 modifyHeistState :: (HasHeist b)
134 => (HeistState (Handler b b) -> HeistState (Handler b b))
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
135 -- ^ HeistState modifying function
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
136 -> Initializer b v ()
137 modifyHeistState = Unclassed.modifyHeistState' heistLens
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored
138
139
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored
140 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
141 -- | Runs a function on with the Heist snaplet's 'HeistState'.
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
142 withHeistState :: (HasHeist b)
143 => (HeistState (Handler b b) -> a)
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
144 -- ^ HeistState function to run
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
145 -> Handler b v a
146 withHeistState = Unclassed.withHeistState' heistLens
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored
147
148
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
149 -- $handlerSection
150 -- This section contains functions in the 'Handler' monad that you'll use in
96eb6a0 @mightybyte Improve haddock docs for the Heist snaplet
mightybyte authored
151 -- processing requests. Functions beginning with a 'c' prefix use compiled
152 -- template rendering. The other functions use the older interpreted
153 -- rendering. Splices added with addSplices will only work if you use
154 -- interpreted rendering.
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
155
156
157 ------------------------------------------------------------------------------
158 -- | Renders a template as text\/html. If the given template is not found,
159 -- this returns 'empty'.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
160 render :: HasHeist b
161 => ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
162 -- ^ Template name
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
163 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
164 render t = withTop' heistLens (Unclassed.render t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
165
166
167 ------------------------------------------------------------------------------
168 -- | Renders a template as the given content type. If the given template
169 -- is not found, this returns 'empty'.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
170 renderAs :: HasHeist b
171 => ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
172 -- ^ Content type to render with
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
173 -> ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
174 -- ^ Template name
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
175 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
176 renderAs ct t = withTop' heistLens (Unclassed.renderAs ct t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
177
178
179 ------------------------------------------------------------------------------
103bf47 @mightybyte More documentation
mightybyte authored
180 -- | Renders a compiled template as text\/html. If the given template is not
181 -- found, this returns 'empty'.
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
182 cRender :: HasHeist b
183 => ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
184 -- ^ Template name
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
185 -> Handler b v ()
186 cRender t = withTop' heistLens (Unclassed.cRender t)
187
188
189 ------------------------------------------------------------------------------
103bf47 @mightybyte More documentation
mightybyte authored
190 -- | Renders a compiled template as the given content type. If the given
191 -- template is not found, this returns 'empty'.
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
192 cRenderAs :: HasHeist b
193 => ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
194 -- ^ Content type to render with
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
195 -> ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
196 -- ^ Template name
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
197 -> Handler b v ()
198 cRenderAs ct t = withTop' heistLens (Unclassed.cRenderAs ct t)
199
200
201 ------------------------------------------------------------------------------
432e2fc @mightybyte Update heistServe docs
mightybyte authored
202 -- | A handler that serves all the templates (similar to 'serveDirectory').
203 -- If the template specified in the request path is not found, it returns
204 -- 'empty'. Also, this function does not serve any templates beginning with
205 -- an underscore. This gives you a way to prevent some templates from being
34870ed @mightybyte Clarify heistServe documentation
mightybyte authored
206 -- served. For example, you might have a template that contains only the
207 -- navbar of your pages, and you probably wouldn't want that template to be
208 -- visible to the user as a standalone template. So if you put it in a file
209 -- called \"_nav.tpl\", this function won't serve it.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
210 heistServe :: HasHeist b => Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
211 heistServe = withTop' heistLens Unclassed.heistServe
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
212
213
214 ------------------------------------------------------------------------------
34870ed @mightybyte Clarify heistServe documentation
mightybyte authored
215 -- | Handler for serving a single template (similar to 'fileServeSingle'). If
216 -- the given template is not found, this throws an error.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
217 heistServeSingle :: HasHeist b
218 => ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
219 -- ^ Template name
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
220 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
221 heistServeSingle t = withTop' heistLens (Unclassed.heistServeSingle t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
222
223
224 ------------------------------------------------------------------------------
b107117 @mightybyte Don't render templates if the name begins with underscore
mightybyte authored
225 -- | A compiled version of 'heistServe'.
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
226 cHeistServe :: HasHeist b => Handler b v ()
227 cHeistServe = withTop' heistLens Unclassed.cHeistServe
228
229
230 ------------------------------------------------------------------------------
231 -- | Analogous to 'fileServeSingle'. If the given template is not found,
232 -- this throws an error.
233 cHeistServeSingle :: HasHeist b
234 => ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
235 -- ^ Template name
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
236 -> Handler b v ()
237 cHeistServeSingle t = withTop' heistLens (Unclassed.cHeistServeSingle t)
238
239
240 ------------------------------------------------------------------------------
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
241 -- | Renders a template with a given set of splices. This is syntax sugar for
242 -- a common combination of heistLocal, bindSplices, and render.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
243 renderWithSplices :: HasHeist b
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
244 => ByteString
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
245 -- ^ Template name
8b01abb @mightybyte Get rid of SnapletHeist newtype
mightybyte authored
246 -> [(Text, Unclassed.SnapletISplice b)]
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
247 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
248 -> Handler b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
249 renderWithSplices = Unclassed.renderWithSplices' heistLens
250
251
252 ------------------------------------------------------------------------------
253 -- | Runs an action with additional splices bound into the Heist
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
254 -- 'HeistState'.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
255 withSplices :: HasHeist b
8b01abb @mightybyte Get rid of SnapletHeist newtype
mightybyte authored
256 => [(Text, Unclassed.SnapletISplice b)]
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
257 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
258 -> Handler b v a
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
259 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
260 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
261 withSplices = Unclassed.withSplices' heistLens
262
263
264 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
265 -- | Runs a handler with a modified 'HeistState'. You might want to use
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
266 -- this if you had a set of splices which were customised for a specific
267 -- action. To do that you would do:
268 --
269 -- > heistLocal (bindSplices mySplices) handlerThatNeedsSplices
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
270 heistLocal :: HasHeist b
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
271 => (HeistState (Handler b b) -> HeistState (Handler b b))
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
272 -- ^ HeistState modifying function
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
273 -> Handler b v a
bc66dcc @mightybyte Indent next-line --^ comments
mightybyte authored
274 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
275 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
276 heistLocal = Unclassed.heistLocal' heistLens
277
278
279 -- $spliceSection
280 -- As can be seen in the type signature of heistLocal, the internal
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
281 -- HeistState used by the heist snaplet is parameterized by (Handler b b).
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
282 -- The reasons for this are beyond the scope of this discussion, but the
283 -- result is that 'lift' inside a splice only works with @Handler b b@
284 -- actions. When you're writing your own snaplets you obviously would rather
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
285 -- work with @Handler b v@ so your local snaplet's state is available. We
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
286 -- provide the SnapletHeist monad to make this possible. The general rule is
287 -- that when you're using Snaplets and Heist, use SnapletHeist instead of
aece75e @mightybyte Converted the Heist snaplet to Heist 0.10
mightybyte authored
288 -- HeistT (previously called TemplateMonad) and use SnapletISplice instead of
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
289 -- Splice.
290
Something went wrong with that request. Please try again.