(Quick Reference)

4 Plugin Configuration - Reference Documentation

Authors: Kaleidos Open Source

Version: 0.6.4

4 Plugin Configuration

The power of the grails admin plugin is that you can create a full-fleshed grails administration page only by configuration. In order to be flexible enough the plugin provides several configuration for tunning your application.

There are no mandatory configuration to run your application with this plugin, but to start working with it you have to set some properties.

Your Config.groovy would look like this:

grails.plugin.admin.accessRoot = "/myconfadmin"

grails.plugin.admin.domains = [ "conferences.Room", "conferendes.Attendee", "conferendes.Conference", "conferendes.Talk", "conferendes.Speaker" ]

grails.plugin.admin.domain.Conference = "conferences.ConferenceAdmin"

4.1 Integration with Spring Security

Static assets filters

Spring security by default doesn't allow the static resources from the plugin to be served.

You should add the following rules to your Config.groovy in order to allow these:

grails.plugin.springsecurity.controllerAnnotations.staticRules = [
    '/**/libs/**':                    ['permitAll'],
    '/**/js/**':                      ['permitAll'],
    '/**/css/**':                     ['permitAll'],
    '/**/images/**':                  ['permitAll']
]

API Basic Authentication

In order to use Basic Authentication for the Grails Admin API you have to configure the following parameters for Spring Security:

  • Activate Spring security:

grails.plugin.springsecurity.active = true
  • Activate the Basi Authorization filter

grails.plugin.springsecurity.useBasicAuth = true
  • Only apply the filter for the admin API endpoints:

Be careful because "admin" could be replaced with the property "grails.plugin.admin.accessRoot"

grails.plugin.springsecurity.filterChain.chainMap = [
   "/admin/api/**": 'JOINED_FILTERS,-exceptionTranslationFilter',
   '/**': 'JOINED_FILTERS,-basicAuthenticationFilter,-basicExceptionTranslationFilter'
]

4.2 Global Configuration

Domains List

Necessary

Not mandatory, but necessary to start working with admin

You have to explicitely set the domains that your application is going to manage. The property is a list of strings containing the full class name of your domains.

By default it contains an empty list.

grails.plugin.admin.domains = [
    "conferences.Speaker",
    "conferences.Talk"
]

Optionaly, you can group your domains so they are divided into logical groups.

grails.plugin.admin.domains."Conference Management" = [
    "conferences.Conference",
    "conferences.Talk"
]

grails.plugin.admin.domains."People" = [ "conferences.Attendee", "conferences.Speaker" ]

grails.plugin.admin.domains."Infrastructures" = [ "conferences.Building", "conferences.Room" ]

Admin URL Access Root

Optional

A good security practice is not to use a "standard" URI to access your administration backend.

Grails-Admin allows you to customize the endpoint so it uses a custom one.

By default the value is /admin

grails.plugin.admin.accessRoot = "/admin"

Allow Default Configuration

When a domain has a relationship with another domain (i.e. 1-1 relationship) if the related object has not been defined in the managed domains list you will not be able to interact with it by default.

You can explicitely activate default configuration on objects that are not defined in your domain list by using this property.

Optional

grails.plugin.admin.allowDefaultConfig = false

Security. Access role

Optional

The default role required for a user to access the admin is "ROLE_ADMIN" but you can customize to use any role defined with your application.

grails.plugin.admin.security.role = "ROLE_ADMIN"

Security. Forbid unsecured admin on Production environment

By default the plugin checks if your application is secured or not (currently using Spring Security 1.x and Spring Security 2.x).

If your application is not secured, by default, the plugin will throw an exception when it's boostraped on production environments.

You can override this behaviour by setting this property to "false"

Optional

grails.plugin.admin.security.forbidUnsecureProduction = true

4.3 Per Domain Configuration

You can configure the administration screens with a specific DSL that can be configure either in your Config.groovy or in classes of type "Admin" that also allows the redefinition of some methods.

Configuration on Config.groovy file

grails.plugin.admin.domain.Speaker = {
    create includes: ["name", "description", "dateCreated", "endDate"],
    widget "birthDate", "net.kaleidos.plugins.admin.widget.DateInputWidget", dateFormat: "yyyyMMdd"
}

Configuration on "Admin" entities

Edit Config.groovy to associate your admin class with the domain entity that manage.

grails.plugin.admin.domain.Speaker = "conferences.SpeakerAdmin"

and create admin class.

Place it under grails-app/admin directory.

Note: You can place your admin class wherever you want in classpath, but we recommend this to possible future artifacts control

package conferences

class SpeakerAdmin { static options = { create includes: ["name", "description", "dateCreated", "endDate"], widget "birthDate", "net.kaleidos.plugins.admin.widget.DateInputWidget", dateFormat: "yyyyMMdd" }

}

Include properties

You can select which properties the administration will display on a specific operation.

The order will be preserved in the form.

grails.plugin.admin.domain.Speaker = {
    list includes: ["name", "description", "dateCreated", "endDate"]
    create includes: ["name", "description"]
    edit includes: ["name", "description"]
}

Exclude Properties

You can customize which properties will be excluded from the administration screens.

grails.plugin.admin.domain.Speaker = {
    list excludes: ["startDate", "endDate"]
    create excludes: ["startDate", "endDate"]
    edit excludes: ["startDate", "endDate"]
}

Properties Groups

All the properties for a domain can be visually grouped so they have a logic structure.

grails.plugin.admin.domain.Talk = {
    groups {
        "Speaker" fields: [ 'speaker' ]
        "Talk Info" style:"collapse", fields: [ 'talkDate', 'talkTime', 'room' ]
    }
}

If you don't put a property inside a group it will be displayed at the beginning of the form without any group.

Passing properties to widgets

Some widgets need some internal properties. Also, there are properties that you can pass to any widget. In order to do so, you must specify them on the configuration

grails.plugin.admin.domain.Conference = {
    widget "name",  help:"This is a help text"
}

grails.plugin.admin.domain.Talk = {
    widget "talkDate", dateFormat:"dd/MM/yyyy"
}

Specify a widget

If you want to select a specific widget for a property (for example, to use the PasswordInputWidget instead of the default TextInputWidget) you can use this configuration. Further documentation and a list of all the builtin widgets on the Built In Widgets section.

grails.plugin.admin.domain.User = {
    widget "password", "PasswordInputWidget"
}

Custom widgets

For some properties the default editor/renderer may not be enough. You can customize this behaviour writing your own widget. Further documentation on the Custom Widgets section.

grails.plugin.admin.domain.Conference = {
    widget "coordinates", "sample.MapWidget", height:400, width:600
}