Presented by Alexey Vedishchev Developing Web-applications with Grails framework American University of Nigeria, 2016 Part VI: Mapping URLs

Grails provides working URL mappings right out of the box. The default URL mapping configuration is yet one more place that the Grails framework leverages the powerful idea of convention over configuration to lessen the burden put on the application developer. Sometimes, though, you will want to deviate from the convention and define your own custom mappings. General Idea 2

For example, you may want to create more descriptive and human-readable URLs. Grails gives you the ability to easily define these custom URL mappings. Defining application-specific URL mappings is something that comes up all the time while building web applications. The technique for configuring URL mappings in Grails is really powerful while remaining very simple to work with. General Idea 3

Like a lot of configuration options in a Grails application, configuring custom URL mappings involves writing a little bit of Groovy code, and that’s it. In particular, no XML configuration files are involved. General Idea 4

This chapter will describe the flexible URL mapping system provided by Grails and demonstrate how to: manage both forward and reverse URL lookups; map requests to controller actions or views; map exceptions to controller actions and views. Chapter Outline 5

The default URL mapping configuration in a Grails app is simple. The first part of the URL corresponds to the name of a controller, and the second, optional part of the URL corresponds to the name of an action defined in that controller. For example, the /store/index URL will map to the index action in the StoreController. Specifying the action name is optional, so if the action name is left out of the URL, then the default action for the specified controller will be executed. Understanding the Default URL Mapping 6

Finally, the last piece of the URL is another optional element that represents the value of a request parameter named id. For example, the /album/show/42 URL will map to the show action in the AlbumController with a request parameter named id that has a value of 42. The defiition of the default mapping is in grails- app/conf/UrlMappings.groovy. Understanding the Default URL Mapping 7

The key to this mapping is the string "/$controller/$action?/$id?". Notice that the $action and $id elements are both followed by a question mark. The question mark indicates an optional piece of the URL. The $controller element has no question mark, so it is a required piece of the URL. A mapping can define any number of optional elements. If a mapping does contain any optional elements, they must all appear at the end of the pattern. Understanding the Default URL Mapping 8

In the default mapping, each of the elements in the URL is a variable. Variable elements are prefixed with a $ sign. A URL mapping can contain static elements as well. A static element in a URL mapping is simply text that must be part of the URL in order for a particular mapping to apply. Including Static Text in a URL Mapping 9

