Analyzing domain of the problem - GORM classes

[From the series - creating software books reviews grails web application]

In the previous posts I have created basic empty grails application. All the steps done to get up to this point are linked in this post. When the basic layout of the application is prepared it is obviously time to analyze domain objects. Domain objects in the grails are called GORM (grail's object relational mapping). Database schema is automatically generated from GORM objects and they probably represent the most powerful feature of the grails framework.

As software books reviews site is about providing reviews for the books the main features that need to be covered by application are following.

Visitor comes to the web site. From here he can navigate through existing books and read reviews and summaries. Review can be written on the site or link to the web site with the review can be provided. Summary is expressed as number (from 1 to 5) of some book aspects. Visitor can register and then he is able to post reviews and summaries for the books. Additionally there are some tasks for the administrator like: moderating books, posting new books...

If I try to express this short description as a list of user stories we get following:

As visitor I want to register.

As registered user I want to login.

As visitor I want to see books and reviews/summaries of the books.

As registered user I want to post book review.

As registered user I want to post summary.

As administrator I want to moderate books (this is probably epic).

Although user stories should be implemented one by one it is not a mistake to make an overview of the whole system. So described system can be pictured like this:

On the picture above I have depicted domain object classes that I will create for the sbr project. For those that already have some knowledge about GORM the class BookAuthor may be surprising. In the GORM it is possible to model "many-to-many" relationship directly. I don't like this way and most of the time I create additional domain class that is representing connection object. Of course you can use what ever approach but for me this is much more flexible because I can easily navigate in both directions in the relationship and even having custom logical methods in the connecting class - BookAuthor in this case.

Let me write few words about this domain objects model. As you can see the central place in the model plays the Book class. It is not surprise because sbr is more or less about books. For each book we want to have different details except reviews and summaries. Those details are Author and Publisher.

The relationship between Book and Author is many-to-many. This means that each book can have more than one author and each author can write more than one book. Thus domain object BookAuthor is created.

The relationship between Book and Publisher is many-to-one. This means that each book can have only one publisher. Or from the other point of the relationship, each publisher can publish many books.

Next interesting part of the diagram is BookReview and BookSummary and User. The logic here is that book review and book summary must be provided for an existing book by an existing user. There is no limit on the domain level how many reviews/summaries user can provide for the same book. This limit is set as a business logic. Registered user can post one review/summary per book while moderator can post many reviews per book and one summary per book.

Knowing all these we are ready to start with implementation. If you do it in hurry you can start with the book class. But as we already know that we will need possibility to register and we will need User class it is good moment to have a look into grails plugins.

Before you start implementing anything in the Grails it is good idea to see what is available from the Grails plugins. Very often functionality you need is already implemented as a plugin and you can simply reuse it. The same story is for registration and the User class. For software books reviews site I am using Spring security plugin (former Acegi security plugin). So you need to install this plugin. How to do that you can find in the plugins section of the Grails web site. After installing it create two roles: admin and user. This plugin offers out of the box login, logout, register pages and lot of useful methods that can be used in the application.

So in my next post I will install Spring (Acegi) security plugin, initialize default roles on the startup (if they are not initialized already) and then we will include register/login links on the home page and implement the first two user stories: As visitor I want to register and As registered user I want to login. So stay tuned.

P.S. Don't forget to write some review or post summary on the software books reviews.

Integrating blueprint into Grails application

[From the series - creating software books reviews grails web application]

In the previous post we have created home and admin page. Now it is time to create layout of the application. If you visit software books reviews site you can see that layout of the page is header and footer and three columns. If you are not a CSS expert creating such layout can be probably complex so it is good idea to use help of some CSS framework. My CSS framework is blueprint.

Blueprint is the grid based framework with the fixed width. Screen is divided into 24 columns and you can specify "boxes" and number of columns they should span through. The most important thing to remember is that sum of the box widths may not be bigger than 24. It can be smaller but not bigger.

The short example of the web page with the blueprint can look like this:

<div class="container">
   <div id="one" class="span-24 last">
       <!-- some content -->
   </div>
   <hr/>
   <div id="two" class="span-4 colborder">
       <!-- some content -->
   </div>
   <div id="three" class="span-14 colborder">
       <!-- some content -->
   </div>
   <div class="span-4 last">
   </div>
</div>

In this short code example the most important features of the blueprint framework are already visible.

The first div with class container is mandatory and blueprint will work inside this div.

<div id="one" class="span-24 last"> defines box that should spread through all 24 columns. This means that content will take the whole row of the screen. "last" class is used to specified that it is last box in the given row. This class has more sense when the sum of box widths is less than 24 but you want to put next box into the new row.

<hr> is blueprint tag that just makes more space between two rows.

Next three <divs> are actually more interesting. Here you are defining that row should be divided into three columns. First column of the width 4, next column of the width 14, and last column of the width 4. What you can notice immediately is that sum of these numbers is 22.

The reason is that class colborder separates two columns and actually takes the space of the whole column.

Now when we have basic knowledge about blueprint it is time to integrate it into our sbr application. The first step is to download the blueprint framework from their site. When you extract the downloaded zip file, copy the three css files from the blueprint folder. The file to copy are: ie.css, screen.css, and print.css.

You should copy them into web-app/css folder of the sbr application.

Now it is time to define layout of our application. As already mentioned we want that all pages are same and have header/footer and three columns: left, middle and right column. If you have read Starting with front-end in Grails application post then it should be clear that the right place where to specify this is the main.gsp template. This template specifies how all pages that are based on this template will look like. First of all we need to reference css files we have copied to the css folder. To do this change to grails-app/views/layouts/main.gsp to look like this:

<html>
   <head>
       <title><g:layoutTitle default="Grails" /></title>
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'main.css')}" />
       <g:layoutHead />
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'screen.css')}" type="text/css" media="screen, projection" />
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'print.css')}" type="text/css" media="print" />
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'ie.css')}" type="text/css" media="screen, projection" />
       <g:javascript library="application" />               
   </head>
   <body>
       <g:layoutBody />       
   </body>   
