# 2. Getting Started

## 2.1 Downloading and Installing

The first step to getting up and running with Griffon is to install the distribution. To do so follow these steps:

- Download a binary distribution of Griffon and extract the resulting zip file to a location of your choice
- Set the GRIFFON_HOME environment variable to the location where you extracted the zip

- On Unix/Linux based systems this is typically a matter of adding something like the following `export GRIFFON_HOME=/path/to/griffon` to your profile
- On Windows this is typically a matter of setting an environment variable under `My Computer/Advanced/Environment Variables`

- Now you need to add the `bin` directory to your `PATH` variable:

- On Unix/Linux base system this can be done by doing a `export PATH="$PATH:$GRIFFON_HOME/bin"`
- On windows this is done by modifying the `Path` environment variable under `My Computer/Advanced/Environment Variables`

If Griffon is working correctly you should now be able to type `griffon` in the terminal window and see output similar to the below:

    Welcome to Griffon 0.9.5-rc2 - http://griffon.codehaus.org/
    Licensed under Apache Standard License 2.0
    Griffon home is set to: /usr/local/griffon-0.9.5-rc2
    No script name specified. Use 'griffon help' for more info

## 2.2 Creating an Application

To create a Griffon application you first need to familiarize yourself with the usage of the `griffon` command which is used in the following manner:

    griffon [command name]

In this case the command you need to execute is create-app:

    griffon create-app demoConsole

This will create a new directory inside the current one that contains the project. You should now navigate to this directory in terminal:

    cd demoConsole

## 2.3 A Groovy Console Example

The "create-app" target created a Griffon MVC Triad for you in the models, views, and controllers directory named after the application. Hence you already have a model class DemoConsoleModel in the models directory.

The application model for this application is simple: it contains properties that hold the script to be evaluated and the results of the evaluation. Make sure you paste the following code into `griffon-app/models/democonsole/DemoConsoleModel.groovy`.

    package democonsoleimport groovy.beans.Bindableclass DemoConsoleModel {
        String scriptSource
        @Bindable def scriptResult
        @Bindable boolean enabled = true
    }

The controller is also trivial: throw the contents of the script from the model at a groovy shell, then store the result back into the model. Make sure you paste the following code into `griffon-app/controllers/democonsole/DemoConsoleController.groovy`.

    package democonsoleclass DemoConsoleController {
        private GroovyShell shell = new GroovyShell()    // these will be injected by Griffon
        def model
        def view    def executeScript = { evt = null ->
            model.enabled = false
            def result
            try {
                result = shell.evaluate(model.scriptSource)
            } finally {
                model.enabled = true
                model.scriptResult = result
            }
        }
    }

The Griffon framework will inject references to the other portions of the MVC triad if fields named model, view, and controller are present in the model or controller. This allows us to access the view widgets and the model data if needed

The executeScript method will be used in the view for the button action. Hence the `evt` parameter, and the default value so it can be called without an action event.

Finally, the Griffon framework can be configured to inject portions of the builders it uses. By default, the Threading classes are injected into the controller, allowing the use of the `edt`, `doOutside` and `doLater` methods from SwingBuilder.

You may notice that there's no explicit threading management. All Swing developers know they must obey the Swing Rule: long running computations must run outside of the EDT; all UI components should be queried/modified inside the EDT. It turns out Griffon is aware of this rule, making sure an action is called outside of the EDt by default, all bindings made to UI components via the model will be updated inside the EDT also. We'll setup the bindings in the next example.

