(Quick Reference) # 8.2 Groovy Server Pages Version: 3.2.8 ## Table of Contents ## 8.2 Groovy Server Pages Groovy Servers Pages (or GSP for short) is Grails' view technology. It is designed to be familiar for users of technologies such as ASP and JSP, but to be far more flexible and intuitive.
| Although GSP can render any format, not just HTML, it is more designed around rendering markup. If you are looking for a way to simplify JSON responses take a look at JSON Views.
GSPs live in the `grails-app/views` directory and are typically rendered automatically (by convention) or with the render method such as:
    render(view: "index")
A GSP is typically a mix of mark-up and GSP tags which aid in view rendering.
| Although it is possible to have Groovy logic embedded in your GSP and doing this will be covered in this document, the practice is strongly discouraged. Mixing mark-up and code is a bad thing and most GSP pages contain no code and needn’t do so.
A GSP typically has a "model" which is a set of variables that are used for view rendering. The model is passed to the GSP view from a controller. For example consider the following controller action:
    def show() {
        [book: Book.get(params.id)]
    }
This action will look up a `Book` instance and create a model that contains a key called `book`. This key can then be referenced within the GSP view using the name `book`:
    ${book.title}
| Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on XSS prevention for information on how to prevent XSS attacks.
## 8.2.1 GSP Basics In the next view sections we’ll go through the basics of GSP and what is available to you. First off let’s cover some basic syntax that users of JSP and ASP should be familiar with. GSP supports the usage of `<% %>` scriptlet blocks to embed Groovy code (again this is discouraged):
    <html>
       <body>
         <% out << "Hello GSP!" %>
       </body>
    </html>
You can also use the `<%= %>` syntax to output values:
    <html>
       <body>
         <%="Hello GSP!" %>
       </body>
    </html>
GSP also supports JSP-style server-side comments (which are not rendered in the HTML response) as the following example demonstrates:
    <html>
       <body>
         <%-- This is my comment --%>
         <%="Hello GSP!" %>
       </body>
    </html>
| Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on XSS prevention for information on how to prevent XSS attacks.
## 8.2.1.1 Variables and Scopes Within the `<% %>` brackets you can declare variables:
    <% now = new Date() %>
and then access those variables later in the page:
    <%=now%>
Within the scope of a GSP there are a number of pre-defined variables, including: `application` - The ServletContext instance `applicationContext` The Spring ApplicationContext instance `flash` - The flash object `grailsApplication` - The GrailsApplication instance `out` - The response writer for writing to the output stream `params` - The params object for retrieving request parameters `request` - The HttpServletRequest instance `response` - The HttpServletResponse instance `session` - HttpSession instance `webRequest` - The GrailsWebRequest instance ## 8.2.1.2 Logic and Iteration Using the `<% %>` syntax you can embed loops and so on using this syntax:
    <html>
       <body>
          <% [1,2,3,4].each { num -> %>
             <p><%="Hello ${num}!" %></p>
          <%}%>
       </body>
    </html>
As well as logical branching:
    <html>
       <body>
          <% if (params.hello == 'true')%>
          <%="Hello!"%>
          <% else %>
          <%="Goodbye!"%>
       </body>
    </html>
## 8.2.1.3 Page Directives GSP also supports a few JSP-style page directives. The import directive lets you import classes into the page. However, it is rarely needed due to Groovy’s default imports and GSP Tags:
    <%@ page import="java.awt.*" %>
GSP also supports the contentType directive:
    <%@ page contentType="application/json" %>
The contentType directive allows using GSP to render other formats. ## 8.2.1.4 Expressions In GSP the `<%= %>` syntax introduced earlier is rarely used due to the support for GSP expressions. A GSP expression is similar to a JSP EL expression or a Groovy GString and takes the form `${expr}`:
    <html>
      <body>
        Hello ${params.name}
      </body>
    </html>