</html>

The three lines to notice are:

<link rel="stylesheet" href="${createLinkTo(dir:'css',file:'screen.css')}" type="text/css" media="screen, projection" />
<link rel="stylesheet" href="${createLinkTo(dir:'css',file:'print.css')}" type="text/css" media="print" />
<link rel="stylesheet" href="${createLinkTo(dir:'css',file:'ie.css')}" type="text/css" media="screen, projection" />

They are added as specified by the blueprint framework. The only difference is that I have used createLinkTo grails construct.

Now when we are referencing necessary css files we can specify layout of the template.

<html>
   <head>
       <title><g:layoutTitle default="Grails" /></title>
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'main.css')}" />
       <g:layoutHead />
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'screen.css')}" type="text/css" media="screen, projection" />
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'print.css')}" type="text/css" media="print" />
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'ie.css')}" type="text/css" media="screen, projection" />
       <g:javascript library="application" />
   </head>
   <body>
       <div class="container">
           <div id="header" class="span-24 last">
               header
           </div>
           <hr/>
           <div id="left-sidebar" class="span-4 colborder">
               left sidebar
           </div>
           <div id="content" class="span-14 colborder">
               <g:layoutBody />
           </div>
           <div id="right-sidebar" class="span-4 last">
               right sidebar
           </div>
           <hr/>
           <div id="footer" class="span-24 last">
               footer
           </div>
       </div>
   </body>
</html>

As you can see that is quiet easy and understandable. And what is good it is all what we need to the to get required layout. If you start the application now you will see that home page of the sbr application has correct layout. Of course we still need to populate all parts with the real content but that will be part of the next posts.

I know that usually I am announcing what will be topic of the next post but this time I am not sure. But for sure good reading is introduction into grails templates and tag libs mechanism that I have described in this and this post.

P.S. Don't forget to write some review or post summary on the software books reviews.

Creating home and admin page

[From the series - creating software books reviews grails web application]

In the previous post I have explained some basic aspects of grails front-end. Having this knowledge it is a time to create home page of sbr application. For the list of steps how I got up to this point you may want to have a look at this post pointing to all posts related to sbr series.

