Skip to content
Newer
Older
100644 234 lines (194 sloc) 8.31 KB
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored Dec 10, 2011
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 Jul 25, 2011
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 Nov 29, 2011
15 , heistInit'
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
16 , addTemplates
17 , addTemplatesAt
a35696c @mightybyte Style nazi strikes again.
mightybyte authored Oct 27, 2011
18 , modifyHeistTS
19 , withHeistTS
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 wo…
mightybyte authored Oct 11, 2011
38 , Unclassed.liftAppHandler
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
39 , Unclassed.liftWith
40 , Unclassed.bindSnapletSplices
41
42 , clearHeistCache
43 ) where
44
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored Dec 10, 2011
45 ------------------------------------------------------------------------------
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
46 import Prelude hiding (id, (.))
47 import Data.ByteString (ByteString)
c28c4b4 @mightybyte Switched from fclabels to data-lens.
mightybyte authored Aug 11, 2011
48 import Data.Lens.Lazy
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
49 import Data.Text (Text)
50 import Text.Templating.Heist
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored Dec 10, 2011
51 ------------------------------------------------------------------------------
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
52 import Snap.Snaplet
53 import qualified Snap.Snaplet.HeistNoClass as Unclassed
1e3cfe3 @gregorycollins More code cleanup
gregorycollins authored Dec 10, 2011
54 import Snap.Snaplet.HeistNoClass ( Heist
55 , heistInit
56 , heistInit'
57 , clearHeistCache
58 )
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Aug 3, 2011
70 -- > instance HasHeist App where heistLens = subSnaplet heist
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
71 -- >
72 -- > appInit = makeSnaplet "app" "" Nothing $ do
b2df047 @mightybyte Fixed stale haddock comment.
mightybyte authored Nov 29, 2011
73 -- > h <- nestSnaplet "heist" heist $ heistInit "templates"
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
74 -- > addSplices myAppSplices
75 -- > return $ App h
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored Aug 3, 2011
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 Aug 11, 2011
79 heistLens :: Lens (Snaplet b) (Snaplet (Heist b))
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Dec 10, 2011
88 -- | Adds templates to the Heist HeistState. Other snaplets should use
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Nov 29, 2011
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 Jul 27, 2011
95 addTemplates pfx = withTop' heistLens (Unclassed.addTemplates pfx)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
96
97
98 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
99 -- | Adds templates to the Heist HeistState, and lets you specify where
e88b397 @mightybyte Restructured auth snaplet to improve haddock structure. Other misc wo…
mightybyte authored Oct 12, 2011
100 -- they are found in the filesystem.
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored Nov 29, 2011
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 Jul 27, 2011
107 addTemplatesAt pfx p = withTop' heistLens (Unclassed.addTemplatesAt pfx p)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
108
109
110 ------------------------------------------------------------------------------
111 -- | Allows snaplets to add splices.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored Aug 3, 2011
112 addSplices :: (HasHeist b)
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored Nov 29, 2011
113 => [(Text, Unclassed.SnapletSplice b v)]
114 -- ^ Splices to bind
115 -> Initializer b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
116 addSplices = Unclassed.addSplices' heistLens
117
118
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored Oct 15, 2011
119 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
120 -- | More general function allowing arbitrary HeistState modification.
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored Oct 16, 2011
121 -- Without this function you wouldn't be able to bind more complicated splices
122 -- like the cache tag.
123 modifyHeistTS :: (HasHeist b)
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
124 => (HeistState (Handler b b) -> HeistState (Handler b b))
125 -- ^ HeistState modifying function
5725a77 @mightybyte Added modifyHeistTS
mightybyte authored Oct 16, 2011
126 -> Initializer b v ()
127 modifyHeistTS = Unclassed.modifyHeistTS' heistLens
128
129
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored Oct 19, 2011
130 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
131 -- | Runs a function on with the Heist snaplet's 'HeistState'.
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored Oct 19, 2011
132 withHeistTS :: (HasHeist b)
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
133 => (HeistState (Handler b b) -> a)
134 -- ^ HeistState function to run
8ba2b3b @mightybyte Allow access to the Heist snaplet's TemplateState.
mightybyte authored Oct 19, 2011
135 -> Handler b v a
136 withHeistTS = Unclassed.withHeistTS' heistLens
137
138
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Nov 29, 2011
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 Jul 27, 2011
151 render t = withTop' heistLens (Unclassed.render t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Nov 29, 2011
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 Jul 27, 2011
163 renderAs ct t = withTop' heistLens (Unclassed.renderAs ct t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Aug 3, 2011
169 heistServe :: HasHeist b => Handler b v ()
b8204ee @mightybyte Change HasHeist implementation to fix test cases failing after last c…
mightybyte authored Jul 27, 2011
170 heistServe = withTop' heistLens Unclassed.heistServe
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Nov 29, 2011
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 Jul 27, 2011
180 heistServeSingle t = withTop' heistLens (Unclassed.heistServeSingle t)
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Aug 3, 2011
186 renderWithSplices :: HasHeist b
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
187 => ByteString
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored Nov 29, 2011
188 -- ^ Template name
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored Aug 1, 2011
189 -> [(Text, Unclassed.SnapletSplice b v)]
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored Nov 29, 2011
190 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored Aug 1, 2011
191 -> Handler b v ()
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
192 renderWithSplices = Unclassed.renderWithSplices' heistLens
193
194
195 ------------------------------------------------------------------------------
196 -- | Runs an action with additional splices bound into the Heist
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
197 -- 'HeistState'.
d109d46 @mightybyte Simplified HasHeist down to just one type parameter.
mightybyte authored Aug 3, 2011
198 withSplices :: HasHeist b
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored Aug 1, 2011
199 => [(Text, Unclassed.SnapletSplice b v)]
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored Nov 29, 2011
200 -- ^ Splices to bind
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored Aug 1, 2011
201 -> Handler b v a
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored Nov 29, 2011
202 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored Aug 1, 2011
203 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
204 withSplices = Unclassed.withSplices' heistLens
205
206
207 ------------------------------------------------------------------------------
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
208 -- | Runs a handler with a modified 'HeistState'. You might want to use
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Aug 3, 2011
213 heistLocal :: HasHeist b
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
214 => (HeistState (Handler b b) -> HeistState (Handler b b))
215 -- ^ HeistState modifying function
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored Aug 1, 2011
216 -> Handler b v a
c00a838 @mightybyte Added haddock parameter descriptions for Heist snaplet functions.
mightybyte authored Nov 29, 2011
217 -- ^ Handler to run
b8a1e4f @mightybyte Changed type variable e to v everywhere.
mightybyte authored Aug 1, 2011
218 -> Handler b v a
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
219 heistLocal = Unclassed.heistLocal' heistLens
220
221
222 -- $spliceSection
223 -- As can be seen in the type signature of heistLocal, the internal
0d75768 @gregorycollins Remove deprecated TemplateState.
gregorycollins authored Dec 10, 2011
224 -- HeistState used by the heist snaplet is parameterized by (Handler b b).
b0fadff @mightybyte Alpha release of new snaplet infrastructure.
mightybyte authored Jul 25, 2011
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 Aug 1, 2011
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 Jul 25, 2011
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.