/KickstartWithBootstrap

Kickstart is an extension for Grails in order to start your project with a good looking frontend. It is intended to be used in rapid application scenarios such as a Startup Weekend or a prototyping session with a customer. This plugin provides adapted scaffolding templates for standard CRUD pages using Twitter's CSS Framework Bootstrap and offers some basic pages for a web site.

Primary LanguageCSS

Home on Grails.org

Introduction

Kickstart is a plugin for Grails in order to start your project with a good looking frontend. It is intended to be used in rapid application scenarios such as a Startup Weekend or a prototyping session with a customer. This plugin provides the following feature:

  • Adapted scaffolding templates for standard CRUD pages using the Bootstrap web page template by Twitter.
  • Initial set of webpages to describe the website (e.g., about.gsp, contact.gsp, and systeminfo.gsp)
  • A language picker that adapts to the available property files in the i18n directory. Using the FamFamFam flag icons.
  • A minimal console logging filter (KickstartFilter.groovy) to help understand which actions are called and params are transmitted

Technologies

Bootstrap

Browser Support

Tech Foundation

Bootstrap Browser Support Technologies Used
Kickstart uses Bootstrap to render web pages. Bootstrap is made by Mark Otto (@mdo) and Billy Gates (@fat). Bootstrap is designed to help people of all skill levels as a complete kit or to start something more complex. Bootstrap is tested and supported in major modern browsers like Chrome 14, Safari 5+, Opera 11, Internet Explorer 7, and Firefox 5. Bootstrap is based on elements of HTML 5, CSS 3, Javascript 1.8, and jQuery 1.7 with progressively enhanced components to enable a responsive design of the website. Kickstart is built using Groovy 2.0 and Java 7 integrated into the Grails 2.1 framework.

Usage

After installation you must call the kickstart script "grails kickstart", which will copy several files into your project.

  grails kickstart

Afterwards create your domain classes (or copy them into the project) and generate controllers and views - they will now use the Bootstrap framework!

Consequences!

The Kickstart script will (after asking you) overwrite a few files in the conf, src, and views directories of your project - you should use it only on fresh new Grails projects.

Affected files and directories (as of version 0.8.0; see script/Kickstart.groovy for current procedure):

  • conf/UrlMappings.groovy
  • conf/Config.groovy (will only get one line appended)
  • src/templates
  • /views/_common (contains common GSP entries such as buttons or modals)
  • /views/_errors (contains error GSP for 404, 500, etc.)
  • /views/_menu (contains menus or submenus)
  • /views/home (contains the index.gsp)
  • /views/layouts (contains layout files)
  • /views/siteinfo (contains separated or static pages such as about.gsp)
  • /views/index.gsp will be deleted!
  • /views/error.gsp will be deleted!

Configuration

Since version 0.9 two config variables are available and can be set in Config.groovy:

  • kickstart.build.calculate can be used to disable the calculation of build numbers and defaults to true
  • kickstart.metrics.calculate can be used to disable the calculation of metrics and defaults to true
Furthermore, the views can be configured using the following settings / variables, which have to be defined in the <head></head> section with the scope "request". An exemplary use of this can be found in the file login/auth.gsp.

Currently, the following settings for the views are supported:

  • layout_nomainmenu to remove the main menu (e.g., containing "Home") in the file "_content_grid.gsp"
  • layout_nosecondarymenu to remove the secondary menu (e.g., containing "List") in the file "_content_grid.gsp"
  • layout_noflashmessage to hide the general presentation of the flash message in the file "_content_grid.gsp"
Similarily, the footer and header can be overwritten (or removed) using sitemesh's pageProperties
  • page.header to define the header by inserting <content tag="page.header'">...</content> in the view (gsp)
  • page.footer to define the footer by inserting <content tag="page.footer'">...</content> in the view (gsp)

Developer Notes