If you start sbr application (grails run-app) default home page generated by grails is displayed. This is not very useful page as a home page but will be very useful as admin page. It can be very useful as a admin page because it displays all controllers in your application. For each controller you can generate default list/show/create/edit pages.

So let create home page. To create home page I usually create HomeController. So the first step is to generate home controller. To create home controller type the following command:

grails create-controller Home

This command will generate HomeController.groovy file in the grails-app/controllers folder and home folder in the grails-app/views folder. In this folder we should put our new home page.

So to create home page in the home folder create file home.gsp that should look like this one:

<html>
   <head>
       <title>SBR</title>
       <meta name="layout" content="main" />
   </head>
   <body>
       Welcome to the SBR
   </body>
</html>

We want to display this page when ever the HomeController is accessed. This is very easy to achieve. Update the code of the HomeController to look like this:

class HomeController {
   def index = {
       render (view:'home')
   }
}

index closure is default closure of the controller and is executed when controller is accessed without specifying action to be executed. So if you type in your browser http://localhost:8080/sbr/home, index action will be executed. And this action is telling that the view 'home' should be displayed. As you are in the HomeController it will look for the file home.gsp in the grails-app/views/home folder. But if you want in the render closure you can specify the full path to the page to be displayed relative to the views folder. So render (view:'home/home') would be valid too.

Now it is time to create admin page. For admin page we will need AdminController. To create AdminController execute following command:

grails create-controller admin

Same as for the HomeController this command will create file AdminController.groovy and folder admin. To create admin page in the admin folder create admin.gsp file. Copy the content of the web-app/index.gsp file into the admin.gsp file. At the end admin.gsp should look like this:

<html>
   <head>
       <title>SBR admin</title>
       <meta name="layout" content="main" />
   </head>
   <body>
       <div class="dialog" style="margin-left:20px;width:60%;">
           <ul>
             <g:each var="c" in="${grailsApplication.controllerClasses}">
                   <li class="controller"><g:link controller="${c.logicalPropertyName}">${c.fullName}</g:link></li>
             </g:each>
           </ul>
       </div>
   </body>
</html>

We still need ability to display admin page. To process is the same as for the HomeController. Change the AdminController so it looks like this:

class AdminController {
   def index = {
       render (view:'admin')
   }
}

But still, when you start application and access the link http://localhost:8080/sbr you are getting old index page. To change this change the web-app/index.gsp file to this:

<html>
   <body>
       <%response.sendRedirect(request.getContextPath()+"/home/");%>
   </body>
</html>

This will redirect you to the HomeController and home page will be displayed after accessing sbr application.

We are almost done. But what is still remaining is to update template that we use for our pages. So go the the grails-app/views/layouts/main.gsp file and change it to look like this:

<html>
   <head>
       <title><g:layoutTitle default="Grails" /></title>
       <link rel="stylesheet" href="${createLinkTo(dir:'css',file:'main.css')}" />
       <g:layoutHead />
       <g:javascript library="application" />               
   </head>
   <body>
       <g:layoutBody />       
   </body>   
</html>

What I did are just simple changes to this file. Actually I have only removed some code from file generated by default.

As it turned out that this post is longer than I have expected let me summarize steps I have done. So after your grails application is generated you are ready to create home and future admin page. I am usually doing these steps:

• Create HomeController and home.gps page
• Create AdminController and admin.gsp page
• Change index.gsp file so it redirects to the HomeController
• Make main.gsp layout file simple.

After those steps basic skeleton of the grails application is prepared.

What remains is to prepare layout of the home.page and this can be achieved by changing main.gsp file. If you remember from the previous post, main.gsp is actually template that we can reuse for all the pages in the grails application. Actually we already did it for the home and admin page.

In the next post I will describe layouting of the main.gsp file or to be more precise I will integrate blueprint css framework into sbr application.

P.S. Don't forget to write some review or post summary on the software books reviews.

Starting with front-end in grails application

[From the series - creating software books reviews grails web application]

