Up to this point we've talked about the high-level features of Hyperscala and have gone through a simple Hello World example, but today we're going to write a real application to show a fairly simple real-world web application.

The real-world application we're going to write today is a chat example. This will utilize real-time messaging, cross-session interaction, abstraction from the user-interface through DynamicContent, and much more.

We will be building upon concepts we've already discussed in the past two posts, so if you haven't already read them I would recommend doing that first. I'm going to skip over the project setup and even the website configuration and focus solely on the webpage for the chat in this post.

The first thing we need to do is to create our webpage class and for the purposes of this tutorial we'll call it ChatExample. As we can remember from previous discussion the basic setup for a webpage simply requires extending from org.hyperscala.web.site.Webpage:

Pretty simple so far. Next we are going to leverage existing HTML for the user-interface rather than writing it all in Hyperscala. This is generally the preferred route when you have a disconnect from the designer and the developer and allows for a very clean separation of duties.

The first HTML file is chat.html. It defines the form and layout of the page:

This should be put in the src/main/resources path in your project. Now, DynamicContent requires the HTML to be presented to it as a String, so we need to load and cache that HTML file:

That will load in the HTML file and store it as a String for usage in each page instance. Now lets create a DynamicContent instance in our page to load that HTML for usage and add it to the body of the page:

Now that we have the DynamicContent loaded we can extract any HTML elements we want to modify or listen to:

If you look back at the HTML file you'll see that the Strings being supplied reference the HTML elements by id for lookup and loading. After these elements are loaded we can then modify them or even introspect the existing data from the HTML. Technically we could just load the entire HTML file and parse it as a Hyperscala structure, but that would be a waste of resources and add unnecessary complexity. By using DynamicContent we can reference only the things we care about in existing HTML and the design can change over time without any necessity of the Scala code changing (so long as those elements remain of the same type and id).

Next we need to add some real-time support to these elements so we can listen for changes and clicks:

The require call is necessary to make sure we have support for Realtime messaging. This is a Module that provides two-way communication between the server and client preferring WebSockets and falling back to long-polling AJAX. The other three lines simply connect JavaScriptEvent to the client-side corresponding JavaScript events. This will intercept client-side events of the specified type and fire them on the server as well. Note that this is simply making that occur, we now need to actually listen for the changes we're interested in:

The above code listens for changes to chatName and updates the internal nickname. This will allow you to distinguish between who is messaging. Second, we add a ClickEvent listener to the submit button to send the message. Now lets see the body of these methods:

This method is rather simple. It calls off to our companion object calling its sendMessage method passing your nickname and the message you typed. Next it clears the value of the TextArea. Finally, it uses jQuery to request focus back to the TextArea. We'll cover the ChatExample.sendMessage method in a minute.

First we add a nickname property to our page instance so we can reference the currently accepted nickname for this user. The updateNickname method first checks to see if the chatName has anything entered. If it doesn't then it assigns the name 'guest'. Next it calls off to ChatExample.generateNick with the nickname to verify that an existing nickname isn't already present. Finally, we assign the chatName input's value to be the newly assigned nickname.

Now we need a HTML representation of each chat entry:

We need to load the HTML again, so we add another val representing the HTML as a String in our companion object below Main:

Now we create a custom class representing an individual chat entry:

We can simply instantiate this and add it to our messages div for each message. Notice that this is very similar to our previous use of DynamicContent except this time we are extending it instead of simply instantiating it. Also, notice the use of reId = true during load of the name and body divs. This is necessary when using an item multiple times on a page as you'll end up with duplicate HTML ids in the code if you don't. When we specify reId = true that will simply assign a new unique id to the element at the time it loads it so each time it will be different.

Lets look at the rest of the content of our companion object now:

There's quite a lot going on in the above code although hopefully the majority is fairly easily understood. First we see we're keeping a history of all the messages so when a new person joins they get to see what's already been said. The instances method gives us a peek into the powerful session framework to look up all of the ChatExample pages across all sessions on the site. The generateNick method takes the supplied nickname and checks to see if it's already in use. If it is then it will add an increment to the end until an available nickname is found. Finally, sendMessage broadcasts the message to all pages adding a ChatEntry in their context. It is necessary to mention context at this point. For many of the underlying features of Hyperscala events and other information are localized to a page so in order to invoke changes across multiple pages we must work within that pages' context. As you can see it is incredibly easy to contextualize to the page by simply calling the context method and passing a function to be invoked within the context.

