> cabal update
> cabal install yesod cabal-dev
That is all. It should take some time to
do this as cabal will download all
package and then compile them.
## Initialization
Open a terminal and type:
> yesod init
Enter your name, name the project `yosog` and the name of the Foundation as `Yosog`, then choose `sqlite`.
Perfect. Now you can start the development cycle:
> cd yosog
> cabal-dev install && yesod --dev devel
This will compile the entire project. Be patient it could take some time.
Once finished a server is launched and you could visit it by clicking this link:
[`http://localhost:3000`](http://localhost:3000)
Congratulation! Yesod works.
> Note: if something is messed up use the following command line:
>
> \rm -rf dist/* ; cabal-dev install && yesod --dev devel
>
Until the end of the tutorial, use another terminal and let this one open in a corner to see what occurs.
## Configure git
This step is not mandatory for a tutorial, but I wanted to jump directly in good practice. There are many different choice of CVS, but for this tutorial I'll use `git`.
Copy this `.gitignore` file into the `yosog` folder.
cabal-dev
dist
.static-cache
static/tmp
*.sqlite3
Then initialize your git repository:
> git init .
> git add .
> git commit -a -m "Initial yesod commit"
Now we are almost ready to start.
## A last point
Until here it was just an installation, an initialization and a configuration.
We have a directory containing a bunch of files and
we have a local web server that listen the port 3000.
If we modify a file inside this directory, yesod should try
to recompile as fast as possible the site.
This way, you should see the modification you do.
Instead of explaining the role of every file,
let's get straight to the point.
Inside the `yosog` the important files/directories for this tutorial are:
1. `config/routes`
2. `Handler/`
3. `templates/`
4. `config/models`
Obviously:
- `config/routes` is where you'll configure the map URL → Code.
- `Handler/` contains the files that will contain the code called when a URL is accessed.
- `templates/` contains HTML, JS and CSS templates.
- `config/models` is where you'll configure the persistent objects (database tables).
Also note until here we don't even typed any line of Haskell.
It is now time to start the interesting stuff.
## Protected echo
To verify the quality of the security of the yesod framework, let's make a minimal echo application.
Our goal:
Make a server that when accessed `/echo/`_[some text]_ should return a web page containing "some text" inside an `h1` bloc.
For example, accessing [`http://localhost:3000/echo/some%20text`](http://localhost:3000/echo/some%20text), should display "some text" in an %html web page.
First, we must declare URL of the form /echo/... are meaningful.
Let's take a look at the file `config/routes`:
/static StaticR Static getStatic
/auth AuthR Auth getAuth
/favicon.ico FaviconR GET
/robots.txt RobotsR GET
/ RootR GET
We want to add a route of the form `/echo/[anything]` somehow and do some action with this.
We add the following:
/echo/#String EchoR GETThis line contains three elements: the
Application.hs:31:1: Not in scope: `getEchoR'Why? Simply because we didn't written the code for the handler `EchoR`. Now, let's do this. Edit the file `Handler/Root.hs` and append this:
getEchoR :: String -> Handler RepHtml
getEchoR theText = do
defaultLayout $ do
[whamlet|#{theText}|]
Don't worry if you find all of this a bit cryptic.
This is normal when learning a new framework.
In short it just declare a function named getEchoR with one argument (`theText`) of type String.
When this function is called, it return a "Handler RepHtml" whatever it is.
But mainly this will encapsulate our expected result inside an HTML text.
After saving the file, you should see yesod recompile the application.
When the compilation is finished you'll see the message: `Starting devel application`.
Now you can visit: [`http://localhost:3000/echo/Yesod%20rocks!`](http://localhost:3000/echo/Yesod%20rocks!)
TADA! It works.
### Secure?
Let's try to attack our website by entering a text with special characters:
[`http://localhost:3000/echo/I'm " %>
All should work better than expected.
The special characters are protected for us.
If you have a malicious user, he could not hide some bad script inside his login name for example.
This is a direct consequence of _type safety_.
The URL string is put inside a URL type.
Then the interesting part in the URL is put inside a String type. To pass from URL type to String type some transformation are made. For example, replace all "`%20`" by space characters.
Then to show the String inside an HTML document, the string is put inside an HTML type. Some transformations occurs like replace "<" by "`<`".
Thanks to yesod, most of tedious string transformation job is done for us.
"http://localhost:3000/echo/some%20text" :: URL
↓
"some text" :: String
↓
"some text <a>" :: HTML
That was the first very minimal example, and we already
verified Yesod protect us from many common errors.
Then not only Yesod is fast, it is also relatively secure.
## Cleaning up
This first example was nice, but for simplicity reason we didn't used best practices.
First we will separate the handler code into different files.
After that we will use `Data.Text` instead of `String`.
Finally we'll use a template file to better separate our view.
### Separate handlers
In a first time create a new file `Handler/Echo.hs` containing:
module Handler.Echo where
import Import
getEchoR :: String -> Handler RepHtml
getEchoR theText = do
defaultLayout $ do
[whamlet|#{theText}|]
Do not forget to remove the getEchoR function inside the `Handler/Root.hs` file.
We must declare the file inside the cabal configuration file `yosog.cabal`. Just after `Handler.Root` add:
Handler.Echo
We must also declare the new Handler module inside `Application.hs`.
Just after the "`import Handler.Root`", add:
import Handler.Echo
### Use `Data.Text` instead of `String`
Now our handler is separated in another file.
But we used `String` but it is a good practice to use `Data.Text` instead.
To declare we will use `Data.Text` we modify the file `Foundation.hs`.
Add an import directive just after the last one:
import Data.Text
And also we must modify `config/routes` and our handler accordingly. Replace `#String` by `#Text` in `config/routes`:
/echo/#Text EchoR GETAnd do the same in `Handler/Echo.hs`:
module Handler.Echo where
import Import
getEchoR :: Text -> Handler RepHtml
getEchoR theText = do
defaultLayout $ do
[whamlet|#{theText}|]
### Use a new template file
The last thing to change in order to do things like in
a real project is to use another template file.
Just create a new file `template/echo.hamlet` containing:
#{theText}
and modify the handler `Handler/Echo.hs`:
getEchoR :: Text -> Handler RepHtml
getEchoR theText = do
defaultLayout $ do
$(widgetFile "echo")
At this point our code is clean.
Handler are grouped, we use `Data.Text` and our views are in templates.
It is now time to make a slightly more complex example.
## Protected input
Let's make another minimal application.
You should see a form containing a Text Field and a validation button.
When you click, the next page present you the content you entered in the field.
First, add a new route:
/new NewR GET POST
This time the path /new will accept GET and POST requests. Add the corresponding new Handler file:
module Handler.New where
import Import
getNewR :: Handler RepHtml
getNewR = do
defaultLayout $ do
$(widgetFile "new")
postNewR :: Handler RepHtml
postNewR = do
postedText <- runInputPost $ ireq textField "content"
defaultLayout $ do
$(widgetFile "posted")
Don't forget to declare it inside `yosog.cabal` and `Application.hs`.
The only new thing here is the line that get the POST parameter named "content".
If you want to know more detail about it and form in general you can take look at [the yesod book](http://www.yesodweb.com/book/forms).
Create the two corresponding templates:
Enter your text
You've just posted
#{postedText}
And that is all.
---
<%= startTodo %>