In the previous post I have explained how to create grails application and some general aspects of the grails application. If you are expert for the web front-end you can probably jump into domain logic but if you are like me, front-end is probably harder part of the web application development. As it is generally advised to start with the more complex parts of the application I am usually setting up at least general aspects of the user interface. So let us see how is solved front-end of the grails application.

View technology of the grails application is groovy server pages or shorter gsp while sitemesh is used as main templating mechanism. To gain knowledge of the existing gsp tags visit grails documentation. There is description and short example for each tag. If you don't know site mesh don't worry because I don't know it either. The main usage is very easy and does not require knowledge of the sitemesh.

First interesting file to notice is main.gsp that is located in the grails-app/views/layouts. This file is template for other pages of the application. Just to notice, you can have any number of "main.gsp" files in your grails application. One for each different situation you need. E.g. one for pages with three columns, one for pages with two columns and so on.

The most important part of the main.gsp file is:

<g:layoutBody />

When some page as template uses main.gsp, the whole content of the main.gsp page will be displayed and the <g:layoutBody /> will be replaced with the body element of the mentioned page. To specify which template should be used for the gsp page, put following construct in the <head> element of the page.

<meta name="layout" content="NAME_OF_TEMPLATE_FILE" />

and replace the NAME_OF_TEMPLATE_FILE with the name of template without gsp extension.

So if you have page like this one:

<html>
   <head>
           <meta name="layout" content="main" />
   </head>
   <body>
           <p>Hello World</p>
   </body>
</html>

the main.gsp will be displayed an the element <g:layoutBody /> will be replaced with <p>Hello World</p>. I am not sure that this is 100% correct but this is generally how it behaves.

If this is still confusing let try to make some simple example. Assume that we have two template files: main1.gsp and main2.gsp that are of course placed in the grails-app/views/layouts directory.

// main1.gsp
<html>
   <head>
       <title><g:layoutTitle default="Grails" /></title>
       <g:layoutHead />
   </head>
   <body>
       <h1>Hello World</h1>
       <g:layoutBody />       
   </body>   
</html>



//main2.gsp
<html>
   <head>
       <title><g:layoutTitle default="Grails" /></title>
       <g:layoutHead />
   </head>
   <body>
       <g:layoutBody />       
       <h1>Hello World</h1>
   </body>   
</html>

And if we create following two gsp pages

// test1.gsp that uses main1.gsp as a template
<html>
   <head>
       <meta name="layout" content="main1" />
   </head>
   <body>
       <p>Page 1</p>       
   </body>
</html>



// test2.gsp that uses main2.gsp as a template
<html>
   <head>
       <meta name="layout" content="main2" />
   </head>
   <body>
       <p>Page 2</p>       
   </body>
</html>

test1.gsp will be displayed as:

Hello World
Page 1

while test2.gsp will be displayed as:

Page 2
Hello World

This way you have very powerful tool to create set of pages that look the same and you are just changing the business content of the page. The "same" part should be located in the template file while the "business content" should be located in the page. If for some set of pages you need different layout just create new common template for them. All this magic is possible because grails in the background uses sitemesh for this.

Now when there is basic understanding how front-end works in the grails application we are ready to create our home page. And this will be topic of my next post. I will create dummy home page, admin page from the index.gsp and redirect application to the home page.

P.S. Don't forget to write some review or post summary on the software books reviews.

General Aspects of the Grails Application

[From the series - creating software books reviews grails web application]

In the previous post I have created empty "sbr" grails application. Before changing it to the real grails application it would be good to cover some basic aspects and communication flows of the more or less each grails application. This way it will be more clear what is happening. On the picture below I tried to write main aspects and communication flows of the grails application at least as I see them. I don't claim it is correct. If you need completely correct picture and definitions please refer to the Grails documentation.

Lets start from the top of the picture.

Probably as a first thing you want to display something to the end-user.

GSP stands for groovy server pages and is the view technology used in the grails. This means that front-end of the grails application is written in the GSP. To make GSP pages more readable and more scalable you can use TagLibs and Templates. As I like to write easily readable code, taglibs and templates are features of the grails that enables you to write readable GSP pages.