This mapping will match URLs such as /showAlbum/album/show/42 and /showAlbum/album/list class UrlMappings { static mappings = { "/showAlbum/$controller/$action?/$id?" { constraints { // apply constraints here } Including Static Text in a Mapping 10

The controller and action names do not need to be part of the URL. These special elements can be eliminated from the URL pattern and specified as properties of the mapping. As shown previously, the default mapping supports a URL such as /album/show/42, which will map to the show action in the AlbumController. An application can choose to support a URL such as /showAlbum/42 to access that same controller action. Removing the Controller and Action Names from the URL 11

class UrlMappings { static mappings = { "/showAlbum/$id" { controller = 'album' action = 'show' } //... } Specifying the Controller and Action as Properties of the Mapping 12

class UrlMappings { static mappings = { "/showAlbum/$id"(controller:'album', action:'show') //... } Specifying the Controller and Action as Properties of the Mapping (One More Way) 13

Grails supports request parameters using the standard HTTP request parameter notation. A URL such as /showArtist?artistName=Rush will work if there is a mapping like that class UrlMappings { static mappings = { "/showArtist"(controller:'artist', action:'show') //... } Embedding Parameters in a Mapping 14

Grails supports request parameters using the standard HTTP request parameter notation. A URL such as /showArtist?artistName=Rush will work if there is a mapping like that class UrlMappings { static mappings = { "/showArtist"(controller:'artist', action:'show') //... } Embedding Parameters in a Mapping 15

Instead of /showArtist?artistName=Rush, let’s support a shorter URL such as /showArtist/Rush. class UrlMappings { static mappings = { "/showArtist/$artistName"(controller:'artis t', action:'show') //... } Embedding a Request Parameter in the URL 16

class ArtistController { def show() { def nameToSearchFor = params.artistName.replaceAll('_', ' ') def artist = Artist.findByName(nameToSearchFor) // do whatever is appropriate with the artist... } Accessing a Request Parameter in the Controller Action 17

Sometimes you might want a certain URL pattern to map directly to a view. This is useful when the view does not require any data to be passed in and no controller action is required. In such a case, you can define a URL mapping that is associated with a view rather than with a controller action. The syntax is the same as mapping to an action except that a value must be specified for the view property instead of the action property. Mapping to a View 18

This mapping will handle all requests to the root of the application (/) by rendering the GSP at grailsapp/views/welcome.gsp: class UrlMappings { static mappings = { "/"(view:'/welcome') //... } } Mapping to a View 19

The mapping engine also allows a mapping to specify a view that belongs to a particular controller: class UrlMappings { static mappings = { "/find"(view:'query', controller:'search') //... } } Remember that no controller action is being executed for this mapping. The controller is being specified only so the framework can locate the appropriate GSP. Mapping to a View for a Particular Controller 20

Applying Constraints to URL Mappings 21 The URL mapping engine provides a really powerful mechanism for applying constraints to variables embedded in a URL mapping. The constraints are similar those applied to domain objects. Applying constraints to variables in a URL mapping can greatly simplify the job of weeding out certain kinds of invalid data that would otherwise have to be dealt with in an imperative manner in a controller or service.

Applying Constraints to URL Mappings 22 Consider a blogging application written in Grails. A typical format for a URL in a blogging system might be something like: /grailsblogs/2016/01/15/news

A Typical Blog-Type URL Mapping 23 class UrlMappings { static mappings = { "/grailsblogs/$year/$month/$day/$entry_name? " { controller = 'blog' action = 'display' constraints { // apply constraints here } //... }

Applying Constraints to Mapping Parameters 24 A problem with this mapping is that it will match not only a URL such as /grailsblogs/2016/01/15/ new_grails_release but also a URL such as /grailsblogs/grails/rocks/big/time. In this case, the controller action would receive the value grails for the year, rocks for the month, and so on. Dealing with a scenario like this would complicate the logic in the controller.

Applying Constraints to Mapping Parameters 25 A better way to manage it is to apply constraints to the mapping that would let the framework know that grails is not a valid match for the year parameter in the mapping, for example. As is the case with domain-class constraints, mapping parameters may have as many constraints applied to them as necessary. All the constraints must pass in order for the mapping to apply.

Applying Constraints to Mapping Parameters 26 class UrlMappings { static mappings = { "/grailsblogs/$year/$month/$day/$entry_name?" { controller = 'blog' action = 'display' constraints { year matches: /[0-9]{4}/ month matches: /[0-9]{2}/ day matches: /[0-9]{2}/ } //... }

Including Wildcards in a Mapping 27 You’ve seen how a mapping may contain static text as well as any number of variable parameters (optional and required), and you’ve also seen how constraints may be applied to variable parameters. One more aid to flexibility that you can use in a mapping definition is a wildcard. Wildcards represent placeholders in a mapping pattern that may be matched by anything but do not represent information that will be passed as request parameters.

A Wildcard in a Mapping 28 class UrlMappings { static mappings = { "/images/*.jpg"(controller:'image') //... } This mapping will handle any request for a file under the /images/ directory that ends with the.jpg extension. For example, this mapping will handle /images/header.jpg and /images/ footer.jpg, but it will not match requests for.jpg files that may exist in some subdirectory under the /images/ directory.

A Double Wildcard in a Mapping 29 A double wildcard can be used to match any number of subdirectories: class UrlMappings { static mappings = { "/images/**.jpg"(controller:'image') //... }

A Double Wildcard with a Variable in a Mapping 30 For some situations, it may be desirable for the value that matched the wildcard to be passed to the controller as a request parameter: class UrlMappings { static mappings = { "/images/$pathToFile**.jpg"(controller:' image') //... }

The URL mapping engine provided by Grails is very flexible. Nearly any URL pattern that you might want to map to a particular controller action can easily be configured simply by writing a small amount of Groovy code in UrlMappings.groovy. The framework provides a lot of mechanisms that enable you to spend less time configuring the framework and more time solving business problems in your application. The URL mapping engine is one more example of this. Custom URL mappings are simple to write and simple to test. Part VI Summary 31