We’ve managed to implement a full set of CRUD operations on our Project type. Still, our app is definitely not perfect – for example, in the previous post we’ve implemented DELETE handler as Html Handler. That’s not exactly fine, since browsers generally use only GET and POST – other methods (such as DELETE) are used either by web services or by AJAX calls. We used it as AJAX call, and that’s why we can’t exactly use typical redirection, and instead we redirected the user by hardcoded link. This lead to races and projects which were just deleted were sometimes visible. In this post we’ll deal with this problem.

We’re going to remove the hardcoded link and instead redirect user to link returned from API call, after results are returned. To do this, we need to make several changes:

1. add a Handler for JSON DELETE requests
2. remove redirection from button
3. add redirection to AJAX handler
4. change request to accept application/json header

First one is critical for us, so let’s start with it. We’ll provide only DELETE method – this way we’ll have something to implement when discussing high-level testing.
Right now we want to provide only JSON responses. Since Yesod uses Aeson library under the hood for JSON handling, its types will also appear in the handler (Aeson uses Value type to denote JSON). New implementation of deleteProjectR looks like this:

deleteProjectR :: ProjectId -> Handler TypedContent
deleteProjectR projectId = selectRep $ do
    provideRep $ do
      _ <- runDB $ delete projectId
      renderUrl <- getUrlRender
      returnJson $ object ["target" .= (renderUrl ProjectsR)]

There are quite a few new elements in here! First one is the signature – Handler TypedContent. TypedContent means that Yesod will check headers and verify whether it can provide a representation required by the client (by default it’s not checked). For example, if client requests application/xml, but we can only provide application/json, a 406 (Not Acceptable) error will be returned. This data type check is done by selectRep function, basing on provideRep calls. There is a little trick here – actual delete is performed in provideRep call. That’s not perfect, as it has nothing to do with the representation, and we would prefer to execute the action always if we can provide the return type. For now it’s not a big deal since we have just one representation, but this can lead to problems (code duplication mostly) later on, when we’ll have many representations. Creating the JSON is done in a bit simplistic way (to make it totally clean we should define a data type, a ToJson instance etc.), but doing it in more sophisticated way seems like an overkill.

