Quick Start

Starting up a new grails project with magnolia support is quite simple and quick. So let's walk through the steps and get you going! Download the latest version of the plugin from the downloads section here on github to start with. Then just run a few commands to create the project and install our plugin

$ grails create-app awesomesite
| Created Grails Application at /Users/ake/Devel/workspace/awesomesite
$ cd awesomesite/
$ grails install-plugin ~/Downloads/grails-maglev-0.3.3.zip 
| Plugin installed.

Now we have a project with everything we need, but we should do some setup first to get it all right from the start.

We unfortunately need to remove the resource-plugin that Grails 2 installs by default. It's a nice plugin and all, and it works just fine with magnolia, but magnolia doesn't work well when the resources-plugin steals a few urls that magnolia wants. We'll fix that at some point.

So just comment out the line that says runtime ":resources:1.1.5" in BuildConfig.groovy.

Now we can actually startup the app with your favorite command:

grails run-app

Magnolia will start up and instruct you to go to the update-page to bootstrap a new JCR-repository. Just go there and click the big "Start install.."-button and after a while you can click "Startup Magnolia...".

You basically have a magnolia instance running in a grails up now. Congratulations!. It only gets better.

You have a few choices at this point how you can set things up, but we have a recommended solution. Open up UrlMappings.groovy and change the basic url-mapping so it doesn't catch all urls from magnolia. There is a lot of fun things you can do here but we'll focus on that on a separate page. We suggest you change it from this:

"/$controller/$action?/$id?"{
    constraints {
    // apply constraints here
    }
}

to this:

"/g/$controller/$action?/$id?"{
    constraints {
    // apply constraints here
    }
}

You can also add this if you want to use the css, images and js-folders in grails like before:

"/css/*"(controller: "css")
"/images/*"(controller: "images")
"/js/*"(controller: "js")

Notice the "g" there. It prefixes all the grails pages to a base url of /g. Now just go to the uri .magnolia and start creating templates and paragraphs since it all works just fine now(probably). If you are accustomed to Magnolia Blossom which is the main library Maglev is based on, you can probably figure out how to create templates and paragraphs. The only thing you'll be surprised(and maybe a bit amazed?) by is that you can basically change anything without restarting the server(as it should be in grails).

Creating templates is done by creating a controller and adding a simple blossom annotation called @Template. A quick example of a template with areas.

@Template(id = "grailsModule:pages/demoTemplate", title = "Demo template")
class DemoTemplateController {

def index = {
    render view: "demoTemplate"
}

@TabFactory("Content")
public void propertiesDialog(TabBuilder builder) {
    builder.addEdit("title", "Title", "");
}

@Area("mainArea")
@Inherits
@AvailableComponentClasses([SomeContentController.class,
TextController.class, PersonsController.class,
PageLinkController.class])
static class MainAreaController {

    def index = {
        render(view: "/demoTemplate/mainArea")
    }

    @TabFactory("Info")
    public void propertiesDialog(TabBuilder builder) {
    }

}

@Area("rightColumn")
@Inherits(components = ComponentInheritanceMode.ALL)
@AvailableComponentClasses([SomeContentController.class,
TextController.class])
static class RightColumnController {

    def index = {
        render(view: "/demoTemplate/rightColumn")
    }

    @TabFactory("Info")
    public void propertiesDialog(TabBuilder builder) {
        builder.addEdit("test","Test","")
    }
}
}

If you want to know more about how to use the blossom-annotations you should go to the Magnolia Blossom documentation site and read up. Basically everything there works, but you shouldn't need to mess around in xml create modules or anything like that(we've done all that for you). Just focus och temlates and paragraphs and you'll do fine.

To learn how to do the view-code of templates and paragraphs you should probably take a look at Magnolias documentation which is excellent. Here you can learn to use magnolia if you're new to it, and you can probably find quite a few modules you want there too.

Some things to think about when getting started. A paragraph or template only uses the index-action to render the page but the other actions will be available through any url mapped in UrlMappings.groovy. Important always specify a view-name for your Components. If not the index.gsp of whatever page they are put in is rendered instead resulting in an infinite loop.

Layouts are still very useful, but they have no Magnolia context which means you can't access page-data without going through the systemcontext or something similar which we only recommend for people who are very familiar with magnolia.