Wednesday, October 14, 2009

Multi-Document Griffon Applications

In this post we're going to build the skeleton of a multi-document (tabbed) Griffon application.  Tabbed interfaces are extremely common.  You're probably even viewing this in a web browser with a few open tabs as we speak. We'll be implementing the document-handling logic, so all you will need to do is add your own application-specific logic.

Let's dive in by creating a new Griffon application and creating a Document MVC group:
griffon create-app MultiDocumentExample
cd MultiDocumentExample
griffon create-mvc Document

In our application model, MultiDocumentExampleModel.groovy, we need to add some properties to keep track of open and active documents. We also need a separate 'state' class (more on that later):
import groovy.beans.Bindable

class MultiDocumentExampleModel {
    @Bindable Map activeDocument = null
    List openDocuments = []
    DocumentState state = new DocumentState()
}

@Bindable class DocumentState {
    boolean isDirty = false
}

Next up is the view: MultiDocumentExampleView.groovy. For this minimal example, we'll define some common actions and a tabbed pane for displaying the documents, but you can customize it to suit your application:
actions {
    action(
        id: 'newAction', 
        name:'New', 
        accelerator: shortcut('N'), 
        closure: controller.newAction
    )
    action(
        id: 'openAction', 
        name:'Open', 
        accelerator: shortcut('O'), 
        closure: controller.openAction
    )
    action(
        id: 'closeAction', 
        name:'Close', 
        accelerator: shortcut('W'), 
        closure: controller.closeAction, 
        enabled: bind { model.activeDocument != null }
    )
    action(
        id: 'saveAction', 
        name:'Save', 
        accelerator: shortcut('S'), 
        closure: controller.saveAction, 
        enabled: bind { model.state.isDirty }
    )
}

application(title: 'Multiple Document Example',
    size:[800,600], 
    //pack:true,
    //location:[50,50],
    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],
    defaultCloseOperation: 0,
    windowClosing: { evt -> if (controller.canClose()) { app.shutdown() } }
) {
    menuBar(id: 'menuBar') {
        menu(text: 'File', mnemonic: 'F') {
            menuItem(newAction)
            menuItem(openAction)
            menuItem(closeAction)
            menuItem(saveAction)
        }
    }
 
    tabbedPane(id: 'documents', stateChanged: { evt -> 
        controller.activeDocumentChanged() 
    })
}

If you look close, you'll see I'm using the window closing trick I blogged awhile ago. The last piece of the puzzle is the controller: MultiDocumentExampleController.groovy. This is where we do the heavy lifting.
class MultiDocumentExampleController {
    int count = 0  // not strictly required
    def model
    def view

    void mvcGroupInit(Map args) {}

    void activeDocumentChanged() {
        // de-activate the existing active document
        if (model.activeDocument) { 
            model.activeDocument.controller.deactivate() 
        }

        // figure out the new active document
        int index = view.documents.selectedIndex
        model.activeDocument = index == -1 ? null : model.openDocuments[index]
        if (model.activeDocument) { 
            model.activeDocument.controller.activate(model.state) 
        }
    }
 
    boolean canClose() {
        return model.openDocuments.inject(true) { flag, doc -> 
            if (flag) flag &= doc.controller.close() }
    }

    def newAction = { evt = null ->
        // TODO: use an id that makes sense for your application, like a file name
        String id = "Document " + (count++) 
  
        def document = buildMVCGroup('Document', id, 
            tabs: view.documents, id: id, name: id /* TODO pass other args */)
        if (document.controller.open()) {
            model.openDocuments << document
            view.documents.addTab(document.model.name, document.view.root)
            view.documents.selectedIndex = view.documents.tabCount - 1
        } else {
            destroyMVCGroup(id)
        }
    }
 
    def openAction = { evt = null ->
        // TODO: pop up a open file dialog or whatever makes sense

        // TODO: use an id that makes sense for your application, like a file name
        String id = "Document" + (count++)

        // check to see if the document is already open
        def open = model.openDocuments.find { it.model.id == id }
        if (open) {
            view.documents.selectedIndex = model.openDocuments.indexOf(open)
        } else {
            def document = buildMVCGroup('Document', id, 
                tabs: view.documents, id: id, name: id /* TODO pass other args */)
            if (document.controller.open()) {
                model.openDocuments << document
                view.documents.addTab(document.model.name, document.view.root)
                view.documents.selectedIndex = view.documents.tabCount - 1
            } else {
                destroyMVCGroup(id)
            }
        }
    }
 
    def saveAction = { evt = null ->
        model.activeDocument.controller.save()
    }
 
    def closeAction = { evt = null ->
        if (model.activeDocument.controller.close()) {
            int index = model.openDocuments.indexOf(model.activeDocument)
            model.openDocuments.remove(index)
            view.documents.removeTabAt(index)
        }
    }
}

There's a fair amount of code but it's all pretty straightforward.  The only thing that warrants further discussion is activeDocumentChanged().  This method is called whenever the active tab in the tabbed pane is changed.  In it, we deactivate() the previously active document and then activate() the new document.  When activating, we pass in the state object I mentioned earlier.  The purpose of the state object is to allow us to use bindings that depend on the active document.  For example, we really only want the save action to be enabled when we have a document open and the document is dirty.  We can't bind directly to the active document's model because as soon as we open or switch to a new document, the binding is no longer correct.  We can, however, bind to the state object and then sync the document's state in the activate() method (or other methods).

The implementation of the Document MVC group is straightforward:
DocumentModel.groovy
import groovy.beans.Bindable

@Bindable class DocumentModel {
    String id
    String name = "Untitled"
    boolean isDirty = false
    DocumentState state
}

