Setting up

Maven Repositories

Note: As Sitebricks is in early development, releases are not yet available.

Snapshots

Google Sitebricks is regularly published to the Google snapshot repository at Sonatype. You can browse the snapshot repository here.

To access snapshots you will need to add the following repository to your Maven configuration.

<repository>
  <id>sonatype-google-snapshots</id>
  <name>Sonatype Google Snapshots Repository</name>
  <url>http://oss.sonatype.org/content/repositories/google-snapshots/</url>
  <releases>
    <enabled>true</enabled>
  </releases>
  <snapshots>
     <enabled>true</enabled>
  </snapshots>
</repository>

From there you can add a dependency on Sitebricks in your Maven project.

<dependency>
  <groupId>com.google.sitebricks</groupId>
  <artifactId>sitebricks</artifactId>
  <version>0.8-SNAPSHOT</version>
</dependency>

At the time of writing, 0.8-SNAPSHOT is the most recent development version.

Build from source

To build from source you will need Maven and a Subversion client.

First check out the sources:

svn checkout http://google-sitebricks.googlecode.com/svn/trunk/ google-sitebricks

Now install Sitebricks to your local repository.

cd google-sitebricks
mvn install

If everything is successful, you should have a copy of Sitebricks installed to your local repository.

What next?

You will place your compiled classes inside the WEB-INF/ directory in another dir called classes. You may place html templates side by side with the classes OR in the root (where Example.html resides) of the webapp as you like.

We'll take the following steps to write a web application in Sitebricks:

• Create a Guice injector, configuring Sitebricks and Guice Servlet
• Create a page object in Example.java to back an HTML template called Example.html
• Customize the page to give it some dynamic behavior

Configuring Sitebricks

First let's create and configure our Guice injector. This is done via a ServletContextListener that runs once right after the webapp is deployed. Let's call this MyGuiceCreator and place it in the org.example.web package:

package org.example.web;

public class MyGuiceCreator extends GuiceServletContextListener {
    
    @Override
    public Injector getInjector() {
        return Guice.createInjector(new SitebricksModule());
    }
}

This tells Guice to route all incoming requests to Sitebricks (if Sitebricks cannot handle them, they will be handed back to the normal servlet pipeline as per web.xml). This also lets us take advantage of Guice's powerful web-scopes functionality.

OK, so far so good. Now we need to tell Sitebricks what packages to scan for pages. This is done by adding another step to MyGuiceCreator:

    @Override
    public Injector getInjector() {
        return Guice.createInjector(new SitebricksModule() {
            @Override
            protected void configureSitebricks() {
                // scan class Example's package and all descendants
                scan(Example.class.getPackage());
            }
        });
    }

Now register this and GuiceFilter in your web.xml. It should look as follows:

    <filter>
        <filter-name>webFilter</filter-name>
        <filter-class>com.google.inject.servlet.GuiceFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>webFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

    <listener>
        <listener-class>org.example.MyGuiceCreator</listener-class>
    </listener>

My First Web Page

Now let's create class Example that we just talked about:

@At("/")
public class Example {
    private String message = "Hello";

    public String getMessage() { return message; }
}

The @At annotation tells Sitebricks to expose this web page at url "/". So if you deploy to localhost at port 8080 and visit URL http://localhost:8080/ in a browser, page Example will appear.

Note: This annotation is detected by scanning packages. If you don't like this, you can use the alternate modular configuration approach

The HTML template for Example was already sitting the zip archive root. This looked as follows:

<html>
<body>
    @ShowIf(true)
    <p>${message} from Sitebricks!</p>
</body>
</html>

This is a fairly simple template that renders some text inside a <p> (paragraph) tag. The expression ${message} is evaluated at runtime against an instance of Example. In our case, this evaluates to the string: "Hello".

The other interesting part about this template is a widget annotation, named @ShowIf. This tells Sitebricks to convert the <p> tag into a brick with some dynamic behavior (in this case, shown if an expression evaluates to true). The expression passed to @ShowIf(true) is always true (!), so the <p> tag and its contents are always rendered.

Adding Some Behavior

Let's make this example a bit more interesting. First, let's make @ShowIf take a boolean variable read from the page object:

    @ShowIf(appear)
    <p>${message} from Sitebricks!</p>

    ...

And add it as a field to class Example:

@At("/")
public class Example {
    private boolean appear = true;
    private String message = "Hello";

    ...
}

Note: get + set methods for each field are needed if reading and writing to them from the template. TODO: This will change shortly when we update MVEL to read @Visible fields directly.

Now, the page still looks the same but the behavior is more dynamic.

Even more behavior ;)

Now let's make this user-controllable by placing a link on the page:

    <a href="?appear=${!appear}">show/hide</a>

    @ShowIf(appear)
    <p>${message} from Sitebricks!</p>

    ...

The link show/hide causes a browser to request the same page but with a parameter appear. By placing the expression ${!appear} next to it, we toggle the boolean value of appear in the link. Now each time the page is requested, Sitebricks will bind the value in the query string to the field appear in Example.

Now run your app and try clicking the link.

That's it! Try the five minute tutorial to see how to create your own custom bricks and handle HTTP events.