Lookups Plugin

  • Tags: functionality, ui
  • Latest: 1.4
  • Last Updated: 12 May 2010
  • Grails version: 1.3.0 > *
  • Authors: Paul Fernley
0 vote
Dependency:
compile ":lookups:1.4"

 Documentation

Summary

Description

Lookups Plugin

Description

This plugin allows the creation and maintenance of pseudo reference (lookup) tables. Within the lookup system, you create 'realms' such as 'countries' or 'order.status' and can then create code/value pairs within those realms. The plugin comes with lookup and lookupValue controllers with associated CRUD screens that presume you are using a layout called main.

Installation

Execute the following from your application directory:

grails install-plugin lookups

The plugin creates two domains called Lookup and LookupValue. It also copies two properties files called lookups.properties and lookupValues.properties to the i18n directory of your application overwriting any files of the same name. Two image files (false.png and true.png) are copied to the images directory of your application overwriting any files of the same name.

After installation, the Lookup table in your database should have a unique index on the 'realm' column, but since Hibernate may or may not create this index, you are advised to check it exists otherwise performance may suffer. Similarly, the LookupValues table should have a non-unique index on its 'code' column and you are again advised to check that this exists. Of the two properties files that the installation places in the i18n directory of your application, the lookups.properties bundle is used by the lookup system for its own texts. The lookupValues properties bundle is used by you to internationalize text values in the code/value pairs you create. Note, however, that if you have the localizations plugin, the database will be used rather than these two properties files, per the internalinalization section below.

Lookup codes and their values are held in memory in a 'least recently used cache' for fast repeated access. The default maximum cache size is 64kb, but memory is only used as is needed. If you wish to alter the maximum size (amount of memory) used by the cache, you may do so by making an entry similar to the following in your Config.groovy file:

lookups.cache.size.kb = 32

The above example Config.groovy entry reduces the cache size to 32kb. Setting the cache size to zero disables caching with a consequent increase in databases activity. You can check the cache statistics using a URL such as: http://myServer/myApp/lookup/cache. Note that you may have to refresh your browser window to see the most up to date statistics.

Usage

The components of the plugin are in a package called org.grails.plugins.lookups and any class that wishes to access the components directly must include the following:

import org.grails.plugins.lookups.*

When creating a realm within the lookup system, you specify the type of data to be held by both its codes and its values. Possible data types are String, Integer, Decimal and Date. Decimal data types are returned as BigDecimal objects.

The plugin provides a lookupSelect tag that takes the place of a normal select tag for setting values in a record and is used as follows:

<g:lookupSelect id="status" name="status" realm="order.status"
                value="${sales.status}"/>

or, if you prefer to use the actual id of the value record...

<g:lookupSelectById id="status" name="status" realm="order.status" value="${sales.status}"/>

In the above example, the id and name attributes refer to the property for which the selection list is being created, the realm attribute refers to the 'realm' within the lookups system that holds the code/value pairs you wish to select from and the value attribute refers to the current code setting of the record being created or edited.

Similarly, when displaying a record (such as on a show or list page) you may display the value of the code, rather than the code itself, by using the lookupValue tag:

<g:lookupValue realm="order.status" value="${sales.status}"/>

or, if you prefer to use the actual id of the value record...

<g:lookupValueById realm="order.status" value="${sales.status}"/>

Note that, by default, the value to be displayed is not HTML encoded. If you wish it to be HTML encoded, add the following attribute to the lookupValue tag: encodeAs="HTML". You may also specify a default value if the code cannot be found by adding an attribute to the lookupValue tag such as: default="Unknown code" etc.

You may access the programmatic equivalents of the lookupSelect and lookupValue tags using the following method calls:

// List of code/value pairs as maps
def lst = org.grails.plugins.lookups.Lookup.codeList("order.status")

// The value for code 23 def val = org.grails.plugins.lookups.Lookup.valueFor("order.status", 23)

For the Lookup.codeList method, the codes and values can be accessed using code such as: lst[n].code and lst[n].value. For the Loookup.valueFor method, you can specify a default, if you wish, such as in:

def val = org.grails.plugins.lookups.Lookup.valueFor("order.status",
        23, "Unknown code")

Since the valueFor method returns null if the code you pass it cannot be found, you may use this fact in domain constraint validations, as follows:

static constraints = {
  status(blank:false, validator: {val, obj ->
    return org.grails.plugins.lookups.Lookup.valueFor("order.status",
            val) != null
  })
}

The above programming examples have all used absolute values for the code to be looked up (e.g. the 23 in some of the examples). There are equivalent methods for using the id of a value, as in:

// List of id/value pairs as maps
def lst = org.grails.plugins.lookups.Lookup.idList("order.status")

// The value for the given id def id = valueInstance.id def val = org.grails.plugins.lookups.Lookup.valueForId("order.status", id)

// The value for the given id, using a default if required def val = org.grails.plugins.lookups.Lookup.valueFor("order.status", id, "Unknown code")

Internationalization

As mentioned above, it is possible to have String lookup values internationalized by placing code/translated-text pairs in to the lookupValues.properties file or, if you have the localizations plugin installed, in to the database. In both cases, the general format of the the code within the properties file or database is: lookups.realm.code. For example, in the lookupValues.properties file you might make entries such as:

lookups.order.status.R=Received
lookups.order.status.D=Despatched

In the above examples, 'order.status' is the lookup realm and R and D are two codes you have created in that realm. Alternately, if you were using the localizations plugin, you would create records in the database with codes of 'lookups.order.status.R' and 'lookups.order.status.D' with text settings of 'Received' and 'Despatched' respectively.

Compatibility

This plugin was written using Java version 1.6u18 and Grails version 1.3.0.

If you have the help-balloons plugin installed, on-line help will be provided on the lookups plugin screens, otherwise you will need to read the help texts in the lookups.properties file to see what each field does. If you have the settings plugin installed and have created settings with keys of pagination.max and/or pagination.default then the lookups plugin will use those settings for its pagination. If you have the criteria plugin installed then users of the lookup and lookup value list pages will be able to limit the records displayed using selection criteria. If you have the drilldowns plugin installed, users will be able to drill down from the lookup page to the lookup values page. The drilldowns plugin makes maintaining the various 'realm' code/value pairs much more convenient. If you have the menus plugin installed, a 'return to menu' button will be placed after the 'home' button on all lookups pages. If you have the localizations plugin installed, all translation of texts will be done via the database rather than property bundles.

History

Version 1.4. (2010-05-12) Update to Grails v1.3

Version 1.3. (2009-12-30) Update to Grails v1.2 plus enhancements from Kalin Wilson

Version 1.2. (2009-04-03) Integration fix for drilldowns plugin

Version 1.1. (2009-04-01) Update to Grails v1.1 and packages.

Version 1.0. (2008-11-18) Initial release