# createLink

## Purpose

Creates a link that can be used where necessary (for example in an href, javascript, ajax call etc.)

## Examples

Example controller for an application called "shop":

    class BookController {
         static defaultAction="list"
         def list = { [ books: Book.list( params ) ] }
         def show = { [ book : Book.get( params['id'] ) ] }
    }

Example usages for above controller:

    <g:createLink action="show" id="1" /> == /shop/book/show/1
    <g:createLink action="show" params="[foo: 'bar', boo: 'far']"/> == /shop/book/show?foo=bar&boo=far
    <g:createLink controller="book" /> == /shop/book
    <g:createLink controller="book" action="list" /> == /shop/book/list
    <g:createLink url="[action:'list',controller:'book']" /> == /shop/book/list
    <g:createLink controller="book" absolute="true"/> == http://portal.mygreatsite.com/book
    <g:createLink controller="book" base="http://admin.mygreatsite.com"/> == http://admin.mygreatsite.com/book
    <g:createLink controller = "book" action="list" params="[title:'The Shining', author:'Stephen King', id:'1']"/> == /shop/book/list/1?title=The+Shining&author=Stephen+King

Example as a method call in GSP:

    <a href="${createLink(action:'list')}">my link</a>

results in:

    <a href="/shop/book/list">my link</a>

## Description

Attributes

- `action` (optional) - The name of the action to use in the link, if not specified the default action will be linked
- `controller` (optional) - The name of the controller to use in the link, if not specified the current controller will be linked
- `id` (optional) - The id to use in the link
- `fragment` (optional) - The link fragment (often called anchor tag) to use
- `mapping` (optional) - The named URL mapping to use to rewrite the link
- `params` (optional) - A map containing URL query parameters
- `url` (optional) - A map containing the action,controller,id etc.
- `absolute` (optional) - If set to "true" will prefix the link target address with the value of the grails.serverURL property from Config, or http://localhost:<port> if no value in Config and not running in production.
- `base` (optional) - Sets the prefix to be added to the link target address, typically an absolute server URL. This overrides the behaviour of the `absolute` property, if both are specified.

## Source

Show Source

    def createLink = { attrs ->
            def writer = getOut()
            // prefer URI attribute
            if (attrs.uri) {
                writer << handleAbsolute(attrs)
                writer << attrs.uri.toString()
            }
            else {
                // prefer a URL attribute
                def urlAttrs = attrs
                if (attrs.url instanceof Map) {
                    urlAttrs = attrs.remove('url').clone()
                }
                else if (attrs.url) {
                    urlAttrs = attrs.remove('url').toString()
                }            if (urlAttrs instanceof String) {
                    if (useJsessionId) {
                        writer << response.encodeURL(urlAttrs)
                    }
                    else {
                        writer << urlAttrs
                    }
                }
                else {
                    def controller = urlAttrs.containsKey("controller") ? urlAttrs.remove("controller")?.toString() : controllerName
                    def action = urlAttrs.remove("action")?.toString()
                    if (controller && !action) {
                        GrailsControllerClass controllerClass = grailsApplication.getArtefactByLogicalPropertyName(ControllerArtefactHandler.TYPE, controller)
                        String defaultAction = controllerClass?.getDefaultAction()
                        if (controllerClass?.hasProperty(defaultAction)) {
                            action = defaultAction
                        }
                    }
                    def id = urlAttrs.remove("id")
                    def frag = urlAttrs.remove('fragment')?.toString()
                    def params = urlAttrs.params && urlAttrs.params instanceof Map ? urlAttrs.remove('params') : [:]
                    def mappingName = urlAttrs.remove('mapping')
                    if (mappingName != null) {
                        params.mappingName = mappingName
                    }
                    if (request['flowExecutionKey']) {
                        params."execution" = request['flowExecutionKey']
                    }                if (urlAttrs.event) {
                        params."_eventId" = urlAttrs.remove('event')
                    }
                    def url
                    if (id != null) params.id = id
                    def urlMappings = applicationContext.getBean("grailsUrlMappingsHolder")
                    UrlCreator mapping = urlMappings.getReverseMapping(controller,action,params)                // cannot use jsessionid with absolute links
                    if (useJsessionId && !attrs.absolute) {
                        url = mapping.createURL(controller, action, params, request.characterEncoding, frag)
                        def base = attrs.remove('base')
                        if (base) writer << base
                        writer << response.encodeURL(url)
                    }
                    else {
                        url = mapping.createRelativeURL(controller, action, params, request.characterEncoding, frag)
                        writer << handleAbsolute(attrs)
                        writer << url
                    }
                }
            }
        }