This application is used to track linguistic information about hunter gatherer languages.

NECESSARY ADDITIONAL FILES TO OBTAIN AND INSTALL:

Before running the application you will need to place a valid DataSource.groovy file in the grails-app/conf/ directory.

IMPORTANT WARNING ABOUT SOURCE FILE CORRUPTION FROM GRAILS

WARNING WARNING WARNING: The first time you run grails run-war', it **WILL CORRUPT YOUR SOURCE FILES**. Specifically, it will overwrite our modified scaffolding files with generic, unmodified versions. This is VERY VERY BAD. We're trying to figure out a way to defeat this behavior, but for the moment, you must do the following the first time you run grails run-war' on a repository:

(1) make sure any outstanding changes are committed to git (2) run grails run-war' (3) make sure to dogit reset --hard' to get rid of the messed up versions

Thankfully, this only appears to happen once, the first time `grails run-war' is executed. Possibly, though, if stuff in ~/.grails or some other caching directory is removed, the bug will bite again.

Comments about further configuration (you don't need to worry about this, it's been done automatically in the repository files and in the standard DataSource.groovy file):

Also, the mail.jar that ships with grails can cause conflicts with the one that ships with tomcat. To fix these problems, run this command after compiling the app but before creating the war file (replace 1.2.0.RC2 with the version of grails you are using):

rm `~/.grails/1.2.0.RC2/projects/HunterGathererLanguages -name mail.jar`

When configuring the database, be sure to use UTF-8. Using a connection string like the following one should accomplish this for MySQL:

jdbc:mysql://servername.example.com/hunter_gatherer?useUnicode=yes&characterEncoding=UTF-8

Also, you need to set the Hibernate dialect in your DataSource.groovy file to this value so that tables are created with a UTF-8 character set:

dialect = org.hibernate.dialect.MySQL5UTF8InnoDBDialect

Accounts you need to create in order to do work on the HunterGathererLanguages software:

(1) Get an account at github.com, and send them a public key (DSA or RSA) so that they can authenticate you. (2) Email Andrew ([email protected]) and get him to add you as a committer to the HunterGathererLanguages project on github. (3) Create an account on the production HunterGathererLanguages database web server at http://tomcat.la.utexas.edu:8080/HunterGathererLanguages/ (4) Get a LAITS account???

For more info about Grails:

See "Groovy and Grails Recipes". This is basically the example application from the book. What we present to the user is basically the admin screen -- "normally" there is another nicer level on top.

See the following web page for a quick start: http://www.grails.org/Quick+Start

Problem with sending email when trying to sign up for account:

This is a LAITS problem with their server not accepting connections from our app. Email them and they'll fix it. Can also create accounts manually from Pattie's admin account. (User admin piece is a plugin.)

Running development vs. production:

To run in development, cd to grails-app and then execute `grails run-war'. This starts up a web server and prints out is a URL that you connect to in your browser.

run-app vs. run-war: -- run-war compiles everything once then runs -- run-app does the same but also tries to recompile on the fly (problem is that it's too eager and recompiles even if you haven't changed anything)

Pushing to production:

1. Run `grails make-war' -- creates a WAR file with a version number attached
2. Symlink the .war file to releases/HunterGathererLanguages.war
3. Run `make-gz' script -- creates .tar.gz file and copies it to proper place
4. Email LAITS (Nick ...) and tell him that a new file has been dropped
5. He will promote it to where it needs to go

Note about developers:

1. Andrew Young ([email protected])
2. Simon Greenhill
3. Mike Speriosu ([email protected], but didn't actually commit anything)

About Grails versions:

This was created using Grails 1.2.0.RC2. There are a lot of dependencies that are specified in `application.properties'. In theory,

(a) it should be possible to use the released Grails 1.2.0 (by changing the applications.properties file)

(b) it should be possible to upgrade to the latest Grails by running `grails upgrade', but Mike had problems getting this working

The different servers:

-- The front end runs on ... -- The back end runs on ...

Creating the database:

The first time you run Grails against a brand-new database (created by LAITS) when you run in production mode (i.e. `grails run-war' with some flag to run in production mode), Grails creates the tables in the database.

Files:

???

.git/ .gitignore Stuff related to Git.

.classpath .project .settings/ Eclipse project files. .settings has preferences for Groovy plugin in Eclipse.

HunterGathererLanguages-test.launch HunterGathererLanguages.launch HunterGathererLanguages.tmproj These are NetBeans project files, possibly out of date.

README This file.

application.properties Grails properties.

build.xml Ant build file.

csv/ Files used to populate the database.

get-libs.sh Script to download some necessary plugins. Needs to be run once after fetching from git.

grails-app/ The code for the Grails app. See Grails documentation.

ivy.xml ivysettings.xml Ivy is a tool by Apache that handles dependencies for Java programs -- part of Grails.

releases/ Contains `make-gz', a script for deploying to production. When pushing to production, ...

semanticFields.tab Used to populate the database (Andrew wrote a script to do it).

src/ See src/README.

test/ In theory, contains test cases, but not yet written.

web-app/ Static content that goes into the .war file (Javascript, images, CSS).

xml/ XML versions of files in CSV format, used to populate the database.

About filtering (from Andrew):

"Filtering" shows search criteria for limiting the display of various lists of stuff. For example, in LexicalDataController:

http://github.com/vaelen/HunterGathererLanguages/blob/master/grails-app/controllers/LexicalFeatureController.groovy

In this controller, the user can filter by English Headword, Spanish Headword, Portuguese Headword, French Headword, Latin Headword, Case Study Region, Semantic Field, Category, Part of Speech, and Export Set.

The code in Controller.groovy is the default implementation, and these methods should then be overridden by controllers that need to add filtering, such as LexicalFeatureController.

It looks like Simon duplicated a lot of the code into the individual controllers that shouldn't need to be there. I don't know why that was done, but Simon should be able to tell us.

Here you can see which developer wrote each line of code in the file:

http://github.com/vaelen/HunterGathererLanguages/blame/master/grails-app/controllers/LexicalFeatureController.groovy

This next link is the file as I originally wrote it. You'll notice that only getFilterList() and doFilter() are overridden, NOT filter(), parseFilter(), and list(). Duplicating these methods into each controller defeats the purpose of putting the methods in Controller.groovy to begin with, so I'm not sure why Simon did this.

http://github.com/vaelen/HunterGathererLanguages/blob/5b846e15c1b512983c7e4b64b7180815f2b11e41/grails-app/controllers/LexicalFeatureController.groovy

The data returned by getFilterList() and doFilter() is then used by the list.gsp view, which displays the various text fields and select fields that handle the filtering.

Let me know if this didn't answer your question.