Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 238 lines (198 sloc) 8.786 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 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
88 -- | Adds templates to the Heist HeistState. Other snaplets should use
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
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
44e9ddd @mightybyte Improve comments for addTemplates functions
mightybyte authored
93 -- ^ The url prefix for the template routes
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
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 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
99 -- | Adds templates to the Heist HeistState, and lets you specify where
44e9ddd @mightybyte Improve comments for addTemplates functions
mightybyte authored
100 -- they are found in the filesystem. Note that the path to the template
101 -- directory is an absolute path. This allows you more flexibility in where
102 -- your templates are located, but means that you have to explicitly call
103 -- getSnapletFilePath if you want your snaplet to use templates within its
104 -- normal directory structure.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
105 addTemplatesAt :: HasHeist b
106 => ByteString
107 -- ^ URL prefix for template routes
108 -> FilePath
109 -- ^ Path to templates
110 -> Initializer b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
111 addTemplatesAt pfx p = withTop' heistLens (Unclassed.addTemplatesAt pfx p)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
112
113
114 ------------------------------------------------------------------------------
115 -- | Allows snaplets to add splices.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
116 addSplices :: (HasHeist b)
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
117 => [(Text, Unclassed.SnapletSplice b v)]
118 -- ^ Splices to bind
119 -> Initializer b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
120 addSplices = Unclassed.addSplices' heistLens
121
122
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored
123 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
124 -- | More general function allowing arbitrary HeistState modification.
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored
125 -- Without this function you wouldn't be able to bind more complicated splices
126 -- like the cache tag.
127 modifyHeistTS :: (HasHeist b)
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
128 => (HeistState (Handler b b) -> HeistState (Handler b b))
129 -- ^ HeistState modifying function
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored
130 -> Initializer b v ()
131 modifyHeistTS = Unclassed.modifyHeistTS' heistLens
132
133
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored
134 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
135 -- | Runs a function on with the Heist snaplet's 'HeistState'.
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored
136 withHeistTS :: (HasHeist b)
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
137 => (HeistState (Handler b b) -> a)
138 -- ^ HeistState function to run
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored
139 -> Handler b v a
140 withHeistTS = Unclassed.withHeistTS' heistLens
141
142
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
143 -- $handlerSection
144 -- This section contains functions in the 'Handler' monad that you'll use in
145 -- processing requests.
146
147
148 ------------------------------------------------------------------------------
149 -- | Renders a template as text\/html. If the given template is not found,
150 -- this returns 'empty'.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
151 render :: HasHeist b
152 => ByteString
153 -- ^ Template name
154 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
155 render t = withTop' heistLens (Unclassed.render t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
156
157
158 ------------------------------------------------------------------------------
159 -- | Renders a template as the given content type. If the given template
160 -- is not found, this returns 'empty'.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
161 renderAs :: HasHeist b
162 => ByteString
163 -- ^ Content type to render with
164 -> ByteString
165 -- ^ Template name
166 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
167 renderAs ct t = withTop' heistLens (Unclassed.renderAs ct t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
168
169
170 ------------------------------------------------------------------------------
171 -- | Analogous to 'fileServe'. If the template specified in the request path
172 -- is not found, it returns 'empty'.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
173 heistServe :: HasHeist b => Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
174 heistServe = withTop' heistLens Unclassed.heistServe
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
175
176
177 ------------------------------------------------------------------------------
178 -- | Analogous to 'fileServeSingle'. If the given template is not found,
179 -- this throws an error.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
180 heistServeSingle :: HasHeist b
181 => ByteString
182 -- ^ Template name
183 -> Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored
184 heistServeSingle t = withTop' heistLens (Unclassed.heistServeSingle t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
185
186
187 ------------------------------------------------------------------------------
188 -- | Renders a template with a given set of splices. This is syntax sugar for
189 -- a common combination of heistLocal, bindSplices, and render.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
190 renderWithSplices :: HasHeist b
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
191 => ByteString
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
192 -- ^ Template name
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
193 -> [(Text, Unclassed.SnapletSplice b v)]
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
194 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
195 -> Handler b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
196 renderWithSplices = Unclassed.renderWithSplices' heistLens
197
198
199 ------------------------------------------------------------------------------
200 -- | Runs an action with additional splices bound into the Heist
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
201 -- 'HeistState'.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
202 withSplices :: HasHeist b
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
203 => [(Text, Unclassed.SnapletSplice b v)]
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
204 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
205 -> Handler b v a
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
206 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
207 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
208 withSplices = Unclassed.withSplices' heistLens
209
210
211 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
212 -- | Runs a handler with a modified 'HeistState'. You might want to use
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
213 -- this if you had a set of splices which were customised for a specific
214 -- action. To do that you would do:
215 --
216 -- > heistLocal (bindSplices mySplices) handlerThatNeedsSplices
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored
217 heistLocal :: HasHeist b
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
218 => (HeistState (Handler b b) -> HeistState (Handler b b))
219 -- ^ HeistState modifying function
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
220 -> Handler b v a
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored
221 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
222 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
223 heistLocal = Unclassed.heistLocal' heistLens
224
225
226 -- $spliceSection
227 -- As can be seen in the type signature of heistLocal, the internal
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored
228 -- HeistState used by the heist snaplet is parameterized by (Handler b b).
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
229 -- The reasons for this are beyond the scope of this discussion, but the
230 -- result is that 'lift' inside a splice only works with @Handler b b@
231 -- actions. When you're writing your own snaplets you obviously would rather
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored
232 -- work with @Handler b v@ so your local snaplet's state is available. We
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored
233 -- provide the SnapletHeist monad to make this possible. The general rule is
234 -- that when you're using Snaplets and Heist, use SnapletHeist instead of
235 -- HeistT (previously called TemplateMonad) and use SnapletSplice instead of
236 -- Splice.
237
Something went wrong with that request. Please try again.