We have covered a very broad scope of functionality in this post but hopefully it was all clear and understandable. The end result should look like this:

All of the source referenced in this tutorial can be found in the GitHub repository:

• ChatExample.scala
• chat.html
• chat_entry.html

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!".

It has been well over a year since my last post. In 2011 I went to work for Overstock and moved to Utah. Life got busy and I worked during the day and when I had time I programmed on Sgine at night (http://www.sgine.org).  In February of 2012 I left Overstock and moved back to Oklahoma to start my own company writing software for businesses around the world (http://www.outr.com).  Life got busier. :)  Now, here it is, 2013 and I've resolved to blog at least once a week on the many amazing things I get to do.

Today I want to introduce you to Hyperscala (https://github.com/darkfrog26/hyperscala).  It's a web framework I've been working on for a few months in Scala to provide type-safe HTML, CSS, SVG, and JavaScript to developers.  The first question out of my mouth when I hear another person talking about another web framework is, "Why another web framework?" and I've asked myself that question many times both before creating and since creating it. Each time I come up with the same answer, and one that by the end of this introduction I hope you all will agree: It was necessary.

First, as any good introduction should, I'll show you a little Hello World example:

Obviously this is a very simplistic example and simply sets the page title and adds a String to the body of the page. If you'd like a far more detailed example of the bare-metal type-safe HTML writing capabilities I would recommend looking at the TodoMVC example.

This is all well and good if there are no designers and you prefer working in Scala to HTML and CSS. Unfortunately, this is not always the case and the goal of Hyperscala is not to make presumptions on how it will be used, so we try to accommodate everyone.

So, what do you do when you have existing HTML that needs to be brought into your project?

The first option is to convert it into Scala using the handy-dandy code conversion utility in Hyperscala. The code in the TodoMVC above was generated using this neat little tool. This works great when you have a snippet or large amount of HTML that needs to be converted into code to work with. For more information about this tool take a look HTMLToScala.scala. You can run the main method to get a nice visual file selector and tell it where to output the resulting Scala source file. This route works great until you need a designer to make a change to your HTML and they are unwilling to edit your Scala source files. ;)

This brings us to the second option. This is sort of a hybrid approach and I believe really gives you the best of both worlds in the case that you have externally maintained HTML and CSS that needs dynamic content integration. I created the DynamicContent trait and utilization of this trait allows you to dynamically import HTML and load only the elements you want to work with. See the following HTML snippet:

In this example we care about the two inputs and the button but we don't care about the rest of the content. So, utilizing DynamicContent we create SimpleDynamicForm:

This is a bit more elaborate than is necessary, but shows some of the power of PowerScala Properties in the mix with Hyperscala. Look specifically at the line where the button is loaded:

DynamicContent finds the button by its id in the dynamic.html file and loads it as a Hyperscala tag.Button and any changes I make to the loaded button are reflected at render time. I could have simply loaded the name and age inputs as well, but using bind I cross-bind the value of the input to their reflected field names in the Person class. This means that when I change the value of the inputs it updates the 'person' Property to reflect the change. DynamicContent.bind introduces two other features of Hyperscala we need to briefly discuss: Modules and Realtime.

Modules provide the ability to define shared functionality between applications, components, features, etc. For example, a big problem in web site development is avoiding multiple includes of jQuery. In Hyperscala there is a built-in module for jQuery that any tag or page that needs to make use of can simply 'require' in their code. For example:

The above code requires jQuery be present by referencing the jQuery Interface and passing a default implementation of jQuery182. This will inject jQuery182 if no other implementation of jQuery is specifically provided before render of the page. The require method may be invoked with just an Interface (and an exception will be thrown at render time if no implementation has been provided), an Interface and a default Module (as seen above), or just a Module (at render time the module will be used if it is the highest version number provided for the same module name).

Modules are extremely easy to write. For example, the jQuery182 module looks like this:

Every Module needs a name and version. If they implement an Interface they can override the implements method to provide a list of those they implement (see we are implementing jQuery interface). The init method is invoked the very first time the module is used within a Website. This allows one-time actions to be taken like registering a JavaScript resource to a path as seen above. The load method is invoked at first render of every page that requires this module. This gives the module the ability to interact with the page prior to rendering to the client. As you can see in the jQuery182 module we simply add a tag.Script instance to the head of the page.

Realtime is actually a Module like we just discussed, but an extremely powerful one. This allows two-way communication between the client and server via WebSockets falling back to AJAX polling. It is incredibly easy to use as seen below:

That's all that's necessary in order to allow cross-communication to a loaded webpage. Now any changes to the HTML after page load will automatically synchronize to the browser. Further, you can begin listening to JavaScript events on the server by specifying what events you want to be sent down. For example:

This is an extremely simple example of hooking up a button that sends click events to the server. Notice on line 12 the use of "event.click". All HTML tags expose JavaScript events via the "event" object. In this case we are assigning the result of calling JavaScriptEvent() that interacts with Realtime to send the event down to the server. We could do something like this instead if we wanted just basic JavaScript:

Notice on line 14 we add a synchronous listener to handle a ClickEvent (the JavaScript event that is thrown when clicked). When clicked we simply log that the button has been clicked to the server-side console.

This has been a pretty long post, but barely scratches the surface of what Hyperscala can do. My goal is to spend the next few weeks blogging about the features and capabilities of Hyperscala and get into some even more powerful features of the framework. Again, the biggest advantage of Hyperscala is that at its core it is simply a webpage rendering framework. Everything else is just icing on the cake. This means anyone that has other needs for the features of Hyperscala can simply build their own abstraction layer on top to provide whatever they want.

I've spent most of my career developing in Java for the web. I've used the full range of frameworks: Servlets, JSPs, Struts, JSF, Wicket, and dozens more. Early in my career I did a lot of Swing development. Now I grant there are a lot of inherent problems there as well, but nowhere near the painfulness of web development. At least in Swing you just have to know Java. In the majority of web frameworks you have to know HTML, CSS, JavaScript, whatever your server-side technology is, and then you have to deal with the client-server model and even stateful / stateless decisions. It's such a mess and although frameworks like Vaadin do a phenomenal job of removing much of that pain, the norm in the Java world is still focused towards a complicated web where you have to deal with cross-browser compliance, HTML 5 compliance, and a slew of crappy languages most developers would rather gouge their eyes out than have to stare at all day long.

I've recently been looking at templating frameworks for larger front-facing web sites as larger organizations like where I work have entire departments to create the HTML and design the pages and then the developers have to hook up the dynamic elements. We've been talking about moving more toward Wicket, but as I've been using Wicket more and more I find myself liking it less and less. I dislike the one-to-one mapping that has to take place between the template and the Java code first of all. Secondly, the more complex features are not at all intuitive (at least to me...I'm sure some think it's the most rational thing ever and will readily tell me so). However, I very much like the concept that designers can work completely independently of the developers and can create the markup and even test it with bogus information that is replaced at runtime with production content. To that end I started thinking about what I could see as a better templating system. I like templating frameworks like Mustache, but unfortunately for many cases it's just not powerful enough. After further thought I came up with a similar concept to Wicket that would parse through XHTML content as XML and then provide components that would manipulate those Elements based on the HTML "id" associated. This means that designers assign ids to their elements (like many would already for CSS and JavaScript to access) and then the developer can opt to interact with these elements when the page is being rendered.

For this prototype I opted to use Scala as native XML support made it so much easier. So I started with the idea of a "Component" with the simple concept of Element to Element conversion:

import xml.Elem

trait Component {
  def render(elem: Elem): Elem
}

I then created a couple simple implementations of the Component:

import xml.{Text, Elem}

class Label(textFunction: () => String) extends Component {
  def this(text: String) = this(() => text)

  def render(elem: Elem) = {
    val text = textFunction() match {
      case null => ""
      case s => s
    }
    Elem(elem.prefix, elem.label, elem.attributes, elem.scope, Text(text))
  }
}

import xml.Elem

class Content(content: Elem) extends Component {
  def render(elem: Elem) = Elem(elem.prefix, elem.label, elem.attributes, elem.scope, content)
}

The Label component simply replaces the content of the element with the supplied text (offering function support for more advanced usage) and the Content component even more simply just replaces the content of the element with the passed content.

Now I needed a way to map the Components to ids and render the XML:

import component.Component
import xml.{Node, Elem}
import xml.transform.{RuleTransformer, RewriteRule}
import java.lang.ThreadLocal

object Xemplate {
  private val components = new ThreadLocal[Map[String, Component]]

  def apply(components: Map[String, Component], elem: Elem): Node = {
    this.components.set(components)
    val result = apply(elem)
    this.components.set(null)
    result
  }

  protected[xemplate] def apply(elem: Elem): Node = {
    val transformer = new RuleTransformer(new Rewriter(components.get()))
    transformer(elem)
  }
}

class Rewriter(components: Map[String, Component]) extends RewriteRule {
  override def transform(n: Node) = n match {
    case elem: Elem => convert(elem)
    case node => node
  }

  def convert(elem: Elem) = {
    val id = elem.attribute("id").map(ns => ns.text).getOrElse("")
    components.get(id) match {
      case Some(component) => component.render(elem)
      case None => elem
    }
  }
}

Fortunately Scala has some really powerful features to do exactly this. The RuleTransformer and RewriteRule classes provide the majority of the functionality I need immediately out of the box. I simply take in a Map of id to Component mapping along with the XML to process and when I find an element that has a mapped id I simply replace it with the Component's render result. I called it Xemplate just because I was being lazy and it's XML templating.

At this point I needed a way to simplify bringing this together into an individual page rendering so I created a Page class:

import component.Component
import xml.Elem

class Page(xhtml: Elem) {
  private var components = Map.empty[String, Component]

  def register(id: String, component: Component) = components += id -> component

  def render() = Xemplate(components, xhtml)
}

Now I have ability to instantiate a Page, register Component instances to ids, and then render to get the modified XML. Lets see an example of this in action:

val xhtml = 
  
      
  
  
Yes, I can simply inject XML!

Lets get a little bit more complicated though. One of the most painful things in a framework like this is often cycling over a list of elements and trying to populate them onto the page. In Wicket this is relatively effectively done, but you often end up with a lot of anonymous subclasses layering down so you have a reference to the current item being rendered in the list. I took a different approach to this by creating what I called an EntryHolder that is responsible for holding the current instance being iterated over:

import java.lang.ThreadLocal

class EntryHolder[T] extends Function0[T] {
  val current = new ThreadLocal[T]

  def apply() = current.get()
}

As you can see this is an extremely simple wrapper over ThreadLocal. For the purposes of testing I could have just had a var, but if we ever want to handle a web environment we would presumably have several threads handling requests at the same time and obviously would want to run the risk of transferring one pages' content to someone elses' page.

Now we need to create our Sequence class that allows us to iterate over items:

import xml.Elem
import xemplate.{Xemplate, EntryHolder}

class Sequence[T](items: Seq[T], holder: EntryHolder[T]) extends Component {
  def render(elem: Elem) = {
    val content = for (item <- items) yield {
      holder.current.set(item)
      for (n <- elem.child) yield n match {
        case elem: Elem => Xemplate(elem)
        case node => node
      }
    }
    Elem(elem.prefix, elem.label, elem.attributes, elem.scope, content.flatMap(s => s): _*)
  }
}

Though more complex than Label or Content, it's still relatively simple. We iterate over the items, set the current item to the EntryHolder, and then ask Xemplate to process the child elements so they can be templatized as well.

Lets see an example of this:

val xhtml = 
  

      

  


val page = new Page(xhtml)
val names = List("Alan", "Brad", "Chris", "Don", "Edward")
page.register("names", new Sequence(names, NameHolder))
page.register("name", new Label(NameHolder))
println(page.render())

object NameHolder extends EntryHolder[String]

I simply instantiate my Page with the XHTML content, create a List of names, register "names" to a new Sequence with the names list and NameHolder, then I register "name" to a new Label with NameHolder as the text function. Notice above that EntryHolder extends Function0[T] allowing us to pass it in as a String function to generate the String. What this does is the function is called per iteration on the names list and NameHolder has the current name associated and returns it. This keeps us from having to deal with layering our components for visibility by creating companion objects that are visible for a specific function.

The resulting XHTML should look like this:

      

          
Alan
      
          
Brad
      
          
Chris
      
          
Don
      
          
Edward
      
    

That's about it. Again, where possible I would still recommend using something like Vaadin as it keeps you from dealing with the majority of the evils of the web, but I think this little example demonstrates an extremely simple and fast (performance tests on a 1 meg XML file averaged around 25ms per render) templating system that doesn't have to overcomplicate or obscure development. If anyone is interested in turning this into a full-fledged project feel free to do so and build on it. I would appreciate the credit, but the code above is free to use for anything you see fit.

I was pretty exclusively a Java developer for twelve years before making the switch to Scala. Yes, it was difficult to learn some of the syntactical differences, but now that I have I don't want to turn back. No, this is not a baited question to get a flame-war going, but an honest attempt to get some real feedback by those that believe Scala is more difficult than Java.

Let me lay some ground-rules before we get this discussion going though. First, complex topics in Scala are complex, there's no debate there, but that doesn't make Scala more difficult than Java, there are just more possibilities to what you can accomplish. I say that the argument cannot be made that Scala is more complex if there is not a side-by-side comparison to Java code that is much simpler to understand. This means we have to leave the advanced concepts of implicit conversions, multiple inheritance, and so much more that Scala can do, but are features that bring it beyond the capabilities of Java. Yes, of course you can make an argument that in switching to a language like Scala you will eventually run into these scenarios, but I am speaking purely of the introductory programmer and the "difficulties" between Scala's syntax versus Java's.

Now, can someone give me a scenario of code in Java that would be more complicated to understand in Scala?

I would consider myself pretty competent with Scala at this point, but there is still so much I have yet to learn. Something I always used to do in Java was to work my way one class at a time through the JavaDocs of the language I am attempting to do with Scala now as well.

I've just run across the Either class in the ScalaDocs and really like the idea.


The idea is that you may have two different return types that may result from one method. Classically that is solved with all sorts of hackery or returning the common superclass to the two and then doing an instanceof check, but in Scala the Either class provides a much more elegant solution:

object Test {
 def main(args: Array[String]): Unit = {
  numOrString("5") match {
   case Left(s) => println("String: " + s)
   case Right(i) => println("Integer: " + i)
  }
 }
 
 def numOrString(s: String) = {
  try {
   Right(s.toInt)
  } catch {
   case exc: NumberFormatException => Left(s)
  }
 }
}

I'm not really sure how practical this example I wrote is, but my method "numOrString" takes in a String and attempts to convert it to an Int. If it can return an Int it does so or it returns a String. By use of the Left and Right subclasses of Either you can define which type of result you are sending back. Finally, with Scala's awesome matching you can easily determine which type of result you got.

Programmer ADD: The (often external) push to work on many projects at a time rather than focusing on and accomplishing one task at a time.

I currently work for a small company and unfortunately that means I'm constantly being pulled in many directions. There just aren't enough people to do everything, but lately I've started noticing the effect this has had on the quality of work I do. Since I'm constantly pushing to finish up what I'm working on in order to start on the next project on my plate I often don't take the time really necessary to quality check and test the functionality I've added or changed. This results in work that is not as well thought out as it should be, and not as well executed as I would like.

I can definitely point a finger to my boss for pushing the amount of work I have to accomplish in a given time-frame, but realistically even when I've worked for larger companies this has still been more-or-less true of all development work I've done. As developers we're constantly being pushed for deadlines and getting bugs fixed. This might be great from a management perspective on "work accomplished", but I think this really has a negative impact on the company in the long-term as we aren't really given the time necessary to nurture our projects to write solid and well-tested code, but just enough to get the job done. The result? Code that eventually has to be repaired or updated at twice the effort as it would have taken to do it right in the first place.

This is basically just a rant as I see the quality of my work declining as deadlines push me to do more than I can safely accomplish, but it also raises my curiosity if this is something most other developers deal with as well?