However, unlike JSP EL you can have any Groovy expression within the `${..}` block.
| Embedding data received from user input has the risk of making your application vulnerable to an Cross Site Scripting (XSS) attack. Please read the documentation on XSS prevention for information on how to prevent XSS attacks.
## 8.2.2 GSP Tags Now that the less attractive JSP heritage has been set aside, the following sections cover GSP’s built-in tags, which are the preferred way to define GSP pages.
| The section on Tag Libraries covers how to add your own custom tag libraries.
All built-in GSP tags start with the prefix `g:`. Unlike JSP, you don’t specify any tag library imports. If a tag starts with `g:` it is automatically assumed to be a GSP tag. An example GSP tag would look like:
    <g:example />
GSP tags can also have a body such as:
    <g:example>
       Hello world
    </g:example>
Expressions can be passed into GSP tag attributes, if an expression is not used it will be assumed to be a String value:
    <g:example attr="${new Date()}">
       Hello world
    </g:example>
Maps can also be passed into GSP tag attributes, which are often used for a named parameter style syntax:
    <g:example attr="${new Date()}" attr2="[one:1, two:2, three:3]">
       Hello world
    </g:example>
Note that within the values of attributes you must use single quotes for Strings:
    <g:example attr="${new Date()}" attr2="[one:'one', two:'two']">
       Hello world
    </g:example>
With the basic syntax out the way, the next sections look at the tags that are built into Grails by default. ## 8.2.2.1 Variables and Scopes Variables can be defined within a GSP using the set tag:
    <g:set var="now" value="${new Date()}" />
Here we assign a variable called `now` to the result of a GSP expression (which simply constructs a new `java.util.Date` instance). You can also use the body of the `<g:set>` tag to define a variable:
    <g:set var="myHTML">
       Some re-usable code on: ${new Date()}
    </g:set>
The assigned value can also be a bean from the applicationContext:
    <g:set var="bookService" bean="bookService" />
Variables can also be placed in one of the following scopes: `page` - Scoped to the current page (default) `request` - Scoped to the current request `flash` - Placed within flash scope and hence available for the next request `session` - Scoped for the user session `application` - Application-wide scope. To specify the scope, use the `scope` attribute:
    <g:set var="now" value="${new Date()}" scope="request" />
## 8.2.2.2 Logic and Iteration GSP also supports logical and iterative tags out of the box. For logic there are if, else and elseif tags for use with branching:
    <g:if test="${session.role == 'admin'}">
       <%-- show administrative functions --%>
    </g:if>
    <g:else>
       <%-- show basic functions --%>
    </g:else>
Use the each and while tags for iteration:
    <g:each in="${[1,2,3]}" var="num">
       <p>Number ${num}</p>
    </g:each>

    <g:set var="num" value="${1}" />
    <g:while test="${num < 5 }">
        <p>Number ${num++}</p>
    </g:while>
## 8.2.2.3 Search and Filtering If you have collections of objects you often need to sort and filter them. Use the findAll and grep tags for these tasks:
    Stephen King's Books:
    <g:findAll in="${books}" expr="it.author == 'Stephen King'">
         <p>Title: ${it.title}</p>
    </g:findAll>
The `expr` attribute contains a Groovy expression that can be used as a filter. The grep tag does a similar job, for example filtering by class:
    <g:grep in="${books}" filter="NonFictionBooks.class">
         <p>Title: ${it.title}</p>
    </g:grep>
Or using a regular expression:
    <g:grep in="${books.title}" filter="~/.*?Groovy.*?/">
         <p>Title: ${it}</p>
    </g:grep>
The above example is also interesting due to its usage of GPath. GPath is an XPath-like language in Groovy. The `books` variable is a collection of `Book` instances. Since each `Book` has a `title`, you can obtain a list of Book titles using the expression `books.title`. Groovy will auto-magically iterate the collection, obtain each title, and return a new list! ## 8.2.2.4 Links and Resources GSP also features tags to help you manage linking to controllers and actions. The link tag lets you specify controller and action name pairing and it will automatically work out the link based on the URL Mappings, even if you change them! For example:
    <g:link action="show" id="1">Book 1</g:link>

    <g:link action="show" id="${currentBook.id}">${currentBook.name}</g:link>

    <g:link controller="book">Book Home</g:link>

    <g:link controller="book" action="list">Book List</g:link>

    <g:link url="[action: 'list', controller: 'book']">Book List</g:link>

    <g:link params="[sort: 'title', order: 'asc', author: currentBook.author]"
            action="list">Book List</g:link>