Please note that the datepicker can handle dates after the year 9999 while most databases (e.g., mysql) handle dates with 4-number years. This might result in date that cannot be stored (such as "01/02/20135") and in Exceptions such as "MysqlDataTruncation: Data truncation: Incorrect datetime value: '20135-02-01 00:00:00'" (@see issue #31). If you want to change this behaviour please have a look in the file "src/groovy/CustomDateEditorRegistrar.groovy" and set lenient to false (However, this will also invalidate years before 1000)

Terms of Use

  • Web Layout: Bootstrap 3.0.2, from Twitter Licensed under the Apache License v2.0. Documentation licensed under CC BY 3.0. (@TwBootstrap , http://twitter.github.com/bootstrap/)
  • Datepicker: Datepicker for Bootstrap, Copyright 2012 Stefan Petre, Improvements by Andrew Rowls, Licensed under the Apache License v2.0
  • Flag Icons: FamFamFam Flag Icons by Mark James. They are "available for free use for any purpose with no requirement for attribution".
  • Kickstart Plugins: Code licensed under the Apache License v2.0. Documentation licensed under CC BY 3.0.

Backlog: Work required / Problems

1.x.1 Fix for Date binding (currently, the date binding does not work)
1.x.2 Fix for DatePicker (currently, the datepicker requires jQuery 1.8.3)
1.x.3 Fix for index vs list actions (currently, both are supported)

Changelog

1.1.0 Fresh setup on a newly created Grail 2.3.5 plugin project. Update to Grails 2.3.5.
1.0.5 Removed dependency for Font-Awesome (Bootstrap uses Glyphicon's Icon-Font now)
1.0.4 Correction of "alert-error" into "alert-danger" - changed in Bootstrap 3 (Tip by Leo Bartoloni)
1.0.3 Fix for display:none in scaffolding (Merged by "stlhrt")
1.0.0 Upgrade to Grail 2.3.4
0.9.9.1 Fixed missing search view. Integrated cleanup by Burt Beckwith.
0.9.9 Upgraded to Bootstrap 3.0.2.
0.9.8 Upgraded to Grails 2.2.4. Updated several plugin dependencies. Added Flag for China (zh.png). Updated Datepicker plugin.
0.9.7 Integrated fixes by Craig Sherstan (csherstan)
0.9.6 Updated to Bootstrap 2.3.1 with lesscss 1.3.3
0.9.5 Reduced to the max: removed skin/layout switching. Removed build and metrics calculation. Works on PAAS with less files.
0.9.4 Integrated Font Awesome using the Grails Font Awesome Resources Plugin by Eamonn O'Connell
0.9.3 Upgrade to patched Bootstrap 2.3.0 (had to partially downgrade mixins.less to 2.2.2). Fixed problem with hibernate plugin dependency when using Grails versions less than 2.2.0.
0.9.2 Fixed problem with less file handling if resource plugin is disabled.
0.9.1 Added views for security (prepared for spring security: auth.gsp and denied.gsp). Integrated configuration settings for views. Updated several missing I18N codes.
0.9.0 Added config switches to calculate build numbers and metrics. Updated to Bootstrap 2.2.2 (2.3 has currently compilation errors with lesscss).
0.8.9 Fixed Bug with CloudFoundry and Tomcat which (now) need references to the plugin containing resources (e.g., images)
0.8.8 Fixed Bug with i18n directory when deploying. Removed domain Object for demo page.
0.8.7 Improved the date binding to use default.date.datepicker.format or default.date.format (removing non-Date items).
0.8.6 Changed solution for Less compilation problem (Switch is now in KickstartResources.groovy only). Fixed problem of SkinA alternative in responsive mode. In production mode only one skin is used.
0.8.5 Fixed a problem with CloudFoundry & Less: running in production will not compile less anymore but switch to files directly.
0.8.3 Introduced a demo page with all fields used by the scaffolding mechanism.
0.8.2 Corrected missing copy of resources.groovy.
0.8.1 Fixed error when copying UrlMappings.groovy, which was not packaged into the plugin.
0.8.0 Integrated less templates of two Bootstrap based designs. Corrected links in language selector and config menus.
0.7.2 Integrated a Bootstrap-based checkbox in the taglib and scaffolding templates.
0.7.1 Corrected datepicker problem with Java representation with month. Corrected missing ID in links to edit-actions.
0.7.0 Updated to Bootstrap 2.1.1 and Grails 2.1. Included FamFamFam icons for flags in language selector. Reorganized file structure for views.
0.6.1 Minor bug fix in _Events.gsp script.
0.6.0 Integration of Bootstrap DatePicker. Uses Grails 2.0 files as base for scaffolding, etc. Cleanup of code and scripts.
0.5.7 Added script to calculate or retrieve build numbers.
0.5.6 Empty commit to test Grails plugin publish mechanism
0.5.5 Minor bugfix (missing import) and correction of KickstartWithBootstrapGrailsPlugin.groovy
0.5.4 Added measurement of time to simple console logging in KickstartFilters
0.5.3 Improvement of error.gsp
0.5.2 Cleanup of code and scripts. Improvement of I18N
0.5.1 Minor bugfixes in Bootstrap and layout files
0.5.0 Initial shared version (February 11, 2012)
0.1.0 Initial version (September 21, 2011)