DocumentView.groovy
panel(id: 'root') {
    // TODO: put your view implementation here
    button(text: 'Mark Dirty', enabled: bind { !model.isDirty }, 
        actionPerformed: { controller.markDirty() })
    button(text: 'Mark Clean', enabled: bind { model.isDirty }, 
        actionPerformed: { controller.markClean() })
}


DocumentController.groovy
import javax.swing.JOptionPane

/**
 * A skeleton controller for a 'document'.
 */
class DocumentController {
    def model
    def view
    def tabs

    void mvcGroupInit(Map args) {
        tabs = args.tabs
    }

    /**
     * Called when the tab with this document gains focus.
     */
    void activate(state) {
        // save the state object so we can signal the 
        model.state = state
  
        // TODO: sync the model and document state
        state.isDirty = model.isDirty
    }
 
    /**
     * Called when the tab with this document loses focus.
     */
    void deactivate() {
        // forget the state object
        model.state = null
    }
 
    /**
     * Called when the document is initially opened.
     */
    boolean open() {
        // TODO: perform any opening tasks
        return true 
    }
 
    /**
     * Called when the document is closed.
     */
    boolean close() {
        if (model.isDirty) {
            switch (JOptionPane.showConfirmDialog(app.appFrames[0], 
                    "Save changes to '${model.name}'?", "Example", 
                    JOptionPane.YES_NO_CANCEL_OPTION)){
                case JOptionPane.YES_OPTION: return save()
                case JOptionPane.NO_OPTION: return true
                case JOptionPane.CANCEL_OPTION: return false
            }
        }
        return true
    }
 
    /**
     * Called when the document is saved.
     */
    boolean save() {
        // TODO: perform any saving tasks
        markClean()
        return true
    }
 
    /**
     * Marks this document as 'dirty'
     */
    void markDirty() {
        model.isDirty = true
        if (model.state) { model.state.isDirty = true }
        // TODO: update any other model/state properties
        setTitle(model.name + "*")
    }
 
    /**
     * Marks this document as 'clean'
     */
    void markClean() {
        model.isDirty = false
        if (model.state) { model.state.isDirty = false }
        // TODO: update any other model/state properties
        setTitle(model.name)
    }
 
    /**
     * Sets this document's tab title.
     */
    void setTitle(title) {
        int index = tabs.indexOfComponent(view.root)
        if (index != -1) {
            tabs.setTitleAt(index, title)
        }
    }
}

So there it is. You should be able to use this as a starting place for your next Griffon-based text editor, web browser, etc.  I'm personally using in PSICAT to manage the open diagrams:


I zipped up all of the code from this post and made it available for download.

12 comments:

Goldfish said...

That is wicked! Griffon looks nice and sweet! I have only recently started using Groovy, and found I could slap together a very detailed, complex Swing UI with much better ease and clarity. Griffon just takes this idea to the next level!

Steve said...

Very cool article - I love tabbed UIs for most stuff I do.

P.S. Did you mean to say "The purpose of the state object is to allow us to use bindings that depend on the active DOCUMENT"? Cause I was a little lost there.

Josh Reed said...

@Goldfish - be careful, it'll be hard to go back to programming anything else once you get hooked on Groovy :)

@Steve - thanks and good catch on the diagram vs document. I fixed it.

Peter said...

Nice!
How much effort would it be to integrate an open source docking framework ala mydoggy or vl docking?

http://karussell.wordpress.com/2009/10/12/vl-docking-and-other-window-docking-managers-for-java/

Josh Reed said...

@Peter - that's a good question. A quick glance at MyDoggy, it looks like it wouldn't be too hard. Everything is managed by a component (MyDoggyToolWindowManager) so you would just add that to your view under the application() node. The only problem I see at the moment as since there is no builder, your view code wouldn't look as nice as pure SwingBuilder. But that is easily remedied.

So are you going to work up an example or am I? :)

Peter said...

> So are you going to work up an example or am I?

hehe, good question too :-)

The problem is that I already have set up mydoggy within spring rc[1].
And now I read nearly every day about griffon, which seems to be a really nice solution for my purpose.
Some things I would like to know about griffon:
* is property validation supported?
* is griffon DI capable (e.g. with google guice?)
* (a docking framework would be nice :-))
* which size would the smallest app have? (with validation and binding) ... this is particularly interesting for webstart apps ... (is ws possible at all?)
* ... and what about wizards, login dialogs, forms?

Kind regards,
Peter.

[1]
http://karussell.wordpress.com/2008/06/30/spring-rich-client-part-2/

Peter said...

okay, for the wizard I found that
http://blogs.sun.com/geertjan/entry/how_to_incorporate_a_wizard

Andres Almiray said...

@Peter: Griffon's core is really small given that we target webstart and applet too, not just standalone applications.

For that reason there is no DI solution included out of the box (like Spring or Guice). However there will be Spring integration in the near future, after all we'd like to be able to use GORM (the gateway drug ;-)).

All other features can be provided via plugins as well. Here's hoping someone cooks up a validation plugin ;-)

karussell said...

Ah, okay.
What does plugin mean here? Osgi or other technic to load classes dynamically?

Jeff Winkler said...

Great article, thanks!

One caveat.. the writeup is very detailed, but does not explicitly mention the autoShutdown=false in griffon-app/conf/Application.groovy

Raj Alfresco said...

Hi Andres,

Is there any way where we can integrate griffon with grails with user access i.e user login.

User logs with his credentials from Griffon applet. User counts are created at back-end (Grails).

Is it possible to do this can you plz provide a example.

Thanks,
Rajshekar

Raj Alfresco said...

Hi Andres,

Is it possible to integrate griffon with grails with user accounts.

User logs from griffon applet i.e connecting and getting some response from grails.

User credentials are created in grails with Acegi Authentication.