Adding Todo Lists (Handlers and the Service Layer) - ColdBox Series Part 8d

Now we are really getting into this ColdBox stuff. We've got a view set up, we've got some handlers, we've auto-wired our handlers, and we've added ColdSpring into our application. Now we can start to do stuff.

So where did we leave off last time? Thinking.... thinking... thinking... oh yeah.

Accepting user input

Before we went off on a tangent of setting up ColdSpring and Autowiring Handlers, we had two simple handler methods inside of the list.cfc handler. We had addList() and doAddList().

addList():

doAddList():

addList() just added some values to the event object and then set the view to be displayed. doAddList() accepted the event arguments, which includes the form fields that were submitted from the form inside of the view listForm.cfm and is now ready to do something with that data.

NOTE: Don't forget that in the last post, we set up this handler to be autowired with the todoService, so right now it is available to us in the variables scope.

But FIRST, let's make some changes

So just like with any project, change happens. In this case, it was due to my design. Originally, I thought we would auto-increment our primary key in the lists and items tables, but it occurs to me that I don't like that, and I don't want to have to deal with getting the key back after it is set. So we are going to modify our DB design, and we'll need to make some model changes too. Nothing major.

First, since we have not yet done anything with our database, we can just drop the tables and recreate them. Here's the script.

Next, we need to make some changes to the model objects to accommodate this change. In the todoGateway's createList() method we need to add the listID to the INSERT statement.

We'll need to do the same for createitem():

Ok, one more change. In the WHERE statements for updateList(), updateItem() and createItem() inside of todoGateway, we need to change the CFSQLType attributes to cf_sql_varchar. Change it in both where clause statements in updateItem() and in the last value statement for createItem(). A total of 4 changes are needed.

Working with the service layer

We have this fancy new service layer with one method in it, and that is just for dependency injection, what else are we going to use it for? Well, what I use the service layer for is to communicate between the controller (ColdBox) and the model(Beans and Gateway). Some might argue that the service layer is part of the model. I'm not sure if I care.

We want our doListAdd() method to so something now, don't we? But what? Well we want it to take the user input, validate it, and persist it to the database. We're going to do all but the validation today. Let's start with this.

There is actually quite a lot going on in these 5 new lines of code. Let's examine each.

1. Here we are putting the request collection into a "virtual scope" (a struct) called rc. This rc scope contains all of the FORM and URL scoped variables and the name of the event that was called. This way we can get the data out of the event without needing the very verbose getValue() method. We will not actually be using this struct today.

2. Here we are calling the todoService (the one that was autowired in) method newList(). I supposed we'll need to create that method now ;). This method will create a new bean, persist it to the database as an empty record with only and id and return the bean with the id in it.

3. This line is pretty cool. ColdBox has a beanFactory plugin that does several things. One of those things is to populate a bean from the event object data. It will look at the object's properties and call setter methods for each of the properties on the bean that is passed in. So if there is a firstname property, it will call setFirstname() on the bean and pass in the value from the event object. So as long as our formfields were named the same as the bean properties, we can use this.

4. The listBean is then passed to the todoService.saveList() method to be persisted to the database.

5. The last line tells ColdBox which event to fire next. We are telling it to fire the list.allLists event so that we can view all of the lists that we have made so far. We'll need to create that too.

Our first Service Method

In our doAddList() handler we are making a call to a todoService method called newList(). Let's make that method.

Here we are using the createObject() method to create an instance of the List object. To do this we are calling the init() method and passing in a new UUID using the createUUID() method. NOTE: In the future this would be a good place for an Object Factory that would be injected using ColdSpring, but we are trying to keep this simple.

The method is then going to take that newly created bean and pass it into the todoGateway's createList() method. NOTE: remember, the todoGateway was injected with ColdSpring. The createList method takes the bean as-is and persists it to the database. At this point we have not yet called populateBean(), so, other than the UUID ListID, this bean is empty.

Finally, it returns the bean to the handler.

Now our handler populates the bean:

This will take the form field values and populate the bean with them.

The bean is then passed to the todoService.saveList() method. So we'll need to create that.

This is simple enough. It takes in the bean as an argument, then passes it to the todoGateway's updateList() method, which will actually save it to the database.

Finishing Up

Finally, the handler uses setNextEvent() to fire the next ColdBox event. Which is list.allLists. So let's create that event handler method.

Like all event handler methods, we are first taking in the event object as an argument. Then we are creating a query object by calling getAllLists() from the todoService. Next we are injecting that query into the event object using the setValue() method. I am giving it the same name, "qAllLists". Lastly, the method sets a new view to display, allLists, which is actually allLists.cfm inside of the /views directory.

We have a few things here to create. todoService does not have a getAllLists() method, and there is not a allLists.cfm file.

todoService.getAllLists():

allLists.cfm:

getAllLists(), like many of our service methods, makes a call to the gateway object. The method todoGateway.getAllLists() is for requesting all of the lists. Now, there was an oversight in my design, because we never added this method to the todoGateway, so let's.

Then our allLists.cfm view is getting the query object our of the event object and dumping the values. This will show that the lists we create are actually being persisted.

Conclusion

Well, that was fun. We got a lot done today. We handled our user input, created a bean, populated it with the user input and persisted it to the database. We also set up some methods and a view for displaying all of the lists. On top of all that we made some changes to the model layer to make things a little better. I am attaching the entire application to the post.

Next time we will look at adding data validation, I think. Who knows, maybe we will talk about astro-photography instead.