As the input into the GSP page you send a model. Just not to be confused, model is actually map of [key,value] pairs where key is the string and the value can be instance of any groovy or java class available on the classpath. Important part to remember is that value can be instance of any class - not only domain objects. I am making this clear because for the "long" time I was limiting data in the model to the instances of domain objects.

So when you are displaying GSP page, you are using gsp tags, custom taglibs, and templates. Data to be displayed on the page is contained in the model. Example of the map representing model can [bookToDisplay:book]. The bookToDisplay is the key (can be any string) while the book is instance of the groovy class. To e.g. display title of the book in the GSP page you would write ${bookToDisplay.title}.

Now when information is displayed there is big chance we want to send some data back to server and process it.

Controllers are groovy classes stored in the controllers folder. Each closure defined in the controller is considered as action and can be called from the GSP pages. So for example if you click the button on the GSP pages that is wired to some action in the controller, action in that controller will be called. Important thing to remember is that controllers are stateless. Controllers have access to the domain objects and to the services. This means, no business logic should be contained in the controller. Controller should use business logic available in the domain objects and services.

Data sent from the GSP page to the controller is available to the controller via params. params is actually variable containing all the request parameters. Thanks to the groovy it is injected into each controller so you have easy access to all request parameters.

So for example, if you have input field with the name bookTitle, content of the field is available to the controller via construct params.bookTitle.

Now when we got down from the GSP to the controller and we have all necessary data available via params variable the rest is easy.

From the controller class it is very easy to use domain objects and/or services. And when you are on the level of the domain object or service you are working with normal groovy and/or java.

Services are groovy classes stored within services folder. Services provide transactional context for database operations and can by dynamically injected into controller and domain classes. Business logic that is not directly connected with concrete domain object should be put into service. Additionally you can use service to surround transactional behavior around multiple calls on the domain objects.

Domain Objects represents domain of the problem you are solving. They are stored in the domain folder. They are famous because they represent GORM classes, grails solution for persistence. Domain classes are mapped to the databases and the database is automatically generated or updated for you according to relationships between domain objects.

And of course the whole grails framework is built on the top of the hibernate and spring. This ensures stability and scalability of the grails applications.

Summary

When you click on some button or link in the GSP page you are forwarded to the corresponding action in the controller. After performing basic validation in the controller you can use domain objects and services to perform application logic. After all necessary actions are performed you are creating model that is sent and displayed on the GSP page.

In the next post I will return back to the "sbr" project. I will create home page and explain basic layouting options.

P.S. Don't forget to write some review or post summary on the software books reviews.

Creating Grails Application

[From the series - creating software books reviews grails web application]

In this post just for the sake of completeness I will shortly describe how to create grails application. As in the series of the post I will more or less explain some aspects of programming in the Grails and partially recreate software books reviews site the project to create I will call sbr (short for software books reviews).

Note: I am currently using Grails 1.0.3 version.

Creating Grails application is very easy. Open some command line tool and execute the command:

grails create-app sbr

Now the folder named sbr is create and in this folder is new grails application.

Actually you are already able to start this web application by executing following command from the sbr folder:

grails run-app

To access the application in the browser enter: http://localhost:8080/sbr.

In the case you want to start application on another port you can do that using following command:

grails -Dserver.port=[port_number] run-app

And of course instead of the [port_number] you should enter number of the port on which you want to start web application.

When Grails application is started this way without any changes it is run using embedded Jetty web container and in-memory HSQLDB that is default Grails configuration. Later on I will explain how to change database and how to deploy to Tomcat.

Let me shortly explain folders of the grails application. The top level folders are displayed on the following screen shot:

Short explanation of generated folders is:

• grails-app actually contains the main part of the grails application and will be explained separately
• lib - contains all external dependencies to other java libraries and is by default empty
• scripts - contains scripts and is by default empty
• src - contains java and groovy source files and is by default empty
• test - contains unit and integration tests and is by default empty
• web-app - contains web application

The content of the grails-app folder is much more interesting because it contains the heart of your web application.

Names of the folders should be self descriptive enough but shortly:

