////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////


== render



=== Purpose


To render different forms of responses from simple text responses, to view and templates.


=== Examples


[source,groovy]
----
// renders text to response
render "some text"

// renders text for a specified content-type/encoding
render(text: "<xml>some xml</xml>", contentType: "text/xml", encoding: "UTF-8")

// render a template to the response for the specified model
def theShining = new Book(title: 'The Shining', author: 'Stephen King')
render(template: "book", model: [book: theShining])

// render each item in the collection using the specified template
render(template: "book", collection: [b1, b2, b3])

// render a template to the response for the specified bean
def theShining = new Book(title: 'The Shining', author: 'Stephen King')
render(template: "book", bean: theShining)

// render the view with the specified model
def theShining = new Book(title: 'The Shining', author: 'Stephen King')
render(view: "viewName", model: [book: theShining])

// render the view with the controller as the model
render(view: "viewName")

// render some markup to the response
render {
    div(id: "myDiv", "some text inside the div")
}

// render some XML markup to the response
def bookList = [
    new Book(title: 'The Shining', author: 'Stephen King'),
    new Book(title: 'The Great Gatsby', author: 'F. Scott Fitzgerald')
]
render(contentType: "text/xml") {
    books {
         for (b in bookList) {
             book(title: b.title, author: b.author)
         }
    }
}

// render a JSON ( https://www.json.org ) response with the builder attribute:
render(contentType: "application/json") {
    book(title: b.title, author: b.author)
}

// render with status code
render(status: 503, text: "Failed to update book ${b.id}")

// render a file
render(file: new File(absolutePath), fileName: "book.pdf")
----


=== Description


A multi-purpose method for rendering responses to the client which is best illustrated with a few examples! Warning - this method does not always support multiple parameters. For example, if you specify both collection and model, the model parameter will be ignored.
Parameters

Parameters:

* `text` (optional) - The text to render
* `builder` (optional) - The builder to use when rendering markup
* `view` (optional) - The view to delegate the rendering to
* `template` (optional) - The template to render. A template is usually an HTML snippet and the file starts with an underscore ("_"). This is used mostly in AJAX requests.
* `layout` (optional) - The layout to use for the response
* `var` (optional) - The name of the variable to be passed into a template, defaults to the Groovy default argument 'it' if not specified
* `bean` (optional) - The bean to use in rendering
* `model` (optional) - The model to use in rendering
* `collection` (optional) - For rendering a template against each item in a collection
* `contentType` (optional) - The contentType of the response
* `encoding` (optional) - The encoding of the response
* `plugin` (optional) - The plugin to look for the template in
* `status` (optional) - The HTTP status code to use
* `file` (optional) - The byte[], java.io.File, or inputStream you wish to send with the response
* `fileName` (optional) - For specifying an attachment file name while rendering a file.
