This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "snap-website".
The branch, master has been updated
via 887ac720ace7ff4b408beeea9487c6845afb6296 (commit)
via 8c504125155d748747a78be13771023380f42566 (commit)
via 565cce6e694d5268d08958a158ef1e2b3605be79 (commit)
via 7072967cf243e99286060951338a46b73b3f5edc (commit)
via c3721ad1a0e017c5e5ff3f76eda4a14242d715ff (commit)
via a466b7153e15c5bfe2740cc45cd325458c7625a6 (commit)
via 72f49a9f68134db98e91a454d8d2e1437c2e4b46 (commit)
via 9ff0e9f6ee7f3074becbe4a07a0302ba230c5d13 (commit)
from 4fcbab68899421de07c0d5726fbd1768ad882188 (commit)
Summary of changes:
snap-website.cabal | 8 +-
src/Main.hs | 28 ++--
templates/about.tpl | 66 ++++++----
templates/docs.tpl | 6 +-
templates/docs/quickstart.md | 18 ---
templates/docs/tutorials/heist.md | 143 ++++++++++++++------
.../tutorials/{snap-api-0.3.md => snap-api-0.4.md} | 12 +-
templates/docs/tutorials/snap-api.tpl | 2 +-
templates/download.tpl | 4 +-
templates/faq.md | 6 -
templates/index.tpl | 2 +-
11 files changed, 172 insertions(+), 123 deletions(-)
copy templates/docs/tutorials/{snap-api-0.3.md => snap-api-0.4.md} (94%)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 887ac720ace7ff4b408beeea9487c6845afb6296
Merge: 4fcbab6 8c50412
Author: Gregory Collins <[email protected]>
Date: Sat Feb 5 14:56:25 2011 -0500
Merge branch 'master' of github.com:snapframework/snap-website
commit 8c504125155d748747a78be13771023380f42566
Author: Chris Smith <[email protected]>
Date: Tue Jan 18 14:49:05 2011 -0700
Update heist to note HTML compatibility issue
diff --git a/templates/docs/tutorials/heist.md
b/templates/docs/tutorials/heist.md
index 9ea0119..13389d6 100644
--- a/templates/docs/tutorials/heist.md
+++ b/templates/docs/tutorials/heist.md
@@ -330,26 +330,61 @@ the `<ignore>` tag for this purpose. All `<ignore>` tags
and their
contents will be eliminated in a template's output.
-### XML Syntax
-
-By default, Heist templates have an extension of `.tpl`. When used this way,
-Heist understands and makes use of HTML 5 syntax. It is, however, also
-possible to name templates `.xtpl`, in which case Heist will process them as
-plain XML without any HTML-specific rules.
-
-The differences between these two modes are small, but can sometimes matter.
-Using Heist with HTML templates (with a `.tpl` extension) means Heist will
-accept markup that is not valid XML; for example, it understands special tags
-like `<br>`, `<textarea>`, `<script>`, and `<p>` that are empty, have optional
-end tags, or contain content in other languages. Heist also won't mangle your
-JavaScript and stylesheets with escape sequences, or do other things that may
-confuse web browsers, in its output.
-
-On the other hand, some applications may need to produce well-formed XML
-output and may not be producing HTML at all. In this case, templates should
-use Heist's XML mode by using the `.xtpl` extension on templates. XML mode
+### HTML and XML Syntax
+
+By default, and throughout this tutorial, Heist templates have an extension
+of `.tpl`. When used this way, Heist understands and makes use of HTML 5
+syntax. This is the easiest way to use Heist; your experience writing HTML
+will generally serve you well. It is, however, also possible to name
+templates with the extension `.xtpl`. In this case, Heist will process the
+template as an XML document, without any HTML-specific rules.
+
+When templates are written in HTML, Heist is a little less forgiving than
+your web browser. That's because you may write splices that depend on a
+certain structure of your document, so when the structure is unclear, Heist
+will tell you. For example, consider this piece of HTML code.
+
+~~~~~~~~~~~~~~~ {.html}
+<p>
+ These are a few of my favorite things.
+ <ul>
+ <li>Raindrops on roses and whiskers on kittens
+ <li>Bright copper kettles and warm woolen mittens
+ <li>Brown paper packages tied up with strings.
+ </ul>
+</p>
+~~~~~~~~~~~~~~~
+
+First, notice that none of the `<li>` tags have end tags. This is okay. HTML
+allows you to omit the end tags for list items. However, there is an error
+here. A paragraph in HTML is not allowed to contain a list. Since you are
+also allowed to omit the end tag for `<p>`, Heist ends the paragraph when the
+list starts. But then the explicit closing `</p>` tag is mismatched. A web
+browser will often ignore this, so many people don't even realize it is
+incorrect; but since it affects the structure of your document and therefore
+might affect a splice, Heist does not ignore it, and reports an error. You can
+fix the error by not using closing tags on `<p>` elements, or by moving the
+closing tag to before the list.
+
+HTML mode also includes special rules for tags that are always empty (like
+`<br>` and `<input>`), and tags whose contents contain other languages besides
+HTML (like `<script>` and `<style>`), among other things. Heist is also
+careful to write its output in a way that web browsers will understand. For
+example, it will always write `<textarea></textarea>` rather than using an
+empty tag style, and it will normally avoid escaping characters in attributes
+unless it's absolutely needed. In general, you can not worry about these
+things and trust that Heist is writing your output in the most compatible way
+it can.
+
+On the other hand, some applications may want to provide templates in
+well-formed XML, and need to produce well-formed XML output. Perhaps you're
+using XHTML, or not using HTML at all! In this case, templates should use
+Heist's XML mode by using the `.xtpl` extension on templates. XML mode
disables Heist's understanding of the HTML language, and treats the template
-as plain XML.
+as plain XML. There are a few restrictions: for example, processing
+instructions are dropped from the document, and you may not define your own
+entities and use them in the document; but the output will always be
+well-formed XML.
## Heist Programming
commit 565cce6e694d5268d08958a158ef1e2b3605be79
Author: Chris Smith <[email protected]>
Date: Mon Jan 17 17:30:39 2011 -0700
Add information to developers list
diff --git a/templates/about.tpl b/templates/about.tpl
index a964e48..6ffc091 100644
--- a/templates/about.tpl
+++ b/templates/about.tpl
@@ -125,6 +125,14 @@
science and modeling. He uses Haskell at work to help companies
make sound business decisions.
</p>
+ <p>
+ <strong><a href="http://github.com/cdsmith";>Chris Smith</a>
+ </strong> is a software developer and owner of the eLearning
+ company <a href="http://www.brindlewaye.com";>Brindle Waye</a>.
+ He has been developing web applications for about ten years, and
+ free software for about fifteen. He is also an amateur algebraist,
+ doing research in ring theory.
+ </p>
</div><!--end developers-->
<div>
<h2>Contacting us</h2>
commit 7072967cf243e99286060951338a46b73b3f5edc
Author: Chris Smith <[email protected]>
Date: Mon Jan 17 17:18:35 2011 -0700
Update to xmlhtml (code and documentation)
diff --git a/snap-website.cabal b/snap-website.cabal
index 6e96c54..ea28082 100644
--- a/snap-website.cabal
+++ b/snap-website.cabal
@@ -23,19 +23,19 @@ Executable snap-website
filepath,
haskell98,
heist,
- hexpat,
MonadCatchIO-transformers >= 0.2 && < 0.3,
monads-fd,
process,
- snap-core >= 0.3 && <0.4,
- snap-server >= 0.3 && <0.4,
+ snap-core >= 0.3 && <0.5,
+ snap-server >= 0.3 && <0.5,
snap-static-pages >= 0.1 && <1.0,
text,
time,
transformers,
unix,
utf8-string,
- xhtml-combinators >= 0.2.2 && < 0.3
+ xhtml-combinators >= 0.2.2 && < 0.3,
+ xmlhtml ==0.1.*
ghc-prof-options: -prof -auto-all
diff --git a/src/Main.hs b/src/Main.hs
index d92f480..02def06 100644
--- a/src/Main.hs
+++ b/src/Main.hs
@@ -9,7 +9,9 @@ import Data.ByteString.Char8 (ByteString)
import qualified Data.ByteString.Char8 as B
import qualified Data.Map as Map
import Data.Maybe
+import Data.Text (Text)
import qualified Data.Text as T
+import qualified Data.Text.Encoding as T
import Data.Time.Clock.POSIX
import Data.Typeable
import Control.Applicative
@@ -31,7 +33,7 @@ import System.Posix.Env
import Text.Templating.Heist
import Text.Templating.Heist.Splices.Static
import qualified Text.XHtmlCombinators.Escape as XH
-import Text.XML.Expat.Tree hiding (Node)
+import Text.XmlHtml hiding (Node)
@@ -103,7 +105,7 @@ renderTmpl :: MVar (TemplateState Snap)
-> Snap ()
renderTmpl tsMVar n = do
ts <- liftIO $ readMVar tsMVar
- maybe pass writeBS =<< renderTemplate ts n
+ maybe pass (writeBuilder . fst) =<< renderTemplate ts n
templateServe :: MVar (TemplateState Snap)
@@ -132,13 +134,13 @@ site ss =
, ("admin/reload", runReaderT reload ss)
, ("blog/", serveStaticPages (_blogState ss)) ] <|>
templateServe (_currentTs ss) <|>
- (setCache $ fileServe "static")
+ (setCache $ serveDirectory "static")
where
setCache act = do
- pi <- liftM rqPathInfo getRequest
+ pinfo <- liftM rqPathInfo getRequest
act
- when ("media" `B.isPrefixOf` pi) $ do
+ when ("media" `B.isPrefixOf` pinfo) $ do
expTime <- liftM (+604800) $ liftIO epochTime
s <- liftIO $ formatHttpTime expTime
modifyResponse $
@@ -181,25 +183,25 @@ apidoc = do
lift $ do
ts <- liftIO $ readMVar $ _currentTs ss
-- remainder of pathInfo is the doc to lookup
- whichDoc <- liftM rqPathInfo getRequest
+ whichDoc <- liftM (T.decodeUtf8 . rqPathInfo) getRequest
title <- maybe pass return $ Map.lookup whichDoc titles
- let href = B.concat ["/docs/latest/", whichDoc, "/index.html"]
+ let href = T.concat ["/docs/latest/", whichDoc, "/index.html"]
let ts' = bindSplice "docframe" (docframe href) $
- bindSplice "subtitle" (return [mkText title]) ts
+ bindSplice "subtitle" (return [TextNode title]) ts
modifyResponse $ setContentType "text/html"
- maybe pass writeBS =<< renderTemplate ts' "docs/api"
+ maybe pass (writeBuilder . fst) =<< renderTemplate ts' "docs/api"
where
titles = Map.fromList [ ("snap-core", ": snap-core APIs")
, ("snap-server", ": snap-server APIs")
, ("heist", ": heist APIs") ]
- docframe :: ByteString -> Splice Snap
- docframe src = return [ mkElement "frame" [ ("id" , "docframe")
- , ("src", src ) ] [] ]
+ docframe :: Text -> Splice Snap
+ docframe src = return [ Element "frame" [ ("id" , "docframe")
+ , ("src", src ) ] [] ]
@@ -209,7 +211,7 @@ apidoc = do
-- MISC UTILITIES
------------------------------------------------------------------------------
serverVersion :: Splice Snap
-serverVersion = return $ [Text snapServerVersion]
+serverVersion = return [TextNode (T.decodeUtf8 snapServerVersion)]
setLocaleToUTF8 :: IO ()
diff --git a/templates/about.tpl b/templates/about.tpl
index 34453ae..a964e48 100644
--- a/templates/about.tpl
+++ b/templates/about.tpl
@@ -13,15 +13,16 @@
<p>
<strong>Snap</strong> aims to be the <i>de facto</i> web toolkit
for Haskell, on the basis of:
- <ul>
- <li>High performance</li>
- <li>High design standards</li>
- <li>Simplicity and ease of use, even for Haskell beginners</li>
- <li>Excellent documentation</li>
- <li>Robustness and high test coverage</li>
- </ul>
</p>
+ <ul>
+ <li>High performance</li>
+ <li>High design standards</li>
+ <li>Simplicity and ease of use, even for Haskell beginners</li>
+ <li>Excellent documentation</li>
+ <li>Robustness and high test coverage</li>
+ </ul>
+
<p class="foundabug"><b>Found a bug in Snap? Please visit our <a
href="http://github.com/snapframework/snap-core/issues";>issue
tracker.</a></b></p>
@@ -30,34 +31,37 @@
<p>
The first developer prerelease of the Snap framework is available
now. It contains only the Snap core system, namely:
- <ul>
- <li>A fast HTTP server library with an optional high-concurrency
- backend using
- the <a
href="http://software.schmorp.de/pkg/libev.html";>libev</a>
- event loop library.</li>
- <li>A sensible and clean monad for web programming.</li>
- <li>an HTML-based templating system for generating pages that
allows
- you to bind Haskell functionality to tags without getting
- PHP-style tag soup all over your pants</li>
- </ul>
</p>
+ <ul>
+ <li>A fast HTTP server library with an optional high-concurrency
+ backend using
+ the <a href="http://software.schmorp.de/pkg/libev.html";>libev</a>
+ event loop library.</li>
+ <li>A sensible and clean monad for web programming.</li>
+ <li>an HTML-based templating system for generating pages that allows
+ you to bind Haskell functionality to tags without getting
+ PHP-style tag soup all over your pants</li>
+ </ul>
+
<p>
Higher-level facilities for building web applications (like
user/session management, component interfaces, data modeling, etc.)
are planned but not yet implemented, so this release will mostly be
of interest to those who:
- <ul>
- <li>
- need a fast and minimal HTTP API at roughly the same level of
- abstraction as Java servlets, or
- </li>
- <li>
- are interested in contributing to the Snap Framework
- project.
- </li>
- </ul>
</p>
+
+ <ul>
+ <li>
+ need a fast and minimal HTTP API at roughly the same level of
+ abstraction as Java servlets, or
+ </li>
+ <li>
+ are interested in contributing to the Snap Framework
+ project.
+ </li>
+ </ul>
+
<p>
Snap runs on *nix platforms; it has been tested on Linux and Mac OSX
Snow Leopard. Windows support was added more recently, but it not
commit c3721ad1a0e017c5e5ff3f76eda4a14242d715ff
Author: Chris Smith <[email protected]>
Date: Sun Jan 16 16:26:41 2011 -0700
Add file I forgot
diff --git a/templates/docs/tutorials/snap-api-0.4.md
b/templates/docs/tutorials/snap-api-0.4.md
new file mode 100644
index 0000000..c7b8c43
--- /dev/null
+++ b/templates/docs/tutorials/snap-api-0.4.md
@@ -0,0 +1,168 @@
+## Installation
+
+The exposed Snap API is on the same level of abstraction as Java Servlets. If
+you understand servlets, most of the rest of the tutorial should be very
+self-explanatory. Even if you don't, have no fear! The following tutorial only
+expects that you know a little bit of Haskell.
+
+Before we dive into writing our first Snap web application, let's do a quick
+overview of the parts of the Snap framework. Currently Snap is divided into
+four components:
+
+
+ - `snap-core` is the core of Snap. It includes type definitions and all code
+ that is server-agnostic.
+
+ - `snap-server` is an HTTP server library built on top of `snap-core`. It
+ currently includes a backend using stock Haskell socket I/O and a backend
+ which uses the [libev](http://software.schmorp.de/pkg/libev.html) O(1) event
+ loop library.
+
+ - `heist` is the HTML templating library. You do not need it to use Snap,
+ but you are certainly welcome to.
+
+ - `snap` is a library which contains some useful routines for building Snap
+ sites and a `snap` executable which generates a skeleton project to get you
+ started.
+
+To install Snap, simply use `cabal`. It's up to you whether or not you want to
+use the Heist templating library; that said, as of version 0.3 heist is a
+dependency for the snap project starter (although, again, you're not forced to
+use it), and our example below does use it.
+
+~~~~~~ {.shell}
+$ cabal install snap
+~~~~~~
+
+## Hello, Snap!
+
+To generate a skeleton Snap web application, the `snap` package installs an
+executable `snap` into `$HOME/.cabal/bin`. We can use that to create our "Hello
+Snap" application.
+
+(If you do not want to use `heist`, you should execute `snap init -b` instead
+of `snap init` for a bare-bones skeleton that does not depend on `heist`.)
+
+~~~~~~ {.shell}
+$ mkdir hello-snap
+$ cd hello-snap
+$ snap init
+~~~~~~
+
+We now have a skeleton Snap project with a `.cabal` file and a source
+directory. Install it, run it, and see what your browser thinks of it.
+
+~~~~~~ {.shell}
+$ cabal install
+$ hello-snap -p 8000
+$ curl 'http://localhost:8000/'; echo
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHT
+...
+~~~~~~
+
+Make sure to try the some of the echo examples. When you are satisfied, we can
+kill the server by hitting `CTRL-C`.
+
+
+### Under the Hood
+
+Peeking in the `src` directory, we find the haskell files responsible for the
+simple demo page we start with.
+
+~~~~~ {.shell}
+$ cd src
+$ ls
+Application.hs Main.hs Site.hs
+~~~~~
+
+`Main.hs` contains the `main` entry point to the application. The default
+skeleton project contains some C preprocessor statements for optionally
+configuring the server to use [hint](http://hackage.haskell.org/package/hint)
+to dynamically load the site in "development" mode. If we ignore this for now,
+we see that `main` just starts up `snap-server` using our site's initialization
+and web handling routines:
+
+~~~~~~ {.haskell}
+main :: IO ()
+main = quickHttpServe applicationInitializer site
+~~~~~~
+
+The `Application.hs` file defines the `Application` type, which is the type of
+our site's web handlers. `Application` extends the default `Snap` handler type
+with some application-specific state, also defined in `Application.hs`.
+
+A handler (informally, for now) is a function, run by the Snap server, which
+takes an HTTP request and generates the server's Response, with a lot of the
+complexity sort of nudged away under the rug. The handlers currently being used
+by your sample app are defined in `Site.hs`.
+
+For example, here's the top-level Handler used by your sample app:
+
+~~~~~~ {.haskell}
+site :: Application ()
+site = route [ ("/", index)
+ , ("/echo/:stuff", echo)
+ ]
+ <|> serveDirectory "resources/static"
+~~~~~~
+
+This sets up a routing table for the site's URLs: requests for the "`/`" URL
+get routed to the "`index`" handler, and requests for "`/echo/foo`" get routed
+to the "`echo`" handler after we set "`stuff=foo`" in the request's parameter
+mapping.
+
+The second half of the site handler, after the main routing table, handles
+serving any files from the disk. The `a <|> b` syntax means: "try `a`, and if
+it fails, try `b`". In this case, if the user requests an URL that doesn't
+match any of the entries in the routing table --- like "`/screen.css`", for
+example --- the `fileServe` function will attempt to find the file under the
+"`resources/static`" directory, and will serve it back to the user if it is
+found. If the file is *not* found, the "serveDirectory" handler will fail,
+causing the `site` handler to fail, which will cause Snap to produce a
+"404 Not Found" response.
+
+
+Next, let's take a look at the `echo` handler:
+
+~~~~~ {.haskell}
+echo :: Application ()
+echo = do
+ message <- decodedParam "stuff"
+ heistLocal (bindString "message" message) $ render "echo"
+ where
+ decodedParam p = fromMaybe "" <$> getParam p
+~~~~~
+
+The `echo` handler takes the `stuff` parameter out of the parameters mapping
+(remember, "`stuff`" was bound using `route` above), binds its value to a
+`heist` tag, and then renders the "echo" template.
+
+A [lengthier Heist tutorial](/docs/tutorials/heist/) is available, but here's
+what you need to know for now: `heist` serves HTML templates, but with a
+twist: a tag element can be rebound to a Haskell function which replaces it
+with some programmatically-generated markup. In our case, the `echo` template
+lives in `resources/templates/echo.tpl`, and the "`<message>`" tag has been
+redefined to be substituted for the text that was entered by the user. The
+template looks like this:
+
+~~~~~ {.html}
+<body>
+ <div id="content">
+ <h1>Is there an echo in here?</h1>
+ </div>
+ <p>You wanted me to say this?</p>
+ <p>"<message/>"</p>
+ <p><a href="/">Return</a></p>
+</body>
+~~~~~
+
+
+## What Now?
+
+We hope we've whetted your appetite for using Snap. From here on out you should
+take a look at the [API documentation](/docs/latest/snap-core/index.html),
+which explains many of the concepts and functions here in further detail.
+
+You can also come hang out in
+[`#snapframework`](http://webchat.freenode.net/?channels=snapframework&uio=d4)
+on [`freenode`](http://freenode.net/).
commit a466b7153e15c5bfe2740cc45cd325458c7625a6
Author: Chris Smith <[email protected]>
Date: Sun Jan 16 16:18:54 2011 -0700
Additional cleanup to present Heist uniformly as an HTML templating system.
diff --git a/templates/docs.tpl b/templates/docs.tpl
index 4147ad4..39c095d 100644
--- a/templates/docs.tpl
+++ b/templates/docs.tpl
@@ -27,7 +27,7 @@
<a class="book" href="docs/tutorials/heist">
<img src="/media/css/book.png" />
</a>
- A tutorial for the Heist HTML and XML templating library.</dd>
+ A tutorial for the Heist HTML templating library.</dd>
</dl>
</div>
</div>
@@ -87,8 +87,8 @@
<a class="book" href="docs/latest/heist/index.html">
<img src="/media/css/book.png" />
</a>
- An xhtml-based templating engine, allowing Haskell functions to
- be bound to XML tags.</dd>
+ An HTML-based templating engine, allowing Haskell functions to
+ be bound to tags.</dd>
</dl>
</div>
</div>
diff --git a/templates/docs/tutorials/snap-api.tpl
b/templates/docs/tutorials/snap-api.tpl
index 5667deb..10abfc6 100644
--- a/templates/docs/tutorials/snap-api.tpl
+++ b/templates/docs/tutorials/snap-api.tpl
@@ -2,7 +2,7 @@
<static>
<apply template="page">
<div class="singlecolumn">
- <markdown file="docs/tutorials/snap-api-0.3.md"/>
+ <markdown file="docs/tutorials/snap-api-0.4.md"/>
</div>
</apply>
</static>
diff --git a/templates/download.tpl b/templates/download.tpl
index 8d213fc..f4603e1 100644
--- a/templates/download.tpl
+++ b/templates/download.tpl
@@ -72,7 +72,7 @@ $ cabal install snap</pre>
<dt>heist</dt>
- <dd>An HTML/XML-based templating engine, allowing Haskell
functions to be
+ <dd>An HTML-based templating engine, allowing Haskell functions to
be
bound to tags. <br/><span class="linklist">
[ <a href="/docs/latest/heist/index.html" >api docs</a> |
<a href="http://hackage.haskell.org/package/heist";
commit 72f49a9f68134db98e91a454d8d2e1437c2e4b46
Author: Chris Smith <[email protected]>
Date: Sun Jan 16 15:49:21 2011 -0700
Update to new version of heist
diff --git a/templates/about.tpl b/templates/about.tpl
index d5556d8..34453ae 100644
--- a/templates/about.tpl
+++ b/templates/about.tpl
@@ -36,8 +36,8 @@
the <a
href="http://software.schmorp.de/pkg/libev.html";>libev</a>
event loop library.</li>
<li>A sensible and clean monad for web programming.</li>
- <li>an XML-based templating system for generating HTML that allows
- you to bind Haskell functionality to XML tags without getting
+ <li>an HTML-based templating system for generating pages that
allows
+ you to bind Haskell functionality to tags without getting
PHP-style tag soup all over your pants</li>
</ul>
</p>
diff --git a/templates/docs.tpl b/templates/docs.tpl
index 7a0b3cf..4147ad4 100644
--- a/templates/docs.tpl
+++ b/templates/docs.tpl
@@ -27,7 +27,7 @@
<a class="book" href="docs/tutorials/heist">
<img src="/media/css/book.png" />
</a>
- A tutorial for the Heist xhtml templating library.</dd>
+ A tutorial for the Heist HTML and XML templating library.</dd>
</dl>
</div>
</div>
diff --git a/templates/docs/quickstart.md b/templates/docs/quickstart.md
index b5e492a..e97e3f0 100644
--- a/templates/docs/quickstart.md
+++ b/templates/docs/quickstart.md
@@ -12,24 +12,6 @@ PATH=$PATH:$HOME/.cabal/bin
to your `~/.bashrc` and run `source ~/.bashrc`. The following
instructions assume that `$HOME/.cabal/bin` is on your `$PATH`.
-Note also that before you start, you should have a development version of the
-`expat` library on your system; for instance, on Debian you would run:
-
-~~~~~~ {.shell}
-$ sudo apt-get install libexpat-dev
-~~~~~~
-
-and on Ubuntu you'd run:
-
-~~~~~~ {.shell}
-$ sudo apt-get install libexpat1-dev
-~~~~~~
-
-Mac OSX should already have the required C libraries installed. On Windows, see
-[this article by Jacob
-Stanley](http://jystic.com/2010/10/07/installing-heist-and-hexpat-on-windows/)
-for more information.
-
To set up a new Snap project, run the following commands:
~~~~~~ {.shell}
diff --git a/templates/docs/tutorials/heist.md
b/templates/docs/tutorials/heist.md
index 0c704b4..9ea0119 100644
--- a/templates/docs/tutorials/heist.md
+++ b/templates/docs/tutorials/heist.md
@@ -1,11 +1,9 @@
## Heist Templates
-Heist is an XML templating engine based loosely on ideas from the Lift
+Heist is a templating engine based loosely on ideas from the Lift
Web Framework. It functions as a bridge between your web application
-and its views. Heist templates are XML fragments that are not
-required to have a single root element. Heist uses hexpat, a haskell
-interface to the Expat XML library, for fast XML parsing and
-manipulation.
+and its views. Heist templates are HTML (or XML) fragments that are
+not required to have a single root element.
Heist is being developed by the Snap Team in conjunction with Snap,
but Heist is a completely standalone library with no dependencies on
@@ -25,16 +23,15 @@ DRY principle (Don't Repeat Yourself) in the development of
your
application views.
Heist has two primary template abstraction constructs: bind and apply.
-They are implemented as specialized XML tags.
+They are implemented as specialized tags.
### The `<bind ...>` tag
-The `bind` tag allows you to bind XML content to a single tag.
-Whenever the bound tag is used, the template engine will substitute
-the 'bind' tag's child nodes in its place. This allows you to
-essentially create your own higher-level markup language that Heist
-transforms into whatever XML-based markup language is native to your
-application.
+The `bind` tag allows you to bind content to a single tag. Whenever
+the bound tag is used, the template engine will substitute the 'bind'
+tag's child nodes in its place. This allows you to essentially create
+your own higher-level markup language that Heist transforms into whatever
+markup language is native to your application.
#### Attributes
@@ -65,9 +62,9 @@ make changes.
#### Attribute Substitution
Heist also provides attribute string substitution using the same mechanism as
-tag substitution. The syntax is different for attributes since the angle
-bracket tag syntax is not allowed. Within the value of an attribute, use the
-delimiter `$(...)` for variable substitution.
+tag substitution. The syntax is different for attributes since angle bracket
+tag syntax is not generally found there. Within the value of an attribute, use
+the delimiter `$(...)` for variable substitution.
~~~~~~~~~~~~~~~ {.html}
<bind tag="foo">dynamic_name</bind>
@@ -81,13 +78,13 @@ tag. The output looks like this:
<p name="dynamic_name">A paragraph</p>
~~~~~~~~~~~~~~~
-If there are non-text nodes in the bind tag's children, they are converted
-to text nodes and their concatenation will be substituted.
+If there are non-text nodes in the bind tag's children, the markup is removed,
+and just the concatenation of the text inside will be substituted.
### The `<apply ...>` tag
The `apply` tag loads one of your application templates and inserts it
-into the current template's XML tree. If the target template does not
+into the current template's node tree. If the target template does not
have any special tags, then the contents of the `apply` tag are
ignored.
@@ -174,7 +171,7 @@ template:
### The `<content>` tag
-Sometimes it is useful to pass information (usually in the form of XML
+Sometimes it is useful to pass information (usually in the form of HTML
data) into the template when it is applied so the template can insert
it in useful places. This allows you to build page templates that are
not just static blocks of code.
@@ -333,13 +330,35 @@ the `<ignore>` tag for this purpose. All `<ignore>` tags
and their
contents will be eliminated in a template's output.
+### XML Syntax
+
+By default, Heist templates have an extension of `.tpl`. When used this way,
+Heist understands and makes use of HTML 5 syntax. It is, however, also
+possible to name templates `.xtpl`, in which case Heist will process them as
+plain XML without any HTML-specific rules.
+
+The differences between these two modes are small, but can sometimes matter.
+Using Heist with HTML templates (with a `.tpl` extension) means Heist will
+accept markup that is not valid XML; for example, it understands special tags
+like `<br>`, `<textarea>`, `<script>`, and `<p>` that are empty, have optional
+end tags, or contain content in other languages. Heist also won't mangle your
+JavaScript and stylesheets with escape sequences, or do other things that may
+confuse web browsers, in its output.
+
+On the other hand, some applications may need to produce well-formed XML
+output and may not be producing HTML at all. In this case, templates should
+use Heist's XML mode by using the `.xtpl` extension on templates. XML mode
+disables Heist's understanding of the HTML language, and treats the template
+as plain XML.
+
+
## Heist Programming
-Heist lets you bind XML tags to Haskell code with a splice. A
-`Splice` takes the input node from the template and outputs a list of
-XML nodes that get "spliced" back into the template. This lets you
-call haskell functions from your templates, while ensuring that
-business logic does not creep into the presentation layer.
+Heist lets you bind tags to Haskell code with a splice. A `Splice` takes
+the input node from the template and outputs a list of nodes that get
+"spliced" back into the template. This lets you call haskell functions
+from your templates, while ensuring that business logic does not creep into
+the presentation layer.
Splices that you write must have the type `mySplice :: Splice m` where
m is the monad of your choice (usually Snap). `Splice m` is a type
@@ -347,7 +366,7 @@ synonym for `TemplateMonad m Template`. The `getParamNode`
function
is a TemplateMonad computation that lets you get the contents of the
splice node. You can then do any processing you want using
functionality provided by
-[hexpat](http://hackage.haskell.org/package/hexpat).
+[xmlhtml](http://hackage.haskell.org/package/xmlhtml).
#### Example
@@ -356,26 +375,25 @@ number.
~~~~~~~~~~~~~~~ {.haskell}
import Text.Templating.Heist
-import qualified Data.ByteString.Char8 as B
-import qualified Text.XML.Expat.Tree as X
+import qualified Data.Text as T
+import qualified Text.XmlHtml as X
factSplice :: Splice Snap
factSplice = do
input <- getParamNode
- let text = B.unpack $ textContent input
+ let text = T.unpack $ nodeText input
n = read text :: Int
- return [X.Text $ B.pack $ show $ product [1..n]]
+ return [X.TextNode $ T.pack $ show $ product [1..n]]
~~~~~~~~~~~~~~~
-You must tell Heist to bind the splice to an XML tag using the
-`bindSplice` function: `bindSplice "fact" factSplice templateState`.
-This returns a new `TemplateState` with factSplice bound to the
-`<fact>` tag. Now, in any of your templates the XML snippet
-`<fact>5</fact>` will render as `120`.
+You must tell Heist to bind the splice to a tag using the `bindSplice`
+function: `bindSplice "fact" factSplice templateState`. This returns a
+new `TemplateState` with factSplice bound to the `<fact>` tag. Now, in
+any of your templates the snippet `<fact>5</fact>` will render as `120`.
The contents of splices can also be used in attributes using the `$()` syntax
-mentioned above. As above, the first element of the returned list must be a
-text node. This works because a `<bind>` tag is really just a splice that
+mentioned above. As above, any markup is ignored, and just the text is
+included. This works because a `<bind>` tag is really just a splice that
returns a constant node list.
### Hooks
@@ -424,12 +442,18 @@ other hooks that have already been added.
Once you have built a `TemplateState`, you are ready to generate pages
with Heist. The two functions you will use most frequently are
`renderTemplate` and `callTemplate`. `renderTemplate` renders a
-template by name and returns it as a Maybe ByteString. `callTemplate`
-is similar but is designed for templates that require parameters to be
-bound by the caller. When you're calling the template from another
-template with the apply tag, this is easily accomplished by using
-`<bind>` within the body of the `<apply>`. But when you are "calling"
-the template from code, binding splices for each of the template's
+template by name and returns it as a `Maybe (Builder, MIMEType)`. The
+`Builder` is from the `blaze-builder` package, and can be converted into
+a `ByteString` using `blaze-builder`'s `toByteString` function. The
+`MIMEType` is also a `ByteString`, and contains the MIME content type of
+the result (either `text/html` or `text/xml`, with the same character
+encoding as the template).
+
+`callTemplate` is similar but is designed for templates that require
+parameters to be bound by the caller. When you're calling the template
+from another template with the apply tag, this is easily accomplished by
+using `<bind>` within the body of the `<apply>`. But when you are
+"calling" the template from code, binding splices for each of the template's
parameters is cumbersome. `callTemplate` does this for you.
[This website](http://github.com/snapframework/snap-website) is a good
diff --git a/templates/download.tpl b/templates/download.tpl
index 0d89771..8d213fc 100644
--- a/templates/download.tpl
+++ b/templates/download.tpl
@@ -72,8 +72,8 @@ $ cabal install snap</pre>
<dt>heist</dt>
- <dd>An xhtml-based templating engine, allowing Haskell functions
to be
- bound to XML tags. <br/><span class="linklist">
+ <dd>An HTML/XML-based templating engine, allowing Haskell
functions to be
+ bound to tags. <br/><span class="linklist">
[ <a href="/docs/latest/heist/index.html" >api docs</a> |
<a href="http://hackage.haskell.org/package/heist";
>hackage</a> |
diff --git a/templates/faq.md b/templates/faq.md
index 2bd549c..e71a119 100644
--- a/templates/faq.md
+++ b/templates/faq.md
@@ -91,12 +91,6 @@ $ cabal configure -p
$ cabal build
~~~~~~~
-### How do I install Heist on Windows?
-
-Heist needs a C XML library called expat. See [this article by Jacob
-Stanley](http://jystic.com/2010/10/07/installing-heist-and-hexpat-on-windows/)
-for more information.
-
### Why doesn't Heist display templates?
The most common problem we've seen is that you have ".tpl" included as part of
diff --git a/templates/index.tpl b/templates/index.tpl
index 69203e5..53ab737 100644
--- a/templates/index.tpl
+++ b/templates/index.tpl
@@ -88,7 +88,7 @@ $ mkdir foo; cd foo; snap init</pre>
the <a
href="http://software.schmorp.de/pkg/libev.html";>libev</a>
event loop library</li>
<li>A sensible and clean monad for web programming</li>
- <li>An XML-based templating system for generating HTML</li>
+ <li>An HTML-based templating system for generating
pages</li>
</ul>
</div><!--end inner-->
commit 9ff0e9f6ee7f3074becbe4a07a0302ba230c5d13
Author: James Sanders <[email protected]>
Date: Sun Jan 16 15:55:08 2011 -0500
fixed spelling error
diff --git a/templates/about.tpl b/templates/about.tpl
index 197b6db..d5556d8 100644
--- a/templates/about.tpl
+++ b/templates/about.tpl
@@ -96,7 +96,7 @@
Sanders</a></strong> is a self-taught software developer living
and working in the great American South. He works as the resident
Star Trek expert at <a href="http://thisismedium.com/";>Medium</a>.
- His interest include music, mathmatics and classic european cars.
+ His interest include music, mathematics and classic european cars.
</p>
<p>
<strong>Carl Howells</strong> is a veteran of web app
-----------------------------------------------------------------------
hooks/post-receive
--
snap-website
_______________________________________________
Snap mailing list
[email protected]
http://mailman-mail5.webfaction.com/listinfo/snap
