adminlte-ui: a Grails plugin for installing the AdminLTE template

adminlte-ui is a plugin based on two existing and awesome projects:

• AdminLTE Dashboard and Control Panel Template authored by Abdullah Almsaeed from Almsaeed Studio.
• The Navigation API of the Grails Platform Core plugin.

The goal is to provide a nice UI theme to Grails applications reusing these projects in a way that is as easy and functional as possible.

Also, some ideas for the implementation have been taken from the Kickstart with Bootstrap Grails plugin.

Thanks a lot to all the developers of these mentioned projects! They have done an excellent and very valuable work.

Right now adminlte-ui offers a minimal and very basic functionality.

Dependency on Resources plugin

Given that adminlte-ui depends Grails Platform Core plugin, which in turn depends on Resources plugin, your project will need to use the resources plugin. This have been briefly tested to work with Grails versions 2.3.x, 2.4.x and 2.5.x

Since Grails version 2.4.x the Asset Pipeline plugin is now favored, instead of the already mentioned Resources plugin, but adminlte-ui is not ready to use the Asset Pipeline plugin. Eventually, when Grails Platform Core is updated to work with the Asset Pipeline it will be worth to also adapt and upate adminlte-ui.

Simplest Example

Supposing you have just created a Grails application, with these little changes you will have the AdminLTE template applied to the views:

• In the grails-app/conf/BuildConfig.groovy add the adminlte-ui plugin:

        plugins {
            // ...
            runtime ':resources:1.2.14'
            runtime ':adminlte-ui:0.1.0'
            // ...
        }

• Change the grails-app/views/index.gsp file so it uses the _adminlte_layout instead of the main_content. At the end the meta tag should be left as this:

        <meta name='layout' content='adminlte'/>

Some Customizations

The adminlte-ui plugin allows views' customization through templates that can be overwritten by your application; if you don't change them, then the default views' templates included in the plugin will be used. To overwrite them, put in the grails-app/views/adminlte_tmpl directory any of the following template files:

• _littleDropdown.gsp
• _sidebarForm.gsp
• _sidebarToggle.gsp
• _userDropdown.gsp
• _userPanel.gsp

You can view the source code of them to get an idea of what to change.

Applying taglibs

It's likely you will have to modify the layout to fit your needs and to do that the easiest way is to copy the adminlte.gsp included in the plugin to your application, so its final path is grails-app/views/layouts/adminlte.gsp and after that you can use the adminlte-ui taglibs from that copied layout file to get a custom look. Some examples:

• In the sidebar, set a custom image and a greeting (or caption) for the use

        <altt:sidebar userImage='http://www.fillmurray.com/350/350' userGreeting='Welcome, Mr. John Doe!'/>

• In the top right corner user dropdown of the header bar, set a custom image and other fields for the user

        <altt:header userName='Mr. John Doe' userImage='http://www.fillmurray.com/350/350' userTitle='CEO' userSummary='Online' />

Custom navigation menu

Thanks to the navigation API of the Grails Platform Core plugin, you can customize the generated menu on the left sidebar, as this:

• Create the navigation file, for example grails-app/conf/AppNavigation.groovy with the following content:

        def loggedIn = { ->
            // is up to you what and how to return here
            false
        }

        navigation = {
          appMenu {
            'Login' (controller: 'login', action: 'index', data:[faIcon: 'fa-sign-in'], visible: loggedIn)
            Home(uri: '/', data:[faIcon: 'fa-home'])
            MyController(data:[faIcon: 'fa-circle-o-notch'], controller: 'mycontroller', visible: true) {
              MyAction(action: 'list')
            }
            RandomSites(data:[faIcon: 'fa-institution']) {
              Wikipedia(url: 'http://www.wikipedia.org')
              Grails(url: 'http://www.grails.org')
            }
            'Logout' (controller: 'logout', action: 'index', data:[faIcon: 'fa-sign-out'], visible: loggedIn)
          }
        }

• Change the sidebar taglib. Note that only a menu with a depth of 2 levels is supported (and tested) and also that the scope attribute takes as value the name used within the navigation file

        <altt:sidebar forceDeep='true', depth='2' scope='appMenu' userImage='http://www.fillmurray.com/350/350' userGreeting='Mr. John Doe - CEO'/>

Copyright and License

Copyright 2014-2015 Rodolfo Castellanos

Licensed 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

   http://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.