## 8.2.2.5 Forms and Fields #### Form Basics GSP supports many different tags for working with HTML forms and fields, the most basic of which is the form tag. This is a controller/action aware version of the regular HTML form tag. The `url` attribute lets you specify which controller and action to map to:
    <g:form name="myForm" url="[controller:'book',action:'list']">...</g:form>
In this case we create a form called `myForm` that submits to the `BookController’s `list` action. Beyond that all of the usual HTML attributes apply. #### Form Fields In addition to easy construction of forms, GSP supports custom tags for dealing with different types of fields, including: textField - For input fields of type 'text' passwordField - For input fields of type 'password' checkBox - For input fields of type 'checkbox' radio - For input fields of type 'radio' hiddenField - For input fields of type 'hidden' select - For dealing with HTML select boxes Each of these allows GSP expressions for the value:
    <g:textField name="myField" value="${myValue}" />
GSP also contains extended helper versions of the above tags such as radioGroup (for creating groups of radio tags), localeSelect, currencySelect and timeZoneSelect (for selecting locales, currencies and time zones respectively). #### Multiple Submit Buttons The age old problem of dealing with multiple submit buttons is also handled elegantly with Grails using the actionSubmit tag. It is just like a regular submit, but lets you specify an alternative action to submit to:
    <g:actionSubmit value="Some update label" action="update" />
## 8.2.2.6 Tags as Method Calls One major different between GSP tags and other tagging technologies is that GSP tags can be called as either regular tags or as method calls from controllers, tag libraries or GSP views. #### Tags as method calls from GSPs Tags return their results as a String-like object (a `StreamCharBuffer` which has all of the same methods as String) instead of writing directly to the response when called as methods. For example:
    Static Resource: ${createLinkTo(dir: "images", file: "logo.jpg")}
This is particularly useful for using a tag within an attribute:
    <img src="${createLinkTo(dir: 'images', file: 'logo.jpg')}" />
In view technologies that don’t support this feature you have to nest tags within tags, which becomes messy quickly and often has an adverse effect of WYSIWYG tools such as Dreamweaver that attempt to render the mark-up as it is not well-formed:
    <img src="<g:createLinkTo dir="images" file="logo.jpg" />" />
#### Tags as method calls from Controllers and Tag Libraries You can also invoke tags from controllers and tag libraries. Tags within the default `g:` namespace can be invoked without the prefix and a `StreamCharBuffer` result is returned:
    def imageLocation = createLinkTo(dir:"images", file:"logo.jpg").toString()
Prefix the namespace to avoid naming conflicts:
    def imageLocation = g.createLinkTo(dir:"images", file:"logo.jpg").toString()
For tags that use a custom namespace, use that prefix for the method call. For example (from the FCK Editor plugin):
    def editor = fckeditor.editor(name: "text", width: "100%", height: "400")
## 8.2.3 Views and Templates Grails also has the concept of templates. These are useful for partitioning your views into maintainable chunks, and combined with Layouts provide a highly re-usable mechanism for structured views. #### Template Basics Grails uses the convention of placing an underscore before the name of a view to identify it as a template. For example, you might have a template that renders Books located at `grails-app/views/book/_bookTemplate.gsp`:
    <div class="book" id="${book?.id}">
       <div>Title: ${book?.title}</div>
       <div>Author: ${book?.author?.name}</div>
    </div>
Use the render tag to render this template from one of the views in `grails-app/views/book`:
    <g:render template="bookTemplate" model="[book: myBook]" />
Notice how we pass into a model to use using the `model` attribute of the `render` tag. If you have multiple `Book` instances you can also render the template for each `Book` using the render tag with a `collection` attribute:
    <g:render template="bookTemplate" var="book" collection="${bookList}" />
#### Shared Templates In the previous example we had a template that was specific to the `BookController` and its views at `grails-app/views/book`. However, you may want to share templates across your application. In this case you can place them in the root views directory at grails-app/views or any subdirectory below that location, and then with the template attribute use an absolute location starting with `/` instead of a relative location. For example if you had a template called `grails-app/views/shared/_mySharedTemplate.gsp`, you would reference it as:
    <g:render template="/shared/mySharedTemplate" />
You can also use this technique to reference templates in any directory from any view or controller:
    <g:render template="/book/bookTemplate" model="[book: myBook]" />
#### The Template Namespace Since templates are used so frequently there is template namespace, called `tmpl`, available that makes using templates easier. Consider for example the following usage pattern:
    <g:render template="bookTemplate" model="[book:myBook]" />
This can be expressed with the `tmpl` namespace as follows:
    <tmpl:bookTemplate book="${myBook}" />
#### Templates in Controllers and Tag Libraries You can also render templates from controllers using the render controller method. This is useful for JavaScript heavy applications where you generate small HTML or data responses to partially update the current page instead of performing new request:
    def bookData() {
        def b = Book.get(params.id)
        render(template:"bookTemplate", model:[book:b])
    }
The render controller method writes directly to the response, which is the most common behaviour. To instead obtain the result of template as a String you can use the render tag:
    def bookData() {
        def b = Book.get(params.id)
        String content = g.render(template:"bookTemplate", model:[book:b])
        render content
    }
Notice the usage of the `g` namespace which tells Grails we want to use the tag as method call instead of the render method. ## 8.2.4 Layouts with Sitemesh #### Creating Layouts Grails leverages Sitemesh, a decorator engine, to support view layouts. Layouts are located in the `grails-app/views/layouts` directory. A typical layout can be seen below:
    <html>
        <head>
            <title><g:layoutTitle default="An example decorator" /></title>
            <g:layoutHead />
        </head>
        <body onload="${pageProperty(name:'body.onload')}">
            <div class="menu"><!--my common menu goes here--></div>
            <div class="body">
                <g:layoutBody />
            </div>
        </body>
    </html>
The key elements are the layoutHead, layoutTitle and layoutBody tag invocations: `layoutTitle` - outputs the target page’s title `layoutHead` - outputs the target page’s head tag contents `layoutBody` - outputs the target page’s body tag contents The previous example also demonstrates the pageProperty tag which can be used to inspect and return aspects of the target page. #### Triggering Layouts There are a few ways to trigger a layout. The simplest is to add a meta tag to the view:
    <html>
        <head>
            <title>An Example Page</title>
            <meta name="layout" content="main" />
        </head>
        <body>This is my content!</body>
    </html>
In this case a layout called `grails-app/views/layouts/main.gsp` will be used to layout the page. If we were to use the layout from the previous section the output would resemble this:
    <html>
        <head>
            <title>An Example Page</title>
        </head>
        <body onload="">
            <div class="menu"><!--my common menu goes here--></div>
            <div class="body">
                This is my content!
            </div>
        </body>
    </html>
#### Specifying A Layout In A Controller Another way to specify a layout is to specify the name of the layout by assigning a value to the "layout" property in a controller. For example, if you have a controller such as:
    class BookController {
        static layout = 'customer'

        def list() { ... }
    }
You can create a layout called `grails-app/views/layouts/customer.gsp` which will be applied to all views that the `BookController` delegates to. The value of the "layout" property may contain a directory structure relative to the `grails-app/views/layouts/` directory. For example:
    class BookController {
        static layout = 'custom/customer'

        def list() { ... }
    }
Views rendered from that controller would be decorated with the `grails-app/views/layouts/custom/customer.gsp` template. #### Layout by Convention Another way to associate layouts is to use "layout by convention". For example, if you have this controller:
    class BookController {
        def list() { ... }
    }
You can create a layout called `grails-app/views/layouts/book.gsp`, which will be applied to all views that the `BookController` delegates to. Alternatively, you can create a layout called `grails-app/views/layouts/book/list.gsp` which will only be applied to the `list` action within the `BookController`. If you have both the above mentioned layouts in place the layout specific to the action will take precedence when the list action is executed. If a layout may not be located using any of those conventions, the convention of last resort is to look for the application default layout which is `grails-app/views/layouts/application.gsp`. The name of the application default layout may be changed by defining a property in `grails-app/conf/application.groovy` as follows:
    grails.sitemesh.default.layout = 'myLayoutName'
With that property in place, the application default layout will be `grails-app/views/layouts/myLayoutName.gsp`. #### Inline Layouts Grails' also supports Sitemesh’s concept of inline layouts with the applyLayout tag. This can be used to apply a layout to a template, URL or arbitrary section of content. This lets you even further modularize your view structure by "decorating" your template includes. Some examples of usage can be seen below:
    <g:applyLayout name="myLayout" template="bookTemplate" collection="${books}" />

    <g:applyLayout name="myLayout" url="http://www.google.com" />

    <g:applyLayout name="myLayout">
    The content to apply a layout to
    </g:applyLayout>
#### Server-Side Includes While the applyLayout tag is useful for applying layouts to external content, if you simply want to include external content in the current page you use the include tag:
    <g:include controller="book" action="list" />
You can even combine the include tag and the applyLayout tag for added flexibility:
    <g:applyLayout name="myLayout">
       <g:include controller="book" action="list" />
    </g:applyLayout>
Finally, you can also call the include tag from a controller or tag library as a method:
    def content = include(controller:"book", action:"list")
The resulting content will be provided via the return value of the include tag. ## 8.2.5 Static Resources Grails 3 integrates with the Asset Pipeline plugin to provide sophisticated static asset management. This plugin is installed by default in new Grails applications. The basic way to include a link to a static asset in your application is to use the resource tag. This simple approach creates a URI pointing to the file. However modern applications with dependencies on multiple JavaScript and CSS libraries and frameworks (as well as dependencies on multiple Grails plugins) require something more powerful. The issues that the Asset-Pipeline plugin tackles are: Reduced Dependence - The plugin has compression, minification, and cache-digests built in. Easy Debugging - Makes for easy debugging by keeping files separate in development mode. Asset Bundling using require directives. Web application performance tuning is difficult. The need for a standard way to expose static assets in plugins and applications. The need for extensible processing to make languages like LESS or Coffee first class citizens. The asset-pipeline allows you to define your javascript or css requirements right at the top of the file and they get compiled on War creation. Take a look at the documentation for the asset-pipeline to get started. If you do not want to use the Asset-Pipeline plugin, you can serve the static assets from directories `src/main/resources/public` or `src/main/webapp`, but the latter one only gets included in WAR packaging but not in JAR packaging.
| Static resources located in `src/main/resources/public` or `src/main/webapp` are resolved under the `/static/**` URI by default. You can change the URI pattern with the following configuration:
grails-app/conf/application.yml
    grails.resources.pattern: /**
## 8.2.6 Sitemesh Content Blocks Although it is useful to decorate an entire page sometimes you may find the need to decorate independent sections of your site. To do this you can use content blocks. To get started, partition the page to be decorated using the `<content>` tag:
    <content tag="navbar">
    ... draw the navbar here...
    </content>

    <content tag="header">
    ... draw the header here...
    </content>

    <content tag="footer">
    ... draw the footer here...
    </content>

    <content tag="body">
    ... draw the body here...
    </content>
Then within the layout you can reference these components and apply individual layouts to each:
    <html>
        <body>
            <div id="header">
                <g:applyLayout name="headerLayout">
                    <g:pageProperty name="page.header" />
                </g:applyLayout>
            </div>
            <div id="nav">
                <g:applyLayout name="navLayout">
                    <g:pageProperty name="page.navbar" />
                </g:applyLayout>
            </div>
            <div id="body">
                <g:applyLayout name="bodyLayout">
                    <g:pageProperty name="page.body" />
                </g:applyLayout>
            </div>
            <div id="footer">
                <g:applyLayout name="footerLayout">
                    <g:pageProperty name="page.footer" />
                </g:applyLayout>
            </div>
        </body>
    </html>
## 8.2.7 Making Changes to a Deployed Application One of the main issues with deploying a Grails application (or typically any servlet-based one) is that any change to the views requires that you redeploy your whole application. If all you want to do is fix a typo on a page, or change an image link, it can seem like a lot of unnecessary work. For such simple requirements, Grails does have a solution: the `grails.gsp.view.dir` configuration setting. How does this work? The first step is to decide where the GSP files should go. Let’s say we want to keep them unpacked in a `/var/www/grails/my-app` directory. We add these two lines to `grails-app/conf/application.groovy` :
    grails.gsp.enable.reload = true
    grails.gsp.view.dir = "/var/www/grails/my-app/"
The first line tells Grails that modified GSP files should be reloaded at runtime. If you don’t have this setting, you can make as many changes as you like but they won’t be reflected in the running application until you restart. The second line tells Grails where to load the views and layouts from.
| The trailing slash on the `grails.gsp.view.dir` value is important! Without it, Grails will look for views in the parent directory.
Setting "grails.gsp.view.dir" is optional. If it’s not specified, you can update files directly to the application server’s deployed war directory. Depending on the application server, these files might get overwritten when the server is restarted. Most application servers support "exploded war deployment" which is recommended in this case. With those settings in place, all you need to do is copy the views from your web application to the external directory. On a Unix-like system, this would look something like this:
    mkdir -p /var/www/grails/my-app/grails-app/views
    cp -R grails-app/views/* /var/www/grails/my-app/grails-app/views
The key point here is that you must retain the view directory structure, including the `grails-app/views` bit. So you end up with the path `/var/www/grails/my-app/grails-app/views/…​` . One thing to bear in mind with this technique is that every time you modify a GSP, it uses up permgen space. So at some point you will eventually hit "out of permgen space" errors unless you restart the server. So this technique is not recommended for frequent or large changes to the views. There are also some System properties to control GSP reloading:
Name | Description | Default
--- | --- | ---
grails.gsp.enable.reload | alternative system property for enabling the GSP reload mode without changing `application.groovy` | grails.gsp.reload.interval
interval between checking the lastmodified time of the gsp source file | unit is milliseconds | 5000
grails.gsp.reload.granularity | the number of milliseconds leeway to give before deciding a file is out of date. this is needed because different roundings usually cause a 1000ms difference in lastmodified times | 1000
GSP reloading is supported for precompiled GSPs since Grails 1.3.5 . ## 8.2.8 GSP Debugging #### Viewing the generated source code Adding "?showSource=true" or "&showSource=true" to the url shows the generated Groovy source code for the view instead of rendering it. It won’t show the source code of included templates. This only works in development mode The saving of all generated source code can be activated by setting the property "grails.views.gsp.keepgenerateddir" (in `application.groovy`) . It must point to a directory that exists and is writable. During "grails war" gsp pre-compilation, the generated source code is stored in grails.project.work.dir/gspcompile (usually in ~/.grails/(grails_version)/projects/(project name)/gspcompile). #### Debugging GSP code with a debugger See Debugging GSP in STS #### Viewing information about templates used to render a single url GSP templates are reused in large web applications by using the `g:render` taglib. Several small templates can be used to render a single page. It might be hard to find out what GSP template actually renders the html seen in the result. The debug templates -feature adds html comments to the output. The comments contain debug information about gsp templates used to render the page. Usage is simple: append "?debugTemplates" or "&debugTemplates" to the url and view the source of the result in your browser. "debugTemplates" is restricted to development mode. It won’t work in production. Here is an example of comments added by debugTemplates :
    <!-- GSP #2 START template: /home/.../views/_carousel.gsp
         precompiled: false lastmodified: ... -->
    .
    .
    .
    <!-- GSP #2 END template: /home/.../views/_carousel.gsp
         rendering time: 115 ms -->
Each comment block has a unique id so that you can find the start & end of each template call. | Quick Reference (hide)