Anyway, we’ve done our job on the server, and everything still works – that’s because jQuery AJAX calls accept all possible responses (Accept: */* header). We want to change it, since we’ll be only able to handle JSON responses – thus our templates/project.julius will change to:

jQuery("#delete-project").on("click", function() {
  jQuery.ajax("@{ProjectR projectId}", {
    method: "DELETE",
    headers: { Accept: "application/json; charset=utf-8" }
  }).done(function(response) {
    window.location.replace(response.target);
  });
});

This will redirect you to proper page each time after deletion, thus there will be no race condition. Only thing left is to change the hyperlink to actual button:

<button href=@{ProjectsR} .btn .btn-danger #delete-project>Delete

in project.hamlet. And it’s done!

We’ve implemented our first JSON API. It might not be very impressive, but works well – at least better than the previous solution, which had a built-in race condition.
That’s it for today! Since we’ve already implemented quite a lot of stuff, we would like to be sure that it keeps working after each change. This is what the next post will focus on – testing environment preparation and testing the application. This will be just a short instruction of how to manually prepare a single environment for testing – automatically generating and deploying such environments is a much harder topic and we won’t be focusing on it now. Perhaps later, who knows? Maybe we’ll even have a series on environment automation!

Stay tuned!

Sorry for the delay of this page – last week was quite a hard time and this post took much longer than I thought. To make up for it, this week will get two posts – first today and second one tomorrow.

As you probably remember, last time we managed to set up database connection and fetch projects from it. Still, we didn’t have an option to insert data – all our data was preset from a hardcoded file. Well, good news – today we’re going to remove this obstacle.

Right now we’re going to do: add a new route – project/[id]/edit for project data edition – we’ll create a formular and a handling routine.

First of all, let’s start with the route. That’s pretty straightforward and you probably know the right syntax:

/project/#Int/edit ProjectEditR GET POST

in config/routes. A new thing here is that we handle POST as well as GET (no DELETE yet though!), but it doesn’t make a big difference. We just have to provide one more function – postProjectEditR in our handler. So let’s do it now – create a Handler/ProjectEdit.hs and include it in Application.hs and .cabal file.

Now we’re going to write the handler – that’s the core of our today’s concept, so let’s start with a little introduction.

There are three types of forms in Yesod – applicative forms, monadic forms and input forms. Applicative ones are the most common, and ones that we’re going to deal with today. Monadic ones are used in case of non-standard view, and input ones are not generated, but only received (e.g. because of dynamic fields). Applicative forms are generally created by composing preconfigured fields. Let’s take a look on a more concrete example – our Project with four fields – identifier, name, shortName and deadline. While changing identifier might seem a bit weird (it’s in URL after all!), we’re not going to care about it – it’s the forms that are interesting today after all, not the semantics of project addition, right?

We’ll start with creating the form. Type signature will be a little weird – Int -> Maybe Project -> AForm Handler Project. That’s a little unintuitive, but our route allows for accessing UIDs without projects, and if the project already exists, we want to fill in rest of the fields.

We’re gonna start with the easy part – the Hamlet template for the form. W’ve already created quite a bunch of Hamlet templates, so it shouldn’t be a big deal. Here’s the code for templates/project-edition.hamlet (by the way, if you’re wondering how to change templates directory in Yesod – you can’t, it’s hardcoded):

<div .jumbotron>

<h2> Project edition

<form method=post action=@{ProjectEditR projectId} enctype=#{enctype}>
    ^{formWidget}

pretty simple, eh? We just add a master block, a heading and form declaration (with encoding and target route – be careful with the indentation – it’s important that formWidget is under form) and that’s all – well, maybe except the formWidget, which we still have to create. We should do it now, but, unfortunately, it’s not that simple. Yesod uses runFormPost function to both generate a form and evaluate input data against it. It has quite an impressive type signature, but the important thing is the result – it’s m ((FormResult a, xml), Enctype). FormResult a is the parsed result, information that no data was provided or a list of error messages, while xml is the formWidget we’re looking for. Enctype is not really interesting – it is the encoding required by form (UrlEncoded or Multipart). It’s argument is a function, that tranforms Markup(roughly Html) to MForm (a formular).

Before diving into code, let’s recap what we’re going to do:

1. create a POST/GET handler (one for both methods)
2. fetch project from database, if it already exists
3. generate form with prefilled fields (in case of existing project)
4. after submission, save the form to database

Quite a lot of work for a single post, right? We’d better get started straight ahead!
Let’s start with the POST handler:

postProjectEditR :: Int -> Handler Html
postProjectEditR projectId =  do
  project <- runDB $ getBy $ UID projectId renderForm $ (\(Entity _ proj) -> proj) `fmap` project

That’s fairly straightforward and similar to what we’ve done in Handler/Project.hs. Perhaps the only interesting part is using the fact that Maybe is a Functor, so we can use fmap on it (it’ll be executed on Just value, Nothing will be ignored). Well, since the first part is already done, let’s go to the rendering part!

renderForm :: Maybe Project -> Handler Html
renderForm projectId projectEntry = do
  ((result, formWidget), enctype) <- runFormPost (projectForm projectId projectEntry) case result of FormSuccess project -> redirect $ ProjectR (projectIdentifier project)
    _ -> defaultLayout $ do
      app <- getYesod
      setTitle $ (toHtml $ (appName app)) ++ ": editing projects"
      $(widgetFile "project-edition")
      $(widgetFile "back-to-projects")

Now, this piece of code is much more interesting – first of all, it uses the actual form, generated by projectForm projectId projectEntry. We didn’t write this function yet, so it’s more of a stub for the future. Next interesting part is handling of successfully created Project – here we simply redirect to view page. This means that we don’t actually insert anything to database – we’re gonna deal with the inserting later on. And the rest is displaying the form (we’ve created the Hamlet template in the beginning).

Now, before we get to the actual form, there is one more level of indirection that I’d like to introduce:

projectForm :: Int -> Maybe Project -> Html -> MForm Handler (FormResult Project, Widget)
projectForm projectId project = renderBootstrap3 BootstrapBasicForm $ projectAForm projectId project

I want to introduce it, since it’s quite independent from the form creation, but is the point at which the layout is decided (the form’s form). There are a few interesting things here – first of all, it returns a MForm (monadic form version), and creates it from applicative version of form (AForm). Next, it performs the form conversion to Bootstrap mechanisms – namely BootstrapBasicForm. There are three types of Bootstrap form layouts, and this one is simplest – label above input field. Looks good enough for our purposes, so let’s finally get to creating forms!

Here’s the code:

projectAForm :: Int -> Maybe Project -> AForm Handler Project
projectAForm projectId project = Project
    <$> areq hiddenField identifierConfig (pure projectId)
    <*> areq textField nameConfig (projectName <$> project)
    <*> areq textField shortNameConfig (projectShortName <$> project)
    <*> areq utcDayField timeFieldConfig (projectDeadline <$> project)
    <* bootstrapSubmit ("Modify" :: BootstrapSubmit Text)
    where
      identifierConfig = bfs ("" :: Text)
      nameConfig = withPlaceholder "Project name" $ bfs ("Project name" :: Text)
      shortNameConfig = withPlaceholder "Short project name" $ bfs ("Short project name" :: Text)
      timeFieldConfig = bfs ("Project deadline" :: Text)

Lots of code, eh? But it’s mostly simple, so it shouldn’t be a big deal. First we declare that we’re gonna create a Project, and then list it’s fields. In our case all the fields are required (areq – optional are added by using aopt). Fields are added by using <*> operator. First areq argument is type of field (e.g., textField), second – field configuration (in our case labels, but we can also set tooltips or ids) and third – default value. We take most default values out of database project, except identifier – we know it for sure, so it’s taken from URL (as an argument). bfs call in all settings is used to underline the fact that we use Bootstrap styles, and it’s argument will be used as a label for field. There is one little quirk here – currently Bootstrap forms in Yesod don’t handle hidden fields very well, and leave some space for it (namely, space for the label). This might be fixed when a GitHub issue is resolved, but it’s quite old already, and it doesn’t work yet. A possible workaround is to add this field to form after its creation, but it’s not a nice solution, and we’re just gonna live with the current state for now.

We’re almost done – there is just one thing left to display the form. Namely – utcDayField does not exist in Yesod. But fret not! Yesod has a built-in Day field, which is used for dates. We just need to transform it so that using the same field will yield a different data type as output. Luckily, Yesod provides a function to transform one field to another, and it has (quite unintuitive) name checkMMap. Our defintion of utcDayField looks like this:

utcDayField = checkMMap (return . Right . toUTCTime :: (Day -> Handler (Either Text UTCTime))) utctDay dayField
  where
  toUTCTime x = UTCTime x (secondsToDiffTime 0)

Looks a bit magical, I agree. Basically we need to provide two functions: one to transform Day to UTCTime (to inject data to our code), and second, to transform UTCTime to Day (to display default value properly). This is done be toUTCTime (defined) and utctDay (built-in). Rest of the definition (return . Right . and type signature) serves mostly to feed the type system.

And we’re done! The form is generated and user can display it easily. A nice bonus is that Yesod-generated forms automatically provide tokens that protect us from CSRF attacks.

Remember to add also handler for GET requests (getProjectEditR = postProjectEditR is a sufficient implementation) and required imports: Yesod.Form.Bootstrap3 and Data.Time.Clock).

That’s the end of today’s post. We did a lot of things – accessed database to fetch a – possibly existing – project, generated a form and filled it with default values. We didn’t manage to insert the data to database yet – we’re going to do this in the next post, tomorrow.

Stay tuned!

Databases are important. We need to keep all kinds of data in our applications – users, workspaces, messages, even things like selected UI theme. Yesod’s typical answer to this problem is Persistent. Persistent is a Haskell library for accessing databases – ranging from SQLite to MongoDB. It provides a type-safe access from Yesod to database and manages database schema and its changes (that’s actually done in runtime, but connection won’t be established without proper schema). Of course, not all migrations are possible to detect automatically – for example renaming a field will not be executed automatically. You can find more details about migrations in the Yesod Book, chapter about Persistent.

Luckily, our case is pretty straightforward – we want to store records for projects. For now we need only current state of the projects, so we’re going to use the usual facilities offered by Persistent. This involves some Template Haskell, but don’t worry, it’s quite straightforward. First we need to define our data type – but in a little special, Persistent-dedicated way. We’re gonna leave our pair-driven implementation and move to more complex data type. Our Project type will consist of a numeric identifier, textual name, short version of name and a deadline. I was quite tempted to leave out the deadline field since it introduces a bit of trouble, but after all – what’s a project without a deadline?

So, let’s create a Domain/Project.hs file with the following content:

module Domain.Project (Project(Project, projectIdentifier, projectName, projectShortName, projectDeadline)) where

import Import

share [mkPersist sqlSettings, mkMigrate "migrateProjects"] [persistLowerCase|
Project
  identifier Int
  name Text
  shortName Text
  deadline UTCTime
  deriving Show
|]

that’s quite dense, so probably requires some explaination. The part between | symbols is the actual data type definition. It is the input to the magic performed by Template Haskell, which results in generating field “accessors” exported in the first line: projectIdentifier, projectName, projectShortName, projectDeadline. You might guess that these are names of fields appended to name of data type and camelCased – there actually is a valid reason to do that – it is really helpful in avoiding name clashes (imagine field id). Actually, there is also a reason why the first field is called identifier and not simply id – Persistent internally creates an index field for each type, thus resulting in a clash. The type of this automatically generated id varies between backend databases – in most SQL-based ones it’s Int, but in MongoDB it’s String. Of course, both are nicely hidden under a type alias [[DatatypeName]]Id.

persistLowerCase is just a way of telling Persistent how to map field names to DB names, so let’s not focus on it. share is more interesting – it’s a helper function that takes a list of function an a quasiquotation as arguments (quasiquotes are these funny expressions strucured as [sth|sth else] – you can read more about them here) and passes the second one as argument for each of elements in the array. In our case these are mkPersist responsible for DB access and mkMigrate responsible for generating new DB schema.

And the last part that might be a little tricky – exports. module Domain.Project (Project(Project, projectIdentifier, projectName, projectShortName, projectDeadline)) – that’s just a way constructors and fields are exported in Haskell, TypeName(TypeConstructor, OtherTypeConstructor, field1, field2...).

Great, we’ve already done the tough job, now we have to clean up. First let’s change Database/Projects.hs. We’ve already prepared our application to interact with a database, but the interaction itself will be the subject of the next post. For now let’s just make it work. Here’s the new content:

module Database.Projects (projects) where
import Import

import Data.Time.Clock
import Domain.Project

time:: Integer -> Integer -> UTCTime
time a b = UTCTime (fromGregorian a 1 1) (secondsToDiffTime b)

projects::[Project]
projects = [Project 1 "Project 1" "P1" $ time 0 0,
  Project 3 "Substantial" "P2"  $ time 1 0,
  Project 5 "What the hell" "WTH"  $ time 100 0,
  Project 10 "The last project" "TLP"  $ time 10 10]

Only tricky thing here is the UTCTime creation. for some reason secondsToDiffTime is not imported by default, thus we need to explicitly add import Data.Time.Clock. This time function is also quite weird, but I guess we can live with that for now – after all we’ll get rid of such syntax in this file in another post (and if we won’t, we’ll refactor it soon).

Minor fixes are also needed in Handler/Project.hs (mostly substituting fst x with projectIdentifier x) and templates/projects.hamlet (same story + pattern matching in $forall). Handler/Projects.hs might also need a little change, namely importing Domain/Project.hs into the scope.

I’ve also removed copyright from the footer. We don’t need it now and it looked awful.

Quite some changes today! Remember that if something doesn’t work for you you can always check out the exact code that I’ve use during writing this post – it’s available at GitHub.

Next episode, in which we’re going to really attach a database to the application comes soon.

Stay tuned!

This post will introduce some magic that you’ll use on a daily basis when using Yesod. This magic is mostly related to connection with the outside world – while Handler and Widget have IO in their type signatures, there are recommended ways of dealing with it – and this recommended way includes a foundation datatype.

Foundation datatype is a type that is accessible in all your Widget‘s and Handler‘s. In fact, it is even in the signature of your application – in Yesod App, App is your foundation datatype (that’s the name in the default scaffolding, you can change it if you wish to). You can keep anything there – default scaffolding puts there some server settings, connection pools, logger etc., but you can put virtually anything there – it’s just a typical data type.

This time we’re going to use it in a very simple way – to inject application name into the widgets and use it in the title – but on future posts we’ll be using the foundation value in much more sophisticated scenarios, such as database access or configuration. First let’s add the name to our data type – since this is just a tutorial, we’ll add it as a top-level field. So, in Foundation.hs change the definition of data App to

data App = App
    { appSettings    :: AppSettings
    , appStatic      :: Static -- ^ Settings for static file serving.
    , appConnPool    :: ConnectionPool -- ^ Database connection pool.
    , appHttpManager :: Manager
    , appLogger      :: Logger
    , appName        :: Text
    }

Next step, initialization. In Application.hs in code of makeFoundation function add appName <- return "Project M" line. That’s it, you already have your foundation data initialized. A little magic here is performed by the following line: let mkFoundation appConnPool = App {..} – the {..} syntax binds together names that exist in the scope and create a single data record. By the way, you can also use it the other way around: App {..} <- getYesod will bring all the fields to the current scope. I believe it generally clutters the scope and should be avoided. Still, sometimes it can come in handy. getYesod is a wrapped object of the foundation type, which is usually accessed by the syntax mentioned above (app <- getYesod) – yet, it’s a typical Yesod value, so there is no real reason (except maybe convenience) to stick to this method.

In the last step we’re going to change Handler/Project.hs and it’s rendering function. Let’s change the first two lines of renderPage function to:

app <- getYesod
setTitle $ (toHtml $ (appName app)) ++ ": " ++ projectTitle

And that’s it, title on your development server should already change. I’ll change the display to format appName: projectName(projectId), by changing the where clause from projectTitle = (toHtml projectId) ++ (toHtml projectName) to projectTitle = (toHtml projectName) ++ "(" ++ (toHtml projectId) ++ ")".

That’s it for today – soon we’re going to explore the way of using databases with Yesod, but first – in the next post – we’ll have to deal with our data type and make it more useful.

Stay tuned!