Cabal file

Whether directly using cabal, or indirectly using yesod devel, building your code will always go through the cabal file. If you open the file, you’ll see that there are both library and executable blocks. If the library-only flag is turned on, then the executable block is not built. This is how yesod devel calls your app. Otherwise, the executable is built.

The library-only flag should only be used by yesod devel; you should never be explicitly passing it into cabal. There is an additional flag, dev, that allows cabal to build an executable, but turns on some of the same features as the library-only flag, i.e., no optimizations and reload versions of the Shakespearean template functions.

In general, you will build as follows:

• When developing, use yesod devel exclusively.

• When building a production build, perform cabal clean && cabal configure && cabal build. This will produce an optimized executable in your dist folder.

You might be surprised to see the NoImplicitPrelude extension. We turn this on since the site includes its own module, Import, with a few changes to the Prelude that make working with Yesod a little more convenient.

The last thing to note is the exported-modules list. If you add any modules to your application, you must update this list to get yesod devel to work correctly. Unfortunately, neither Cabal nor GHC will give you a warning if you forgot to make this update, and instead you’ll get a very scary-looking error message from yesod devel.

Routes and entities

Multiple times in this book, you’ve seen a comment like "We’re declaring our routes/entities with quasiquotes for convenience. In a production site, you should use an external file." The scaffolding uses such an external file.

Routes are defined in config/routes, and entities in config/models. They have the exact same syntax as the quasiquoting you’ve seen throughout the book, and yesod devel knows to automatically recompile the appropriate modules when these files change.

The models files is referenced by Model.hs. You are free to declare whatever you like in this file, but here are some guidelines:

• Any data types used in entities must be imported/declared in Model.hs, above the persistFile call.

• Helper utilities should either be declared in Import.hs or, if very model-centric, in a file within the Model folder and imported into Import.hs.

Foundation and Application modules

The mkYesod function which we have used throughout the book declares a few things:

• Route type

• Route render function

• Dispatch function

The dispatch function refers to all of the handler functions, and therefore all of those must either be defined in the same file as the dispatch function, or be imported into the module containing the dispatch function.

Meanwhile, the handler functions will almost certainly refer to the route type. Therefore, they must be either in the same file where the route type is defined, or must import that file. If you follow the logic here, your entire application must essentially live in a single file!

Clearly this isn’t what we want. So instead of using mkYesod, the scaffolding site uses a decomposed version of the function. Foundation calls mkYesodData, which declares the route type and render function. Since it does not declare the dispatch function, the handler functions need not be in scope. Import.hs imports Foundation.hs, and all the handler modules import Import.hs.

In Application.hs, we call mkYesodDispatch, which creates our dispatch function. For this to work, all handler functions must be in scope, so be sure to add an import statement for any new handler modules you create.

Other than that, Application.hs is pretty simple. It provides two primary functions: getApplicationDev is used by yesod devel to launch your app, and makeApplication is used by the executable to launch.

Foundation.hs is much more exciting. It:

• Declares your foundation datatype

• Declares a number of instances, such as Yesod, YesodAuth, and YesodPersist

• Imports the messages files. If you look for the line starting with mkMessage, you will see that it specifies the folder containing the messages (messages) and the default language (en, for English).

This is the right file for adding extra instances for your foundation, such as YesodAuthEmail or YesodBreadcrumbs.

We’ll be referring back to this file later, as we discussed some of the special implementations of Yesod typeclass methods.

Import

The Import module was born out of a few commonly recurring patterns.

• I want to define some helper functions (maybe the <> = mappend operator) to be used by all handlers.

• I’m always adding the same five import statements (Data.Text, Control.Applicative, etc) to every handler module.

• I want to make sure I never use some evil function (head, readFile, …) from Prelude.

The solution is to turn on the NoImplicitPrelude language extension, re-export the parts of Prelude we want, add in all the other stuff we want, define our own functions as well, and then import this file in all handlers.

Handler modules

Handler modules should go inside the Handler folder. The site template includes one module: Handler/Home.hs. How you split up your handler functions into individual modules is your decision, but a good rule of thumb is:

• Different methods for the same route should go in the same file, e.g. getBlogR and postBlogR.

• Related routes can also usually go in the same file, e.g., getPeopleR and getPersonR.

Of course, it’s entirely up to you. When you add a new handler file, make sure you do the following:

• Add it to version control (you are using version control, right?).

• Add it to the cabal file.

• Add it to the Application.hs file.

• Put a module statement at the top, and an import Import line below it.

You can use the yesod add-handler command to automate the last three steps.