Hyperscala: Getting Started

Last week I did an introduction to Hyperscala and briefly outlined some really cool things it can do. This week I want to slow down a bit and take you through the basics of getting your first application up and running with Hyperscala.

Requirements: Since there is a broad number of IDEs / editors used for working in Scala I won't make any presumptions in this tutorial regarding an IDE. However, I will quickly say that I use IntelliJ and absolutely love it for Scala development. That being said, the only requirements necessary to begin this tutorial is SBT and your editor of choice.

First we need to create our directory structure:

hello-hyperscala/
src/
main/
scala/
hello/
HelloPage.scala
HelloSite.scala
build.sbt

Now lets create our build.sbt file in the hello-hyperscala folder with the following contents:

This is a fairly simplistic build.sbt file with just a few specifics to note. First, we need the Typesafe Repository because one of Hyperscala's dependencies uses Akka Actors. The external repo will not be required once we upgrade to 2.10 but because of some known bugs in 2.10 that undertaking is currently on hold. The second thing to notice is the hyperscala-web dependency. The web sub-project of Hyperscala provides the functionality to create a Website and Webpages. There are several sub-projects in Hyperscala (core, html, javascript, svg, web, ui, examples, and site) but web is the highest level we need and depends on the rest of the functionality we want to use right now.

Next we need to create our actual webpage:

You'll name this HelloPage.scala and put in the hello directory as reflected in the structure above. It's fairly simple what we're doing here. We're extending from Webpage that defines the basic HTML structure (html, head, body) and we can then add content on to it. We set the page title and add "Hello World!" to the body of the page.

Next we need to create a Website. The website is responsible for routing URLs to pages, managing access to the session, and much more. So here's our very basic website:

You'll name this HelloSite.scala and put it in the hello directory with HelloPage.scala. We simply define the val page that represents the URI /hello.html to point to a new HelloPage. The second argument is a function, so every request creates a new instance of HelloPage. We talked about Scope in the previous article but for the purposes of our do-nothing page we just have it create the page, render it, and then die when a request comes in. By default a WebpageResource will automatically add itself to the Website so there's no need to explicitly add it. Lastly, the createSession is responsible for creating a new Session that is used throughout the website across all pages.

Now that we've got all of our code written we simply need to run it. Issue the following command:

You should end up with some output like the following:

Notice the "bound to *:8080" signifies that it is wildcard bound to all IP addresses and on the port of 8080. Now just open up your browser and hit http://localhost:8080/hello.html and you should be greeted with "Hello World!".