The view classes contain the visual components for your application. Please paste the following code into `griffon-app/views/democonsole/DemoConsoleView.groovy`.

    package democonsoleapplication(title:'DemoConsole', pack:true,
      locationByPlatform:true,
      iconImage: imageIcon('/griffon-icon-48x48.png').image,
      iconImages: [imageIcon('/griffon-icon-48x48.png').image,
                   imageIcon('/griffon-icon-32x32.png').image,
                   imageIcon('/griffon-icon-16x16.png').image]) {
        panel(border:emptyBorder(6)) {
            borderLayout()        scrollPane(constraints:CENTER) {
                textArea(text:bind(target: model, 'scriptSource'),
                    enabled: bind { model.enabled },
                    columns: 40, rows: 10)
            }        hbox(constraints:SOUTH) {
                button("Execute", actionPerformed: controller.executeScript,
                    enabled: bind { model.enabled })
                hstrut 5
                label 'Result:'
                hstrut 5
                label text: bind { model.scriptResult }
            }
        }
    }

The view script is a fairly straightforward SwingBuilder script. Griffon will execute these groovy scripts in context of it's UberBuilder (a composite of the SwingBuilder and whatever else is thrown in).

Now to get the application running. You can do this by calling the run-app command:

    griffon run-app

This command should compile all sources and package the application, you'll see a similar result as depicted by the following screenshot after a few seconds

Standalone mode is not the only way to run your application, try the following command to run it in webstart mode: run-webstart. Conversely run-applet will run your application in applet mode. The best of all is that you did not have to touch a single line of configuration in order to switch modes!

## 2.4 Getting Set-up in an IDE

### IntelliJ IDEA

IntelliJ IDEA and the JetGroovy plug-in offer good support for Groovy/Grails/Griffon developers. Refer to the section on Groovy and Grails support on the JetBrains website for a feature overview.

#### Integrating an existing Griffon project

To integrate Griffon with IntelliJ run the following command to generate appropriate project files:

    griffon integrate-with --intellij

#### Creating a new Griffon project

Follow these steps to create and run a new Griffon project with IDEA

#1 Bring up the "New Project" wizard. You should see Griffon as one of the available options

#2 Choose name and location for the new project

#3 Configure a Griffon SDK if you haven't done so already

#4 Click on the Finish button and develop with pleasure your Griffon project

### NetBeans

A good Open Source alternative is Oracle's NetBeans, which provides a Groovy/Griffon plugin that automatically recognizes Griffon projects and provides the ability to run Griffon applications in the IDE, code completion and integration with Oracle's Glassfish server.

#### Integrating an existing Griffon project

NetBeans does not require any special integration support, it understands the layout of a Griffon project as long as the Griffon plugin is installed. Just select "Open" from the menu and locate the folder that contains your project. It's that simple. Follow these steps to install the Griffon NetBeans plugin.

Prerequisites: Java, Groovy and Grails plugins installed and up to date.

#1 Download the plugin

Follow this link to download the latest zip distribution of the plugin.

#2 Unpack the zip file into a directory of your choosing

#3 Open the plugin manager dialog. Go to the "Downloaded" tab, then click on the "Add Plugins..." button. Locate and select the NBM files that were uncompressed in the previous step.

#4 Select both plugins (using the checkboxes) and click on "Install".

#5 Restart your IDE and enjoy!

#### Creating a new Griffon project

Prerequisites: You must have the Griffon plugin installed. Follow the steps explained in the previous section to get the job done.

#1 Bring up the "New Project" wizard. Click on "Groovy" then on "Griffon Application".

#2 Choose name and location for the new project

#3 Configure a Griffon SDK if you haven't done so already

#4 Click on the Finish button

### Eclipse

We recommend that users of Eclipse looking to develop Griffon application take a look at SpringSource Tool Suite, which offers built in support for Groovy.

#### Integrating an existing Griffon project

To integrate Griffon with Eclipse run the following command to generate appropriate project files:

    griffon integrate-with --eclipse

Then follow these steps to fully integrate and run the application

#1 Install the Eclipse Support plugin

    griffon install-plugin eclipse-support

#2 Configure a pair Classpath User Variables in the preferences dialog. GRIFFON_HOME should point to the install directory of Griffon, while USER_HOME should point to your account's home directory.