• conf - contains configuration of the application. From this folder you are able to configure different aspects of the grails application like: datasources, hibernate, spring, bootstrap and so on. In the later post I will explain at least some of those files.
• controllers - contains controllers of the web application. Controllers are accessed from the views and of course represents C of the MVC pattern
• domain - is folder that will contain all application domain objects. All application domain objects are persisted while the database schema is automatically generated using hibernate. All domain objects are thanks to Groovy by default enriched with number of useful methods.
• i18n - is folder used to localized application
• services - are different services that can be used by controllers or domain objects. They are automatically initialized and inserted using spring. They also provide transactional behavior.
• taglib - folder that will contain custom tag libraries. Tag libraries are excellent feature of the grails that enables you to modularize front-end of the grails application. I am using them heavily.
• views - is the folder that contains html and gsp files of the application. In the one word it contains "pages" of the web application.

And although not directly visible in the folder list, another important part for modularizing front-end of the grails application are templates. I will explain how templates can be used in the later posts.

In the next post I will shortly explain general aspects of the grails application, or namely all folders of the grails-app folder. So stay tuned :)

P.S. Don't forget to write some review or post summary on the software books reviews.

Series from the Developing Software Books Reviews

As I have already promised few days ago, I will write a number of posts explaining my experience gained during development of the software books reviews and partially grails tutorials site. Actually during the series of the posts I will more or less recreate software books reviews grails application. Just for the convenience, I will regularly update this post so it points to all posts from this series. So if you will like those posts come and visit this post from time to time.

So the list of the posts so far is:

• Developing Web Applications with Grails
• Creating Grails Application
• General Aspects of the Grails Application
• Starting with front-end in grails application
• Creating home and admin page
• Integrating blueprint into Grails application
• Analyzing domain of the problem - GORM classes
  

Developing Web Applications with Grails

As I have recently released software books reviews I believe I have finally improved my skills also when working with pure front end (html, css) of web application. As I also mentioned in the previous post, I plan to write series of posts explaining development work on the 'software books reviews' site. I hope my experience will be useful for additional developers. As I am coming from back-end Java development, while developing my first Grails applications the hardest part for me was HTML, css, layout... I believe posts I will write will also help other back-end developers to write web sites using Grails.

I plan to write at least one post per week (till there is enough to write). I do not plan to cover basics like how to install grails or how to generate applications. There are already lot of articles covering these topics. But I hope posts will be clear enough so even beginners will be able to understand them.

Lets go to the first topic :)

So if you are reading this probably you want to write web applications using Grails. Let us see what topics one needs to cover to write web application:

• It is necessary to create nice front-end (HTML, css styles, layouts)  (disclaimer: I don't claim that I am making nice front-ends :) )
• It is necessary to implement business logic - behavior of the application
• Probably it is necessary to include security into application
• It is necessary to store data into database
• And very often it is necessary to provide some additional features that are not directly connected with business logic but in these days are more or less "must have". Obvious feature are RSS feeds.

Grails can help us with most of these requirements while hiding most of the complexity from us. Thanks to grails the most complex things are hidden from us but we still have access to them.

Domain objects - domain objects of course describe domain of our business logic. They are automatically persisted and loaded from the database. This means that database schema generation is something we don't need to think about most of the time.

Services - provide functionality that is not part of the domain objects. In services you include functions that are not naturally fitting into domain objects. Further on services handle transactional behavior for you. You can configure them with simple flag.

Plugins - Grails has excellent system of plugins. As we don't want to reinvent wheel we can reuse what is already implemented for us. Plugins will provide us with security, nice front-end components, RSS generation....

Sitemesh - is decorator engine supported by Grails to support view layouts. I am using it only on the basic level but even in such scenario it is very useful.

So these are some basics that will help us to make developing web application fun and fast.  Using those features we will go through example implementation of the software books reviews.

In the next post I will describe how I start project, and at least what are my basic first steps. I don't claim that it is the correct way but for me it turned out to be good.

Some advertisement: if you are reading software related books please be so kind to post review or link to review on the software books reviews.