#3 Bring up the "New Project" wizard. Select "Existing Projects into Workspace"

#4 Select the directory of the application that contains .project/.classpath files

#4 Click on the Finish button

##### Running Griffon commands within Eclipse

We'll rely on Eclipse's Ant support to get the job done, but first we need to generate an Ant build file

    griffon integrate-with --ant

Refresh the contents of your project. Open the build file in the Ant View. Select any target and execute by double clicking on it.

### TextMate

Since Griffon' focus is on simplicity it is often possible to utilize more simple editors and TextMate on the Mac has an excellent Groovy/Griffon bundle available.

Follow these steps to install the Groovy bundle

#1 Create a local bundle directory

    mkdir ~/Library/Application Support/TextMate/Bundles/

#2a If you have git installed then just clone the repository

    cd ~/Library/Application Support/TextMate/Bundles/
    git clone https://github.com/textmate/groovy.tmbundle.git

#2b Alternatively download a copy of the latest version from github as a zip and unpack it. Rename the unpacked directory to `groovy.tmbundle`.

Follow these steps to install the Griffon bundle

#1 Create a local bundle directory

    mkdir ~/Library/Application Support/TextMate/Bundles/

#2a If you have git installed then just clone the repository

    cd ~/Library/Application Support/TextMate/Bundles/
    git clone https://github.com/griffon/griffon.tmbundle.git

#2b Alternatively download a copy of the latest version from github as a zip and unpack it. Rename the unpacked directory to `griffon.tmbundle`.

Now configure the `PATH` environment variable within TextMate. Make sure that `$GRIFFON_HOME/bin` in expanded form is set

#### Integrating an existing Griffon project

To integrate Griffon with TextMate run the following command to generate appropriate project files:

    griffon integrate-with --textmate

Alternatively TextMate can easily open any project with its command line integration by issuing the following command from the root of your project:

    mate .

You should see a similar display like the next one

##### Running Griffon commands within TextMate

The Griffon bundle provides new commands under the "Bundles" menu. Search for the "Griffon submenu".

Selecting "Run App" will execute the run-app command on the currently open project

## 2.5 Convention over Configuration

Griffon uses "convention over configuration" to configure itself. This typically means that the name and location of files is used instead of explicit configuration, hence you need to familiarize yourself with the directory structure provided by Griffon.

Here is a breakdown and links to the relevant sections:

- `griffon-app` - top level directory for Groovy sources.

- `conf` - Configuration sources.
- `models` - Models.
- `views` - Views.
- `controllers` - Controllers.
- `services` - Services.
- `resources` - Images, properties files, etc.
- `i18n` - Support for internationalization (i18n).

- `scripts` - Gant scripts.
- `src` - Supporting sources.

- `main` - Other Groovy/Java sources.

- `test` - Unit and integration tests.

## 2.6 Running an Application

Griffon applications can be run in standalone mode using the run-app command:

    griffon run-app

Or in applet mode using the run-applet command:

    griffon run-applet

Or in webstart mode using the run-webstart command:

    griffon run-webstart

More information on the run-app command can be found in the reference guide.

## 2.7 Testing an Application

The `create-*` commands in Griffon automatically create integration tests for you within the `test/integration` directory. It is of course up to you to populate these tests with valid test logic, information on which can be found in the section on Testing. However, if you wish to execute tests you can run the test-app command as follows:

    griffon test-app

Griffon also automatically generates an Ant `build.xml` which can also run the tests by delegating to Griffon' test-app command:

    ant test

This is useful when you need to build Griffon applications as part of a continuous integration platform such as CruiseControl.

## 2.8 Creating Artefacts

Griffon ships with a few convenience targets such as create-mvc, create-script and so on that will create Controllers and different artifact types for you.

> These are merely for your convenience and you can just as easily use an IDE or your favorite text editor.

There are many such `create-*` commands that can be explored in the command line reference guide.